What is Sandcastle?
Sandcastle is an open-source TypeScript library for running and orchestrating AI coding agents in isolated environments. Sandcastle serves developers who want to coordinate unattended agents, build review pipelines, or incorporate agent execution into their own tooling. The library handles sandboxing and configurable Git branch strategies, with agent commits merged back.
Sandcastle exposes a programmatic run() function rather than requiring developers to manage every execution step themselves. Sandcastle can be used in scripts, CI pipelines, and custom tools. The repository publishes the project under the MIT license and documents installation through the @ai-hero/sandcastle npm package.
What Sandcastle can do
Sandcastle combines agent execution, sandbox configuration, Git workflows, and execution reporting in a TypeScript API. Sandcastle accepts interchangeable sandbox providers and exposes configuration for prompts, iteration limits, lifecycle hooks, timeouts, and logging. Developers can inspect the returned iteration results, collected commits, and target branch after an execution.
- Sandcastle runs coding agents with Docker, Podman, or Vercel sandbox providers.
- Sandcastle supports custom providers through bind-mount and isolated-provider helpers.
- Sandcastle accepts inline prompts or prompt files with placeholder substitution.
- Sandcastle executes lifecycle hooks on the host or inside the sandbox.
- Sandcastle records logs to files or terminal output.
- Sandcastle forwards agent-stream events to custom observability systems.
How Sandcastle works
Sandcastle setup begins with installing the npm package and running the init command to scaffold a .sandcastle directory. Developers copy the example environment file and configure a Claude Code OAuth token or an Anthropic API key. The generated main.ts or main.mts file is then run with tsx.
Sandcastle receives an agent configuration, a sandbox provider, and a prompt through the JavaScript API. Docker and Podman provide bind-mount environments, while Vercel provides isolated Firecracker microVMs through @vercel/sandbox. Sandcastle also accepts noSandbox() for direct host execution when container isolation is intentionally omitted.
Who Sandcastle is for
Sandcastle is aimed at developers who want to control coding-agent execution from TypeScript. The documented use cases include parallelizing unattended agents, creating review pipelines, and orchestrating custom agents. Sandcastle also fits workflows where scripts or CI jobs need programmatic access to execution results and Git changes.
- Sandcastle supports parallel unattended coding-agent workflows.
- Sandcastle supports agent-driven review pipelines.
- Sandcastle enables coding-agent execution within CI pipelines.
- Sandcastle provides orchestration building blocks for custom developer tooling.
Sandcastle pricing and access
Sandcastle is an open-source project published under the MIT license and available through npm. The supplied documentation describes package installation and local project initialization rather than subscription plans. Sandcastle's documented setup also involves agent authentication and a selected execution environment, such as Docker, Podman, or Vercel.
Sandcastle strengths and limitations
Sandcastle offers interchangeable sandbox providers, configurable branch handling, and execution reporting through a programmatic interface. Sandcastle also exposes lifecycle hooks and logging callbacks for integration into developer workflows. These capabilities require technical setup, and some options have explicit constraints that affect isolation, structured output, and file-copy behavior.
- Sandcastle requires Git for the documented workflow.
- Sandcastle skips container isolation when noSandbox() is selected.
- Sandcastle requires a single iteration and a matching prompt tag for structured output.
- Sandcastle cannot use copyToWorktree with the head branch strategy.
Sandcastle FAQ
What is Sandcastle?
Sandcastle is an open-source TypeScript library for orchestrating AI coding agents in isolated sandboxes. Sandcastle manages sandbox execution and configurable Git branch strategies, and exposes a programmatic API for scripts, CI pipelines, and custom tooling.
How is Sandcastle available?
Sandcastle is available as the @ai-hero/sandcastle npm package and is published under the MIT license. Sandcastle's documentation provides installation and initialization commands, followed by environment configuration and execution of a TypeScript entry file.
Which sandbox providers does Sandcastle support?
Sandcastle includes built-in providers for Docker, Podman, and Vercel. Sandcastle also supports custom providers through createBindMountSandboxProvider or createIsolatedSandboxProvider, and provides noSandbox() for running agents directly on the host without container isolation.
What can developers use Sandcastle for?
Sandcastle supports parallel unattended coding agents, review pipelines, and custom agent orchestration. Sandcastle's run() API can be called from scripts, CI pipelines, or developer tooling, with results that include iterations, created commits, and the target branch.
How do you set up Sandcastle?
Sandcastle setup involves installing @ai-hero/sandcastle, running the init command, and configuring the generated environment file. Sandcastle's quick start uses a Claude Code OAuth token or Anthropic API key, then runs the generated main.ts or main.mts file with tsx.
Does Sandcastle support logging and monitoring?
Sandcastle supports file and terminal logging, verbose raw output, and an onAgentStreamEvent callback. Sandcastle can forward text chunks, tool calls, and raw stdout lines to a developer's observability system; callback errors are swallowed so a broken forwarder cannot terminate the run.
From the community
No reviews yet
Be the first to review this tool. What you write helps the next person choose.
