Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mattpocock/sandcastle/llms.txt

Use this file to discover all available pages before exploring further.

An agent provider is a pluggable implementation that builds commands and parses output for a specific AI coding tool. You inject one into run() via the agent option, and Sandcastle handles the rest — launching the agent inside the sandbox, streaming its output, and capturing results.

​
Built-in providers

Sandcastle ships with four built-in agent providers. All four are exported from the main package: 
import { claudeCode, codex, opencode, pi } from "@ai-hero/sandcastle";
ProviderImport nameExample model
Claude CodeclaudeCode"claude-opus-4-7"
Codexcodex"gpt-5.4-mini"
OpenCodeopencode"opencode/big-pickle"
Pipi—

​
Passing an agent to run()

Every call to run() requires an agent option. Call the provider factory with a model string — and optionally a second argument for provider-specific options — and pass the result: 
import { run, claudeCode } from "@ai-hero/sandcastle";
import { docker } from "@ai-hero/sandcastle/sandboxes/docker";

await run({
  agent: claudeCode("claude-opus-4-7"),
  sandbox: docker(),
  promptFile: ".sandcastle/prompt.md",
});
To pass provider-specific options, use the optional second argument: 
await run({
  agent: claudeCode("claude-opus-4-7", { effort: "high" }),
  sandbox: docker(),
  promptFile: ".sandcastle/prompt.md",
});

​
Custom agent providers

If you need to integrate a tool that isn’t covered by the built-in providers, you can implement the AgentProvider interface directly. A custom provider declares its env variables, implements buildPrintCommand to produce the shell command Sandcastle runs inside the sandbox, and implements parseStreamLine to translate each line of stdout into structured events.

Claude Code

Effort levels, session capture, and session resume for Claude Code.

Other agents

Codex, OpenCode, and Pi provider references.

Build docs developers (and LLMs) love

Get started for freeTalk to us