Sandcastle is a TypeScript library for running AI coding agents inside isolated sandboxes and merging their work back into your repository. You call sandcastle.run() with an agent, a sandbox provider, and a prompt; Sandcastle creates the sandbox with a configurable branch strategy, runs the agent, collects the commits it makes, and merges them back. It is aimed at running several unattended agents in parallel, building review pipelines, and orchestrating your own agents from scripts or CI.
Sandbox providers are pluggable. Built-in options are Docker and Podman (bind-mount providers that share the host worktree), Vercel (an isolated provider using Firecracker microVMs), and a no-sandbox mode that runs the agent directly on the host. You can write your own provider with createBindMountSandboxProvider or createIsolatedSandboxProvider. Agent providers include Claude Code, Codex, and Pi, each with its own options object.
Three branch strategies control where commits land: head writes straight to the host working directory, merge-to-head works on a throwaway branch and merges into HEAD when done, and branch places commits on a named branch for a pull request. createSandbox() keeps one container alive across multiple run() calls and shell exec() commands, so an implement step, a test run, and a review step can share installed dependencies and a branch; await using disposes it automatically, preserving the worktree if uncommitted changes remain.
Runs are configured with iteration limits, an idle timeout, a completion signal the agent emits to stop early, lifecycle hooks on the host and in the sandbox, files to copy into the worktree, and a logging target with an optional stream callback for your own observability system. Prompts support {{KEY}} arguments, inline shell substitution, and typed structured output extracted from the agent's stdout.
Features
- Single entry point: run() sandboxes an agent, runs it, and merges the resulting commits
- Sandbox providers: Docker, Podman, Vercel microVMs, no-sandbox, or a custom provider
- Agent providers: Claude Code, Codex, and Pi with per-provider options such as effort level
- Branch strategies: head, merge-to-head, and explicit branch
- Reusable sandboxes: createSandbox() runs multiple agents or rounds in one warm container with exec() for shell commands
- Worktree lifecycle: createWorktree() manages an independent worktree with its own run and interactive methods
- Iteration control: maxIterations, idle and completion timeouts, and a configurable completion signal
- Hooks: host and sandbox commands on worktree-ready and sandbox-ready events
- Prompt templating: {{KEY}} substitution, built-in arguments, dynamic context from shell commands, and templates
- Structured output: extract a typed payload from the agent's output with a schema
- Session handling: capture, resume, and fork agent sessions across iterations
- Container configuration: mounts, networks, devices, supplementary groups, CPU limits, SELinux labels, and a custom Dockerfile
