Sandcastle is a TypeScript library designed for orchestrating AI coding agents in isolated sandbox environments. The core functionality revolves around a single `sandcastle.run()` function that invokes agents within configurable sandboxed branches, automatically handling the sandbox lifecycle and merging commits back to the host repository. The library is provider-agnostic, shipping with built-in support for Docker, Podman, and Vercel's Firecracker microVMs, while also allowing developers to create custom sandbox providers.
Sandcastle's architecture supports multiple usage patterns. The `run()` function handles one-shot agent invocations with automatic sandbox lifecycle management, while `createSandbox()` enables reusable sandbox instances for running multiple agents or multiple rounds sequentially within the same container. This design avoids repeated container startup costs and allows dependencies and build artifacts to persist across runs. The library also provides `sandbox.exec()` for running shell commands directly within the sandbox, useful for verification steps before triggering review processes.
The sandbox provider system is central to Sandcastle's flexibility. Built-in providers include Docker for local bind-mount sandboxing, Podman as a rootless Docker alternative, Vercel for cloud-based isolated environments, and a no-sandbox option for running agents directly on the host when container isolation is unnecessary. Developers can implement custom providers using `createBindMountSandboxProvider` or `createIsolatedSandboxProvider` for specialized use cases.
Configuration options are extensive and granular. The `SandboxRunOptions` interface allows developers to specify agent providers, inline prompts or prompt files with placeholder substitution, iteration limits, completion signals, idle and completion timeouts, logging preferences, and session resumption capabilities. The library supports AbortSignal for cancellation and includes lifecycle hooks for both host and sandbox environments. Results from runs include per-iteration details, matched completion signals, combined stdout output, created commits, and optional log file paths.
Advanced features include session resumption and forking capabilities. The `resume()` method allows agents that support session capture to continue from a prior state within the same warm sandbox, while `fork()` creates a branching continuation without modifying the parent session. The `createWorktree()` function provides independent git worktree lifecycle management, useful when running interactive sessions before handing off to sandboxed agents.
The repository is classified across multiple domains including TypeScript, documentation, code examples, interactive playground, API reference, developer tools, tutorials, code snippets, and learning platform. This breadth reflects Sandcastle's positioning as both a production library and an educational resource.
