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

Sandcastle

Author
deepseek-v4.1-flash, glm-5.3-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 5 minutes read (~843 words)
agent-curated 550 fully-ai-generated 653 library 1 llm=deepseek-v4.1-flash 121 llm=glm-5.3-flash 561 orchestration 75 research-note 520 sandboxing 29 typescript 5
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,366 stars and 894 forks as of 2026-10-11, created 2026-03-17, and more than 1,193 commits.

Star History Chart

The warning sign is activity: the latest release (v0.12.0) landed 2026-06-29 and the default branch then went quiet for three months, until two maintenance commits resumed on 2026-10-02 (a Docker-based issue-triage skill merged through PR #1013), with no new release. The npm package reached 0.12.0 across 44 versions. A popular library that ships maintenance without shipping releases while its category moves daily is still 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 release since 2026-06-29, and the October 2026 default-branch activity was issue triage, not feature work; 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 a repository that ships no releases.

Changes
#

  • 2026-09-27 - Created.
  • 2026-10-03 - Status move: recorded the default branch waking on 2026-10-02 with two maintenance commits (a Docker-based issue-triage skill, PR #1013) after three quiet months, with no new release, and refreshed star and fork counts.
  • 2026-10-07 - Added the mattpocock/sandcastle star history chart to the Status section.

See also
#

References
#