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.

sandcastle init is the first command you run in a new repo. It scaffolds the .sandcastle/ config directory with everything Sandcastle needs: a container image definition, a prompt template, and environment variable placeholders. You choose a sandbox provider (Docker or Podman), an agent, a backlog manager, and a workflow template during the interactive prompts — or pass flags to skip them.

​
Usage

npx sandcastle init
Sandcastle walks you through a series of prompts and creates the config directory. Once it finishes, copy the generated .env.example and fill in your API key: 
cp .sandcastle/.env.example .sandcastle/.env

​
Options

​
--image-name
string
Docker or Podman image name to use. Defaults to sandcastle:<repo-dir-name>, derived from the basename of your repo directory.
​
--agent
string
Agent to use. Accepted values: claude-code, pi, codex, opencode. If omitted, sandcastle init prompts you to choose interactively.
​
--model
string
Model to use with the chosen agent (for example, claude-sonnet-4-6). Defaults to the agent’s default model if omitted.
​
--template
string
Template to scaffold. Accepted values: blank, simple-loop, sequential-reviewer, parallel-planner, parallel-planner-with-review. If omitted, sandcastle init prompts you to choose interactively.

​
Files created

After a successful init, your repo will contain: 
.sandcastle/
├── Dockerfile        # Sandbox environment (Containerfile when using Podman)
├── prompt.md         # Agent instructions
├── .env.example      # Environment variable placeholders
└── .gitignore        # Ignores .env and logs/
The Dockerfile (or Containerfile for Podman) is pre-configured for the agent you chose and includes Dockerfile snippets for your selected backlog manager. You can customize it freely — add language runtimes, install additional tools, or change the base image. Run sandcastle docker build-image (or sandcastle podman build-image) after any change to rebuild the image. prompt.md contains starter instructions suited to the template you selected. Edit it to describe the work you want the agent to perform. .env.example lists the environment variables the chosen agent needs — for example, ANTHROPIC_API_KEY for Claude Code. Copy it to .env and fill in your values. The generated .gitignore ensures .env is never committed.

​
File name: main.ts vs main.mts

sandcastle init also scaffolds the main orchestration script. If your project’s package.json contains "type": "module", the file is named main.ts. Otherwise it is named main.mts. Both are TypeScript files — the extension difference only affects how Node.js’s module system resolves them.

​
Getting started after init

1

Copy and fill in the environment file

cp .sandcastle/.env.example .sandcastle/.env
Open .sandcastle/.env and set ANTHROPIC_API_KEY (or whichever key your agent requires).
2

Build the container image

npx sandcastle docker build-image
Or, if you chose Podman during init:
npx sandcastle podman build-image
3

Run the scaffolded script

npx tsx .sandcastle/main.ts

​
Error: .sandcastle/ already exists

sandcastle init errors immediately if a .sandcastle/ directory already exists in the repo. This prevents accidental overwrites of your Dockerfile customizations or prompt templates. If you want to try a different template, either run sandcastle init in a fresh directory or remove .sandcastle/ first.
Removing .sandcastle/ is irreversible. Back up any customizations — particularly your Dockerfile and prompt.md — before deleting the directory.

Build docs developers (and LLMs) love

Get started for freeTalk to us