Sandcastle

Sandcastle is a TypeScript library for running AI coding agents — Claude Code, Codex, Copilot, Cursor, OpenCode, and Pi — inside isolated sandboxes so their file edits, shell commands, and git operations never touch your working directory until you’re ready to merge them back.

Built on Docker, Podman, or Vercel’s Firecracker microVMs (with a no-sandbox escape hatch for trusted runs), Sandcastle wraps each agent invocation in a managed git worktree, streams its output through a pluggable logging hook, and gives you full control over iteration limits, structured output extraction, and branch strategy — all from a single run() call or a scriptable createSandbox() API for multi-agent pipelines.

What You Get

• A single run() function that provisions a sandbox, invokes an agent, and merges its commits back to your branch
• Built-in support for six agent providers: Claude Code, Codex, Copilot, Cursor, OpenCode, and Pi
• Three built-in sandbox providers (Docker, Podman, Vercel) plus a no-sandbox mode and a factory API for custom providers
• A createSandbox() API for running multiple agents or iterations inside one reusable sandbox
• A CLI (npx @ai-hero/sandcastle init) that scaffolds a .sandcastle/ config directory with env, prompt, and provider templates

Common Use Cases

• Running an autonomous coding agent against a GitHub issue in an isolated container so it can’t touch your local working tree
• Parallelizing multiple AFK (away-from-keyboard) agent runs across separate worktrees and sandboxes
• Building agent review pipelines that run an agent, extract structured output, and gate the merge on its result
• Resuming a Claude Code or Codex session on the host after it ran inside a sandbox, via session transfer helpers

Under The Hood

Architecture — The core loop lives in run.ts, which resolves the working directory, validates the prompt source, resolves environment variables, creates an isolated git worktree via WorktreeManager.ts, provisions a sandbox through SandboxFactory.ts (a WorktreeDockerSandboxFactory abstraction shared across providers), and hands control to Orchestrator.ts to drive the agent iteration loop — tracking commits, usage, and completion signals — before merging results back to the host branch. createSandbox.ts exposes a lower-level, reusable-sandbox variant of the same pipeline for multi-run scenarios, and interactive.ts/cli.ts/main.ts layer a TUI and init scaffolding command (via InitService.ts) on top for local, human-driven use.

Tech Stack — Written in strict TypeScript (ES2022, NodeNext modules) and built on the Effect functional-effects system (@effect/platform, @effect/platform-node, @effect/cli) for structured concurrency and error handling; Zod (Output.ts) validates structured agent output; tsup produces dual ESM builds with a postbuild step that copies templates and checks the public API stays Effect-free; @changesets/cli drives versioned releases and husky/lint-staged enforce pre-commit checks.

Code Quality — Near every source module has a matching .test.ts file of comparable or greater size (Orchestrator.ts at 23KB pairs with a 139KB Orchestrator.test.ts; createSandbox.ts at 41KB pairs with a 72KB test file), run under Vitest. tsconfig.json enables strict and noUncheckedIndexedAccess. Errors are centralized through dedicated errors.ts, ErrorHandler.ts, and CwdError.ts modules rather than scattered try/catch, and structured-output failures produce a typed StructuredOutputError with a retry-feedback builder rather than failing silently.

API Design — The public surface (run, interactive, createSandbox, createWorktree) is a small set of option-bag functions with consistent shapes across agent providers (claudeCode(), codex(), copilot(), cursor(), opencode(), pi()) and sandbox providers (docker(), podman(), vercel(), noSandbox()), documented exhaustively in an 88KB README that walks through every option, timeout, and hook. The bundled init CLI command removes most first-run boilerplate by scaffolding a working .sandcastle/ directory.