Skip to content

mattpocock/sandcastle

BranchesTags

Repository files navigation

Sandcastle

What Is Sandcastle?

A TypeScript library for orchestrating AI coding agents in isolated Docker containers:

  1. You invoke agents with a single sandcastle.run().
  2. Sandcastle handles building worktrees and sandboxing the agent.
  3. The commits made on the branches get merged back.

Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents.

Prerequisites

Quick start

  1. Install the package:
npm install @ai-hero/sandcastle
  1. Run sandcastle init. This scaffolds a .sandcastle directory with all the files needed.
npx sandcastle init
  1. Edit .sandcastle/.env and fill in your default values for ANTHROPIC_API_KEY
cp .sandcastle/.env.example .sandcastle/.env
  1. Run the .sandcastle/main.ts (or main.mts) file with npx tsx
npx tsx .sandcastle/main.ts
// 3. Run the agent via the JS API
import { run, claudeCode } from "@ai-hero/sandcastle";

await run({
  agent: claudeCode("claude-opus-4-6"),
  promptFile: ".sandcastle/prompt.md",
});

API

Sandcastle exports a programmatic run() function for use in scripts, CI pipelines, or custom tooling.

import { run, claudeCode } from "@ai-hero/sandcastle";

const result = await run({
  agent: claudeCode("claude-opus-4-6"),
  promptFile: ".sandcastle/prompt.md",
});

console.log(result.iterationsRun); // number of iterations executed
console.log(result.commits); // array of { sha } for commits created
console.log(result.branch); // target branch name

All options

import { run, claudeCode } from "@ai-hero/sandcastle";

const result = await run({
  // Agent provider — required. Pass a model string to claudeCode().
  agent: claudeCode("claude-opus-4-6"),

  // Prompt source — provide one of these, not both:
  promptFile: ".sandcastle/prompt.md", // path to a prompt file
  // prompt: "Fix issue #42 in this repo", // OR an inline prompt string

  // Values substituted for {{KEY}} placeholders in the prompt.
  promptArgs: {
    ISSUE_NUMBER: "42",
  },

  // Maximum number of agent iterations to run before stopping. Default: 1
  maxIterations: 5,

  // Worktree mode for sandbox work. Defaults to { mode: 'temp-branch' }.
  // { mode: 'none' } — bind-mount host working directory directly (no worktree).
  // { mode: 'temp-branch' } — create a temp worktree, merge back.
  // { mode: 'branch', branch } — create a worktree on an explicit branch.
  worktree: { mode: "branch", branch: "agent/fix-42" },

  // Docker image used for the sandbox. Default: "sandcastle:<repo-dir-name>"
  imageName: "sandcastle:local",

  // Display name for this run, shown as a prefix in log output.
  name: "fix-issue-42",

  // Lifecycle hooks — arrays of shell commands run sequentially inside the sandbox.
  hooks: {
    // Runs after the worktree is mounted into the sandbox.
    onSandboxReady: [{ command: "npm install" }],
  },

  // Host-relative file paths to copy into the worktree before the container starts.
  copyToSandbox: [".env"],

  // How to record progress. Default: write to a file under .sandcastle/logs/
  logging: { type: "file", path: ".sandcastle/logs/my-run.log" },
  // logging: { type: "stdout" }, // OR render an interactive UI in the terminal

  // String (or array of strings) the agent emits to end the iteration loop early.
  // Default: "<promise>COMPLETE</promise>"
  completionSignal: "<promise>COMPLETE</promise>",

  // Idle timeout in seconds — resets whenever the agent produces output. Default: 600 (10 minutes)
  idleTimeoutSeconds: 600,
});

console.log(result.iterationsRun); // number of iterations executed
console.log(result.completionSignal); // matched signal string, or undefined if none fired
console.log(result.commits); // array of { sha } for commits created
console.log(result.branch); // target branch name

createSandbox() — reusable sandbox

Use createSandbox() when you need to run multiple agents (or multiple rounds of the same agent) inside a single sandbox. It creates the worktree and container once, and you call sandbox.run() as many times as you need. This avoids repeated container startup costs and keeps all runs on the same branch.

Use run() instead when you only need a single one-shot invocation — it handles sandbox lifecycle automatically.

Basic single-run usage

import { createSandbox, claudeCode } from "@ai-hero/sandcastle";

await using sandbox = await createSandbox({
  branch: "agent/fix-42",
});

const result = await sandbox.run({
  agent: claudeCode("claude-opus-4-6"),
  prompt: "Fix issue #42 in this repo.",
});

console.log(result.commits); // [{ sha: "abc123" }]

Multi-run implement-then-review

import { createSandbox, claudeCode } from "@ai-hero/sandcastle";

await using sandbox = await createSandbox({
  branch: "agent/fix-42",
  hooks: { onSandboxReady: [{ command: "npm install" }] },
});

// Step 1: implement
const implResult = await sandbox.run({
  agent: claudeCode("claude-opus-4-6"),
  promptFile: ".sandcastle/implement.md",
  maxIterations: 5,
});

// Step 2: review on the same branch, same container
const reviewResult = await sandbox.run({
  agent: claudeCode("claude-sonnet-4-6"),
  prompt: "Review the changes and fix any issues.",
});

Commits from all run() calls accumulate on the same branch. The sandbox container stays alive between runs, so installed dependencies and build artifacts persist.

Automatic cleanup with await using

await using calls sandbox.close() automatically when the block exits. If the worktree has uncommitted changes, it is preserved on disk; if clean, both container and worktree are removed.

Manual close() with CloseResult

const sandbox = await createSandbox({ branch: "agent/fix-42" });
// ... run agents ...
const closeResult = await sandbox.close();
if (closeResult.preservedWorktreePath) {
  console.log(`Worktree preserved at ${closeResult.preservedWorktreePath}`);
}

CreateSandboxOptions

Option Type Default Description
branch string — Required. Explicit branch for the worktree
imageName string sandcastle:<repo-dir-name> Docker image name
hooks object — Lifecycle hooks (onSandboxReady) — run once at creation time
copyToSandbox string[] — Host-relative file paths to copy into the worktree at creation time

Sandbox

Property / Method Type Description
branch string The branch the worktree is on
worktreePath string Host path to the worktree
run(options) (SandboxRunOptions) => Promise<SandboxRunResult> Invoke an agent inside the existing sandbox
close() () => Promise<CloseResult> Tear down the container and worktree
[Symbol.asyncDispose] () => Promise<void> Auto teardown via await using

SandboxRunOptions

Option Type Default Description
agent AgentProvider — Required. Agent provider (e.g. claudeCode("claude-opus-4-6"))
prompt string — Inline prompt (mutually exclusive with promptFile)
promptFile string — Path to prompt file (mutually exclusive with prompt)
promptArgs PromptArgs — Key-value map for {{KEY}} placeholder substitution
maxIterations number 1 Maximum iterations to run
completionSignal string | string[] <promise>COMPLETE</promise> String(s) the agent emits to stop the iteration loop early
idleTimeoutSeconds number 600 Idle timeout in seconds — resets on each agent output event
name string — Display name for the run
logging object file (auto-generated) { type: 'file', path } or { type: 'stdout' }

SandboxRunResult

Field Type Description
iterationsRun number Number of iterations executed
completionSignal string? The matched completion signal string, or undefined if none fired
stdout string Combined agent output from all iterations
commits { sha }[] Commits created during the run
logFilePath string? Path to the log file (only when logging to a file)

CloseResult

Field Type Description
preservedWorktreePath string? Host path to the preserved worktree, set when it had uncommitted changes

How it works

Sandcastle uses a worktree-based architecture for agent execution:

  • Worktree: Sandcastle creates a git worktree on the host at .sandcastle/worktrees/. The worktree is a just a normal git worktree.
  • Bind-mount: The worktree directory is bind-mounted into the sandbox container as the agent's working directory. The agent writes directly to the host filesystem through the mount.
  • No sync needed: Because the agent writes directly to the host filesystem, there are no sync-in or sync-out operations. Commits made by the agent are immediately visible on the host.
  • Merge back: After the run completes, the temp worktree branch is fast-forward merged back to the target branch, and the worktree is cleaned up.

From your point of view, you just run sandcastle.run({ worktree: { mode: 'branch', branch: 'foo' } }), and get a commit on branch foo once it's complete. All 100% local.

Prompts

Sandcastle uses a flexible prompt system. You write the prompt, and the engine executes it — no opinions about workflow, task management, or context sources are imposed.

Prompt resolution

You must provide exactly one of:

  1. prompt: "inline string" — pass an inline prompt directly via RunOptions
  2. promptFile: "./path/to/prompt.md" — point to a specific file via RunOptions

prompt and promptFile are mutually exclusive — providing both is an error. If neither is provided, run() throws an error asking you to supply one.

Convention: sandcastle init scaffolds .sandcastle/prompt.md and all templates explicitly reference it via promptFile: ".sandcastle/prompt.md". This is a convention, not an automatic fallback — Sandcastle does not read .sandcastle/prompt.md unless you pass it as promptFile.

Dynamic context with !`command`

Use !`command` expressions in your prompt to pull in dynamic context. Each expression is replaced with the command's stdout before the prompt is sent to the agent.

Commands run inside the sandbox after the worktree is mounted and onSandboxReady hooks complete, so they see the same repo state the agent sees (including installed dependencies).

# Open issues

!`gh issue list --state open --label Sandcastle --json number,title,body,comments,labels --limit 20`

# Recent commits

!`git log --oneline -10`

If any command exits with a non-zero code, the run fails immediately with an error.

Prompt arguments with {{KEY}}

Use {{KEY}} placeholders in your prompt to inject values from the promptArgs option. This is useful for reusing the same prompt file across multiple runs with different parameters.

import { run } from "@ai-hero/sandcastle";

await run({
  promptFile: "./my-prompt.md",
  promptArgs: { ISSUE_NUMBER: 42, PRIORITY: "high" },
});

In the prompt file:

Work on issue #{{ISSUE_NUMBER}} (priority: {{PRIORITY}}).

Prompt argument substitution runs on the host before shell expression expansion, so {{KEY}} placeholders inside !`command` expressions are replaced first:

!`gh issue view {{ISSUE_NUMBER}} --json body -q .body`

A {{KEY}} placeholder with no matching prompt argument is an error. Unused prompt arguments produce a warning.

Built-in prompt arguments

Sandcastle automatically injects two built-in prompt arguments into every prompt:

Placeholder Value
{{SOURCE_BRANCH}} The branch the agent works on inside the worktree (temp or explicit)
{{TARGET_BRANCH}} The host's active branch at run() time

Use them in your prompt without passing them via promptArgs:

You are working on {{SOURCE_BRANCH}}. When diffing, compare against {{TARGET_BRANCH}}.

Passing SOURCE_BRANCH or TARGET_BRANCH in promptArgs is an error — built-in prompt arguments cannot be overridden.

Early termination with <promise>COMPLETE</promise>

When the agent outputs <promise>COMPLETE</promise>, the orchestrator stops the iteration loop early. This is a convention you document in your prompt for the agent to follow — the engine never injects it.

This is useful for task-based workflows where the agent should stop once it has finished, rather than running all remaining iterations.

You can override the default signal by passing completionSignal to run(). It accepts a single string or an array of strings:

await run({
  // ...
  completionSignal: "DONE",
});

// Or pass multiple signals — the loop stops on the first match:
await run({
  // ...
  completionSignal: ["TASK_COMPLETE", "TASK_ABORTED"],
});

Tell the agent to output your chosen string(s) in the prompt, and the orchestrator will stop when it detects any of them. The matched signal is returned as result.completionSignal.

Templates

sandcastle init prompts you to choose a template, which scaffolds a ready-to-use prompt and main.mts suited to a specific workflow. If your project's package.json has "type": "module", the file will be named main.ts instead. Four templates are available:

Template Description
blank Bare scaffold — write your own prompt and orchestration
simple-loop Picks GitHub issues one by one and closes them
sequential-reviewer Implements issues one by one, with a code review step after each
parallel-planner Plans parallelizable issues, executes on separate branches, then merges

Select a template during sandcastle init when prompted, or re-run init in a fresh repo to try a different one.

CLI commands

sandcastle init

Scaffolds the .sandcastle/ config directory and builds the Docker image. This is the first command you run in a new repo.

Option Required Default Description
--image-name No sandcastle:<repo-dir-name> Docker image name
--agent No Interactive prompt Agent to use (claude-code, pi, codex)
--model No Agent's default model Model to use (e.g. claude-sonnet-4-6). Defaults to agent's default
--template No Interactive prompt Template to scaffold (e.g. blank, simple-loop)

Creates the following files:

.sandcastle/
├── Dockerfile      # Sandbox environment (customize as needed)
├── prompt.md       # Agent instructions
├── .env.example    # Token placeholders
└── .gitignore      # Ignores .env, logs/, worktrees/

Errors if .sandcastle/ already exists to prevent overwriting customizations.

sandcastle build-image

Rebuilds the Docker image from an existing .sandcastle/ directory. Use this after modifying the Dockerfile.

Option Required Default Description
--image-name No sandcastle:<repo-dir-name> Docker image name
--dockerfile No — Path to a custom Dockerfile (build context will be the current working directory)

sandcastle remove-image

Removes the Docker image.

Option Required Default Description
--image-name No sandcastle:<repo-dir-name> Docker image name

RunOptions

Option Type Default Description
agent AgentProvider — Required. Agent provider (e.g. claudeCode("claude-opus-4-6"), pi("claude-sonnet-4-6"), codex("gpt-5.4-mini"))
prompt string — Inline prompt (mutually exclusive with promptFile)
promptFile string — Path to prompt file (mutually exclusive with prompt)
maxIterations number 1 Maximum iterations to run
hooks object — Lifecycle hooks (onSandboxReady)
worktree WorktreeMode { mode: 'temp-branch' } Worktree mode: { mode: 'none' }, { mode: 'temp-branch' }, or { mode: 'branch', branch }
imageName string sandcastle:<repo-dir-name> Docker image name for the sandbox
name string — Display name for the run, shown as a prefix in log output
promptArgs PromptArgs — Key-value map for {{KEY}} placeholder substitution
copyToSandbox string[] — Host-relative file paths to copy into the worktree before start (not supported with mode: 'none')
logging object file (auto-generated) { type: 'file', path } or { type: 'stdout' }
completionSignal string | string[] <promise>COMPLETE</promise> String or array of strings the agent emits to stop the iteration loop early
idleTimeoutSeconds number 600 Idle timeout in seconds — resets on each agent output event

RunResult

Field Type Description
iterationsRun number Number of iterations that were executed
completionSignal string? The matched completion signal string, or undefined if none fired
stdout string Agent output
commits { sha }[] Commits created during the run
branch string Target branch name
logFilePath string? Path to the log file (only when logging to a file)

Environment variables are resolved automatically from .sandcastle/.env and process.env — no need to pass them to the API. The required variables depend on the agent provider (see sandcastle init output for details).

Configuration

Config directory (.sandcastle/)

All per-repo sandbox configuration lives in .sandcastle/. Run sandcastle init to create it.

Custom Dockerfile

The .sandcastle/Dockerfile controls the sandbox environment. The default template installs:

  • Node.js 22 (base image)
  • git, curl, jq (system dependencies)
  • GitHub CLI (gh)
  • Claude Code CLI
  • A non-root agent user (required — Claude runs as this user)

When customizing the Dockerfile, ensure you keep:

  • A non-root user (the default agent user) for Claude to run as
  • git (required for commits and branch operations)
  • gh (required for issue fetching)
  • Claude Code CLI installed and on PATH

Add your project-specific dependencies (e.g., language runtimes, build tools) to the Dockerfile as needed.

Hooks

Hooks are arrays of { "command": "..." } objects executed sequentially inside the sandbox. If any command exits with a non-zero code, execution stops immediately with an error.

Hook When it runs Working directory
onSandboxReady After the sandbox is ready Sandbox repo directory

onSandboxReady runs after the worktree is mounted into the sandbox. Use it for dependency installation or build steps (e.g., npm install).

Pass hooks programmatically via run():

await run({
  hooks: {
    onSandboxReady: [{ command: "npm install" }],
  },
  // ...
});

Development

npm install
npm run build    # Build with tsgo
npm test         # Run tests with vitest
npm run typecheck # Type-check

License

MIT

About

Orchestrate sandboxed coding agents in TypeScript with sandcastle.run()

Resources

Readme

License

MIT license
Activity

Stars

429 stars

Watchers

4 watching

Forks

42 forks
Report repository

Releases 10

v0.2.3 Latest
Apr 5, 2026
+ 9 releases

Packages

 
 
 

Contributors

Languages