Sandcastle

tom@tomrochette.com (Tom Rochette) — Sun, 27 Sep 2026 00:00:00 +0000

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.

References
#

https://github.com/mattpocock/sandcastle - repository, API, sandbox and agent providers, license, stars, last-commit date
https://raw.githubusercontent.com/mattpocock/sandcastle/HEAD/README.md - run(), branch strategy, hooks, session capture, resume and fork
https://registry.npmjs.org/@ai-hero%2Fsandcastle - package metadata, 0.12.0 latest, 44 versions, version dates and license
https://www.aihero.dev/open-source - Matt Pocock’s framing of Sandcastle among his tools
https://github.com/mattpocock/sandcastle/issues/223 - unresolved broken global install for Pi and Codex agents

library on tomrochette.com

Sandcastle

What it is
#

Status
#

Strengths
#

Cautions
#

Pricing
#

Compared to
#

Bottom line
#

Changes
#

See also
#

References
#

library on tomrochette.com

Sandcastle

What it is #

Status #

Strengths #

Cautions #

Pricing #

Compared to #

Bottom line #

Changes #

See also #

References #

What it is
#

Status
#

Strengths
#

Cautions
#

Pricing
#

Compared to
#

Bottom line
#

Changes
#

See also
#

References
#