Core concepts

Sandcastle runs on the host, creates a sandbox, and invokes an agent inside it. One run() call does all three:

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

const result = await run({
  agent: claudeCode("claude-opus-4-8"),
  sandbox: docker(),
  promptFile: ".sandcastle/prompt.md",
});

console.log(result.iterations.length); // number of iterations executed
console.log(result.iterations); // per-iteration results with optional sessionId
console.log(result.commits); // array of { sha } for commits created
console.log(result.branch); // target branch name

Map of the docs

Each page below covers one term from the glossary, with the terms around it folded in.

• Getting started: prerequisites and a quick start.
• Sandbox providers: how the sandbox is created. Bind-mount, native, isolated and no-sandbox providers, building and removing images, and writing your own provider.
• Branch strategies: where the agent's commits land. Head, merge-to-head and branch, worktrees and createWorktree(), source and target branches.
• Agent providers: which agent runs, its options, and its env.
• Agent sessions: capturing, resuming and forking the agent's conversation.
• Iterations: the iteration loop, the completion signal, and the completion timeout for a hanging process.
• Structured output: a typed payload from the agent, checked against an output schema.
• Prompts: inline prompts and prompt templates, prompt arguments, built-in prompt arguments, and shell expressions.
• Hooks: commands that run on the host or in the sandbox while it starts.
• Init: sandcastle init, the config directory, issue trackers, templates and the Dockerfile.
• Run logs: log-to-file mode, terminal mode, and agent stream events.
• Reference: run() and createSandbox(), every option and result field, and the CLI commands.