mattpocock /sandcastle
Orchestrate sandboxed coding agents in TypeScript with sandcastle.run()
★ 9,094⑂ 982👁 26⑃ 844● 806▤ 45
+18
Daily
9,094
stars
982
forks
26
watchers
844
prs
806
issues
45
releases
README
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 native sandboxes that use your OS's own process sandbox (Bubblewrap on Linux and WSL2, Seatbelt on macOS), image-based providers for Docker and Podman, and cloud providers for Daytona, E2B, Fly.io Sprites, Modal and Vercel, and you can create your own. Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents. Documentation The docs live in docs/guide, one page per major term, with every term defined in the Glossary, and are published at aihero.dev/sandcastle. - Getting started: prerequisites and a quick start - Core: Core concepts - Sandboxes: Sandbox providers - Branching: Branch strategies - Agents: Agent providers, Agent sessions - Execution: Iterations, Structured output - Prompts: Prompts - Hooks: Hooks - Init: Init - Display: Run logs - Reference: run() and createSandbox(), CLI commands, Glossary Development bash npm install npm run build Bundle with tsup npm test Run tests with vitest npm run typecheck Type-check License MIT
Top issues
#488Figure out Codex + Subscription11 comments · 2026-04-29#854Bind-mount worktree sandboxes corrupt worktree git metadata on non-Windows hosts4 comments · 2026-06-25#849Concurrent branch-strategy worktrees delete each other4 comments · 2026-06-23#745`pnpm install` in `onSandboxReady` corrupts host `node_modules` with Linux-only native binaries on macOS4 comments · 2026-05-26#1043Reused worktree: 'Could not fetch from origin' drops git's error output3 comments · 2026-10-15#998Giving claude permission for /home/agent3 comments · 2026-09-11#996Windows: worktree-mode createSandbox fails when the host repo is itself a linked worktree (host .git pointer-file mount is never patched)3 comments · 2026-09-11#852Wrong permissions workspace with podman3 comments · 2026-06-24
Latest release
v0.14.0 v0.14.0 2026-11-02Minor Changes
- d99fff8: Add an E2B isolated sandbox provider, e2b() from @ai-hero/sandcastle/sandboxes/e2b. It needs the optional e2b peer dependency and E2B_API_KEY (or the apiKey option). Use a template that ships your agent's CLI, such as e2b({ template: "claude" }).
- 8783573: Add modal(), an isolated sandbox provider for Modal sandboxes, at @ai-hero/sandcastle/sandboxes/modal. Install modal (an optional peer dependency) and set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET, or pass tokenId and tokenSecret. By default it builds a node:24-bookworm image with Claude Code installed; pass image for