Sandcastle

Sandcastle is a TypeScript library designed to orchestrate AI coding agents within isolated sandboxes. It simplifies agent execution by:

1. Invoking agents via a single run() call.
2. Automatically handling sandboxing using a configurable branch strategy.
3. Merging commits made on the sandbox branches back into the main codebase.

It is provider-agnostic and supports Docker, Podman, and Vercel, or custom providers.

Sandcastle is a TypeScript CLI tool that orchestrates an agent inside a sandbox. To use the tool effectively, understand these key entities:

• Sandcastle: The CLI tool itself.
• Sandbox: The isolation boundary (container, VM, etc.) that constrains the agent's access.
• Host: Your local machine where the real git repository and Sandcastle reside.
• Agent: The AI coding tool running inside the sandbox (e.g., Claude Code, Codex).
• Agent Provider: A pluggable implementation that builds commands and parses output for a specific agent.
• Sandbox Provider: A pluggable implementation that creates and manages the sandbox environment.

To use Sandcastle effectively, understand these core components:

• Sandbox: An isolated environment (either a Docker container or a local directory) where the agent executes code.
• Host: Your local machine where Sandcastle is running and where the actual git repository resides.
• Agent: The AI coding tool (such as Claude Code) that is invoked inside the sandbox.
• Iteration: A single invocation of the agent, which results in at most one commit.

Claude Code is the default agent provider in Sandcastle. It uses Claude Code as the AI coding agent inside the sandbox. To use it, you must provide either an OAuth token or an Anthropic API key, along with a GitHub token.

To get a CLAUDE_CODE_OAUTH_TOKEN, run claude setup-token on your host machine. This allows the agent to use your existing Claude subscription.

# Required Environment Variables

# One of these:
CLAUDE_CODE_OAUTH_TOKEN
ANTHROPIC_API_KEY

# Plus:
GH_TOKEN

Sandcastle supports different ways to provide instructions to the agent:

• Inline prompt: A raw string provided via the prompt option. No substitution or expansion is performed.
• Prompt template: A file sourced via the promptFile option. It supports:
  • Prompt argument substitution: Replacing {{KEY}} placeholders with values from promptArgs.
  • Prompt expansion: Evaluating shell expressions (marked with !`command`) by replacing them with the command's stdout inside the sandbox.

When running a sandbox inside a Linux container on a Windows host, Git worktree mounts can break because the .git file contains Windows-native paths (e.g., C:\Users\...) that cannot be resolved inside the Linux environment. Additionally, the parent .git directory may not have a valid sandbox path.

Sandcastle resolves this by using patchGitMountsForWindows to perform pre-start patching. This process:

1. Mounts the parent .git directory at a deterministic POSIX path: /.sandcastle-parent-git.
2. Rewrites the worktree's .git file to use the new gitdir: path (e.g., gitdir: /.sandcastle-parent-git/worktrees/abc).
3. Uses a Docker overlay mount to place the corrected .git file at SANDBOX_REPO_DIR/.git before the container starts.

This ensures that Git operations work immediately upon sandbox availability without needing post-start exec commands.

The IterationResult.usage object provides raw token counts but does not include the model's context window size or the percentage of the window used. To calculate the percentage of the context window consumed, you must manually provide the model's context limit and use the raw token counts provided in IterationResult.usage.

Available raw token fields in IterationResult.usage:

• inputTokens
• cacheCreationInputTokens
• cacheReadInputTokens
• outputTokens

Run the initialization command to scaffold the required configuration directory. This creates a .sandcastle/ directory containing a Dockerfile, a prompt file, and the necessary configuration files for your project.

npx @ai-hero/sandcastle init

Sandcastle distinguishes between inline prompts (passed via the prompt string) and template prompts (sourced via promptFile).

• Inline Prompts (prompt: "..."): These are delivered to the agent verbatim. Sandcastle does not perform argument substitution, prompt expansion, or injection of built-in variables like {{SOURCE_BRANCH}} or {{TARGET_BRANCH}}. If your inline prompt contains {{...}} sequences, they will be passed to the agent literally and will not be processed.
• Template Prompts (promptFile): These are processed through the full interpolation pipeline, supporting {{KEY}} substitution and `!command` execution.

Important: If you need to include dynamic context (like branch names) in an inline prompt, you must perform the interpolation in your JavaScript code using template literals rather than relying on Sandcastle's built-in arguments.