Sandcastle lets you invoke AI coding agents — Claude Code, Codex, OpenCode, Pi — inside isolated sandbox environments with a singleDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/mattpocock/sandcastle/llms.txt
Use this file to discover all available pages before exploring further.
sandcastle.run() call. It handles the full lifecycle: spinning up a container, running the agent against your codebase, and landing commits on the right branch. All 100% local, all provider-agnostic.
Quickstart
Install Sandcastle and run your first agent in under five minutes
Core concepts
Understand sandboxes, agents, branch strategies, and iterations
API reference
Full reference for
run(), createSandbox(), createWorktree(), and moreSandbox providers
Docker, Podman, Vercel, and custom sandbox provider setup
Why Sandcastle?
Sandcastle solves the problem of safely running unsupervised AI coding agents. Instead of letting an agent write directly to your working directory, Sandcastle spins up an isolated environment, runs the agent there, and surfaces the results as commits on a branch you control.Provider-agnostic
Works with Docker, Podman, Vercel Firecracker VMs, or any custom provider you implement
Flexible branching
Three branch strategies: write to head, merge to head, or land on a named branch
Dynamic prompts
Prompt templates with
{{KEY}} substitution and !`command` shell expansion inside the sandboxParallel workflows
Spawn multiple agents on separate branches simultaneously for parallel issue resolution
Structured output
Extract schema-validated JSON payloads from agent output with
Output.object()Lifecycle hooks
Run setup commands on the host or inside the sandbox before the agent starts
How it works
Install and initialize
Install
@ai-hero/sandcastle and run sandcastle init to scaffold a .sandcastle/ config directory with a Dockerfile, prompt file, and environment template.Configure your sandbox
Choose a sandbox provider (Docker, Podman, or Vercel) and a branch strategy. The provider controls the isolation boundary; the branch strategy controls where commits land.
Write your prompt
Edit
.sandcastle/prompt.md with instructions for the agent. Use {{KEY}} placeholders for dynamic values and !`command` expressions to pull in live context like open GitHub issues or recent commits.