AIHero

    Start here

    Getting started

    Edit this page on GitHub
    On this page

    What Is Sandcastle?

    A TypeScript library for orchestrating AI coding agents in isolated sandboxes:

    1. You invoke agents with a single sandcastle.run().
    2. Sandcastle handles sandboxing the agent with a configurable branch strategy.
    3. The commits made on the branches get merged back.

    Sandcastle is provider-agnostic — it ships with built-in providers for Docker, Podman, and Vercel, and you can create your own. Great for parallelizing multiple AFK agents, creating review pipelines, or even just orchestrating your own agents.

    Prerequisites

    • Git
    • A sandbox provider — Sandcastle needs an isolated environment to run agents in. Built-in options:
      • Docker Desktop — most common for local development
      • Podman — rootless alternative to Docker
      • Vercel — cloud-based Firecracker microVMs via @vercel/sandbox
      • Or create your own using createBindMountSandboxProvider or createIsolatedSandboxProvider

    Quick start

    1. Install the package:
    npm install --save-dev @ai-hero/sandcastle
    1. Run npx @ai-hero/sandcastle init. This scaffolds a .sandcastle directory with all the files needed.
    npx @ai-hero/sandcastle init
    1. Copy .sandcastle/.env.example to .sandcastle/.env, then fill in your default values for CLAUDE_CODE_OAUTH_TOKEN (run claude setup-token on your host to get one). To use an Anthropic API key instead, uncomment and fill in ANTHROPIC_API_KEY.
    cp .sandcastle/.env.example .sandcastle/.env
    1. Run the .sandcastle/main.ts (or main.mts) file with npx tsx
    npx tsx .sandcastle/main.ts
    // 4. Run the agent via the JS API

    import { run, claudeCode } from "@ai-hero/sandcastle";

    import { docker } from "@ai-hero/sandcastle/sandboxes/docker";

    

    await run({

      agent: claudeCode("claude-opus-4-8"),

      sandbox: docker(), // or podman(), vercel(), or your own provider

      promptFile: ".sandcastle/prompt.md",

    });