Sandcastle is a TypeScript library designed to orchestrate AI coding agents in isolated sandboxes, enabling safe and efficient automation of code generation, review, and modification tasks. Its primary purpose is to provide a robust framework for running agents—such as AI models like Claude—in environments that are isolated from the host system, ensuring that code changes are managed, tracked, and merged back into the main repository in a controlled manner. Sandcastle is particularly useful for parallelizing multiple agents, creating automated review pipelines, or simply orchestrating custom coding agents.
The core functionality revolves around the `sandcastle.run()` method, which allows users to invoke agents with a single command. Sandcastle handles the creation of sandboxed environments using a configurable branch strategy, ensuring that each agent operates on its own isolated branch. The changes made by agents are committed to these branches and can be merged back into the main repository, facilitating collaborative and automated workflows.
Sandcastle is provider-agnostic, meaning it supports multiple sandbox providers out of the box and allows users to create custom providers. Built-in providers include Docker, Podman, and Vercel. Docker and Podman offer local container-based isolation, while Vercel provides cloud-based microVMs for remote execution. There is also a "no-sandbox" option for running agents directly on the host when container isolation is not required. Users can extend Sandcastle by implementing their own providers using helper functions like `createBindMountSandboxProvider` or `createIsolatedSandboxProvider`.
To get started, users install the package and initialize the project with `npx @ai-hero/sandcastle init`, which scaffolds a `.sandcastle` directory containing all necessary files. Configuration is managed via environment variables, such as API keys for AI providers. The main entry point is typically `.sandcastle/main.ts`, which can be executed with `npx tsx`.
Sandcastle offers a flexible API for programmatic use in scripts, CI pipelines, or custom tooling. The `run()` function is suitable for one-shot invocations, automatically handling sandbox lifecycle. For scenarios requiring multiple agent runs within the same environment, the `createSandbox()` method creates a reusable sandbox, allowing repeated agent invocations without incurring container startup costs. This is ideal for workflows where dependencies and build artifacts need to persist across runs.
The library provides granular control over sandbox and worktree management. Options include specifying branches, sandbox providers, working directories, lifecycle hooks, file copying, and timeouts. Sandcastle supports automatic and manual cleanup of sandboxes and worktrees, preserving worktrees with uncommitted changes for inspection or further use.
Worktrees are managed independently from sandboxes, allowing users to run interactive sessions or hand off worktrees to agents. Ownership and cleanup responsibilities are clearly defined, ensuring that containers and worktrees are managed appropriately based on the workflow.
Overall, Sandcastle is a powerful tool for orchestrating AI-driven coding workflows in isolated environments, offering flexibility, extensibility, and safety. Its provider-agnostic design, comprehensive API, and robust lifecycle management make it suitable for advanced automation scenarios, collaborative coding, and integration with modern development pipelines.
