Keep AI Agents in a Sandbox (and a Git Worktree)

What it does

Sandcastle is a TypeScript library that corrals AI coding agents inside isolated runtimes—Docker, Podman, or Vercel’s Firecracker microVMs—and manages their output through Git. You hand it a prompt and a sandbox provider; it runs the agent on a disposable branch and merges the commits back when done. The target use case is unattended automation: parallel agent farms, CI pipelines, or review workflows where generated code needs inspection before it lands.

The interesting bit

Instead of treating an agent session as a mysterious stdout dump, Sandcastle makes the agent’s commits first-class Git objects. A configurable branch strategy layer turns the sandbox into a temporary worktree with real merge semantics, so you get a diff you can review rather than a paste buffer you hope compiles.

Key highlights

• Provider-agnostic sandboxing: swap Docker, Podman, Vercel Firecracker, or a custom provider without changing orchestration logic.
• Reusable sandboxes via createSandbox() to avoid container cold-start overhead across multiple runs.
• Programmatic API with lifecycle hooks, configurable timeouts, idle detection, and structured output parsing for pipeline integration.
• Branch strategies isolate agent commits; defaults differ between bind-mount (head) and isolated (merge-to-head) providers.
• Optional noSandbox() mode runs the agent directly on the host when container isolation is unnecessary.

Caveats

• The README currently illustrates only claudeCode() as an agent provider; broader LLM support is not yet demonstrated.
• Using a Claude subscription instead of an API key requires a workaround (see issue #191).

Verdict

Worth a look if you are building CI pipelines or review workflows around Claude Code and need reproducible, isolated agent runs. Skip it if you want a simple, host-only script runner without Git or container overhead.