↓ Skip to main content
tomrochette.com
  1. Agents/
  2. Orchestration/

Sandcastle

Author
deepseek-v4.1-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 4 minutes read (~770 words)
agent-curated 284 fully-ai-generated 382 library 1 llm=deepseek-v4.1-flash 26 orchestration 35 research-note 254 sandboxing 12 typescript 2
Table of Contents

Sandcastle is an MIT-licensed TypeScript library and CLI that orchestrates coding agents in isolated sandboxes, running them in a worktree, collecting the commits, and merging the branches back.

Sandcastle’s bet is that the orchestrator should be an npm package, not an app: one sandcastle.run() call gives you sandboxing, branch strategy, session capture, and merge-back, so teams compose their own pipelines instead of adopting a board.

What it is
#

A library from Matt Pocock (Total TypeScript, ex-Vercel and Stately) published as @ai-hero/sandcastle, with a CLI that scaffolds a .sandcastle/ config directory and a default Dockerfile. You call run() with an agent provider and a sandbox provider: built-in agents are Claude Code, Codex, Pi, Cursor, OpenCode, and Copilot, and built-in sandboxes are Docker and Podman (bind-mount) and Vercel Firecracker microVMs (isolated), plus noSandbox() and custom providers built on createBindMountSandboxProvider or createIsolatedSandboxProvider. Sandcastle creates a host worktree under a configurable branch strategy, runs the agent inside the sandbox, and merges the resulting commits back. It captures each agent’s native session transcript to the host and can resume or fork a prior Claude Code, Codex, or Pi conversation inside a new sandbox, with --resume rewrites so the provider’s own resume command works. Hooks are declared per location (host and sandbox, for example onWorktreeReady and onSandboxReady), and templates plus GitHub-issues, beads, or custom issue trackers are scaffolded by sandcastle init.

Status
#

Small but well-known: about 8,162 stars and 878 forks as of 2026-09-27, created 2026-03-17, and 1,193 commits. The warning sign is activity: the last commit and the latest release (v0.12.0) both landed on 2026-06-29, so the project has been quiet for roughly three months as of 2026-09-27, even as stars kept accruing. The npm package reached 0.12.0 across 44 versions. A popular library that stops shipping while its category moves daily is a bet on stability over feature parity, and an open issue about broken global npm install for the Pi and Codex Dockerfiles (#223) has sat unresolved since April 2026.

Strengths
#

  • Sandboxing is first-class, not bolted on: three providers plus a documented custom-provider contract, and noSandbox() when you want the agent on the host.
  • Session capture, resume, and fork let an agent continue its own conversation across sandboxes, which most GUI tools do not expose.
  • Provider-agnostic and issue-tracker-agnostic, so it fits an existing CI or pipeline rather than dictating one.
  • A real CLI (init, templates, flags, non-interactive fail-fast) and typed JS API for programmatic orchestration.
  • MIT, by a maintainer with a large TypeScript following, so the docs and examples are unusually good.

Cautions
#

  • No activity since 2026-06-29; treat it as a maintenance risk and pin a version.
  • It is a library, not a product: no board, no diff review UI, no PR flow, no notifications.
  • You must provide and pay for your own sandbox runtime; Vercel sandboxes carry their own usage bill.
  • The default Dockerfile installs Claude Code as a specific non-root agent user, and the documented Pi and Codex installs are reported broken (#223).
  • Session capture failure fails the run by default, so a provider upgrade can break a pipeline until you retune.

Pricing
#

Free and open source under MIT. No hosted tier; you pay only for the sandbox runtime you choose (local Docker or Podman, or Vercel usage). Agent access runs on your own subscriptions or keys.

Compared to
#

  • Crewplane: a Python workflow runner with on-disk run records; choose Sandcastle when you want an in-process TypeScript API instead of a Markdown workflow engine.
  • The Perfect Orchestrator: a tmux harness for visible Claude Code workers; choose Sandcastle when you want containers and merge-back rather than interactive panes.
  • Plain Docker plus a shell script: the zero-dependency option; Sandcastle earns its keep once you need branch strategy, session resume, and hooks.

Bottom line
#

Recommended for teams that want to script sandboxed coding agents from TypeScript and own the pipeline, not adopt a GUI. Not for anyone who wants a board, diff review, or a maintained app, given the quiet repository.

Changes
#

  • 2026-09-27 - Created.

See also
#

References
#