Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mattpocock/sandcastle/llms.txt

Use this file to discover all available pages before exploring further.

Sandcastle is a TypeScript library that orchestrates AI coding agents inside isolated sandboxes. This page walks you through everything you need — from installing the package to running your first agent — so you reach a working state as quickly as possible.

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Git — Sandcastle uses git worktrees to manage branches
  • A sandbox provider — Sandcastle needs an isolated environment to run the agent in:
    • Docker Desktop — the most common choice for local development
    • Podman — a rootless alternative to Docker
    • Vercel — cloud-based Firecracker microVMs via @vercel/sandbox
You only need one sandbox provider. Docker Desktop is the recommended starting point if you don’t have a preference.

​
Set up Sandcastle

1

Install the package

Add @ai-hero/sandcastle as a dev dependency in your project.
npm install --save-dev @ai-hero/sandcastle
2

Scaffold the config directory

Run sandcastle init to create the .sandcastle/ config directory. The command prompts you to choose a sandbox provider (Docker or Podman), a backlog manager (GitHub Issues or Beads), and a workflow template.
npx sandcastle init
This creates the following files:
.sandcastle/
├── Dockerfile       # Sandbox environment — customize as needed
├── main.ts          # Entry point for running the agent
├── prompt.md        # Agent instructions
├── .env.example     # API key placeholders
└── .gitignore       # Ignores .env and logs/
If your package.json sets "type": "module", the entry point is named main.ts. Otherwise it is main.mts. Both work identically.
3

Configure your API key

Copy the example env file and fill in your ANTHROPIC_API_KEY.
cp .sandcastle/.env.example .sandcastle/.env
Open .sandcastle/.env and set your key:
ANTHROPIC_API_KEY=sk-ant-...
.sandcastle/.env is listed in .sandcastle/.gitignore by default. Do not commit it — it contains your API credentials.
4

Edit the prompt file

Open .sandcastle/prompt.md and write the instructions you want the agent to follow. This file is passed directly to the agent at the start of each iteration.
You are working on {{SOURCE_BRANCH}}.

Fix the failing tests in the `src/` directory. When you are done, output:

<promise>COMPLETE</promise>
{{SOURCE_BRANCH}} and {{TARGET_BRANCH}} are built-in prompt arguments that Sandcastle injects automatically — you do not need to pass them via promptArgs.
5

Run the agent

Execute the scaffolded entry point with npx tsx:
npx tsx .sandcastle/main.ts
Sandcastle starts the sandbox, mounts your repository, passes your prompt to the agent, and writes progress to a log file under .sandcastle/logs/. You will see a tail -f command printed to the terminal so you can follow along.

​
Minimal TypeScript example

The full .sandcastle/main.ts entry point that sandcastle init scaffolds is a thin wrapper around the run() function. Here is the minimal version: 
import { run, claudeCode } from "@ai-hero/sandcastle";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";

await run({
  agent: claudeCode("claude-opus-4-7"),
  sandbox: docker(), // or podman(), vercel(), or your own provider
  promptFile: ".sandcastle/prompt.md",
});
run() returns a RunResult with the commits the agent made, the branch it worked on, and the number of iterations it completed: 
const result = await run({
  agent: claudeCode("claude-opus-4-7"),
  sandbox: docker(),
  promptFile: ".sandcastle/prompt.md",
});

console.log(result.iterations.length); // number of iterations executed
console.log(result.commits);           // [{ sha: "abc123" }, ...]
console.log(result.branch);            // branch the agent worked on

​
Next steps

Key concepts

Understand sandboxes, agents, branch strategies, and how Sandcastle orchestrates them.

Sandbox providers

Configure Docker, Podman, or Vercel as your sandbox environment.

Prompts guide

Use prompt arguments, shell expressions, and built-in variables in your prompt files.

Branch strategies

Control how the agent’s commits land — directly on HEAD, a temp branch, or a named branch.

Build docs developers (and LLMs) love

Get started for freeTalk to us