Sandcastle

Sandcastle is a TypeScript library that lets you orchestrate AI coding agents inside isolated sandboxes with a single sandcastle.run() call. It handles sandboxing via configurable providers (Docker, Podman, Vercel, or custom), manages git branch strategies so agent commits land cleanly, and merges changes back automatically. It is provider-agnostic and designed for parallelizing multiple AFK agents, building review pipelines, or composing custom agent workflows.

• sandcastle.run() — invoke an agent with a single call; Sandcastle handles sandbox lifecycle, branching, and commit merging automatically.
• Multiple sandbox providers — built-in support for Docker, Podman, and Vercel Firecracker microVMs; create custom bind-mount or isolated providers using createBindMountSandboxProvider / createIsolatedSandboxProvider.
• Branch strategies — choose head (direct write), merge-to-head (temp branch merged back), or branch (explicit named branch) to control where agent commits land.
• createSandbox() — reuse a single sandbox across multiple agent runs to avoid repeated container startup costs and keep all runs on the same branch.
• createWorktree() — manage git worktrees as independent first-class objects, enabling interactive-then-AFK agent handoffs on the same branch.
• Prompt system — use inline strings or prompt files with {{KEY}} placeholder substitution, dynamic shell expression expansion (!`command`), and built-in {{SOURCE_BRANCH}} / {{TARGET_BRANCH}} variables.
• Lifecycle hooks — run setup commands on the host or inside the sandbox at onWorktreeReady and onSandboxReady hook points, with per-hook timeout control.
• Session capture & resume — automatically captures Claude Code session JSONL to the host for claude --resume support; pass resumeSession to continue a prior conversation in a new sandbox.
• CLI tooling — sandcastle init scaffolds the .sandcastle/ config directory and Docker image; sandcastle docker build-image / sandcastle podman build-image rebuild images after Dockerfile changes.
• Workflow templates — choose from blank, simple-loop, sequential-reviewer, parallel-planner, or parallel-planner-with-review during sandcastle init to scaffold ready-to-use orchestration scripts.
• Iteration control — configure maxIterations, completionSignal, and idleTimeoutSeconds to control how long agents run and when they stop.
• AbortSignal support — pass a signal to run() to cancel in-flight agent subprocesses and lifecycle hooks cleanly.