mattpocock / sandcastle

## What Is Sandcastle?
A TypeScript library for orchestrating AI coding agents in isolated sandboxes:
1. You invoke agents with a single `sandcastle.run()`.
2. Sandcastle handles sandboxing the agent with a configurable branch strategy.
3. The commits made on the branches get merged back.
Sandcastle is provider-agnostic — it ships with built-in providers for Docker, Podman, and Vercel, and you can create your own. Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents.
## Prerequisites
- Git
- A sandbox provider — Sandcastle needs an isolated environment to run agents in. Built-in options:
 - Docker Desktop — most common for local development
 - Podman — rootless alternative to Docker
 - Vercel — cloud-based Firecracker microVMs via `@vercel/sandbox`
 - Or create your own using `createBindMountSandboxProvider` or `createIsolatedSandboxProvider`
## Quick start
1. Install the package:
 [code] 
2. Run `npx @ai-hero/sandcastle init`. This scaffolds a `.sandcastle` directory with all the files needed.
 [code] 
3. Copy `.sandcastle/.env.example` to `.sandcastle/.env`, then fill in your default values for `CLAUDE_CODE_OAUTH_TOKEN` (run `claude setup-token` on your host to get one). To use an Anthropic API key instead, uncomment and fill in `ANTHROPIC_API_KEY`.
 [code] 
4. Run the `.sandcastle/main.ts` (or `main.mts`) file with `npx tsx`
 [code] 
 [code] 
## Sandbox Providers
Sandcastle uses a `SandboxProvider` to create isolated environments. The `sandbox` option on `run()`, `interactive()`, and `createSandbox()` accepts any provider, including `noSandbox()` — opt in to running the agent directly on the host when container isolation is undesired. Built-in providers:
| Provider | Import path | Type | Accepted by |
| ---------- | ------------------------------------------ | ---------- | ------------------------------------------- |
| Docker | `@ai-hero/sandcastle/sandboxes/docker` | Bind-mount | `run()`, `createSandbox()`, `interactive()` |
| Podman | `@ai-hero/sandcastle/sandboxes/podman` | Bind-mount | `run()`, `createSandbox()`, `interactive()` |
| Vercel | `@ai-hero/sandcastle/sandboxes/vercel` | Isolated | `run()`, `createSandbox()`, `interactive()` |
| No-sandbox | `@ai-hero/sandcastle/sandboxes/no-sandbox` | None | `run()`, `createSandbox()`, `interactive()` |
Worktree methods (`wt.run()`, `wt.interactive()`, `wt.createSandbox()`) accept the same providers as their top-level counterparts. `wt.interactive()` defaults to `noSandbox()` when no sandbox is specified.
 [code] 
You can also create your own provider using `createBindMountSandboxProvider` or `createIsolatedSandboxProvider`.
## API
Sandcastle exports a programmatic `run()` function for use in scripts, CI pipelines, or custom tooling. The examples below use `docker()`, but any `SandboxProvider` works in its place.
 [code] 
### All options
 [code] 
### `createSandbox()` — reusable sandbox
Use `createSandbox()` when you need to run mul