Reference
Glossary
On this page
The words these docs use, one entry each, in alphabetical order. Each guide page links a term to its entry the first time it mentions it.
Agent
The AI coding tool Sandcastle runs for you, such as Claude Code or Codex. It runs inside a sandbox, and you can swap one agent for another. See Core concepts.
Agent provider
The function that tells Sandcastle how to run one kind of agent: claudeCode(), codex(), pi() and the rest. You pass it to run() as the agent option. See Agent providers.
Agent session
The agent's own record of a conversation, which Sandcastle captures after each iteration. The agent provider decides where it lives, for example ~/.claude/projects/ for Claude Code. You can resume or fork it. See Agent sessions.
Agent stream event
One item from the agent's output as it runs: a text chunk or a toolCall, with its iteration number and a timestamp. Pass an onAgentStreamEvent callback to the logging option to receive them, in log-to-file mode only. See Run logs.
Bind-mount sandbox provider
A sandbox provider that mounts your repo from the host straight into the sandbox, so the agent edits the real files. Docker, Podman and the native sandbox providers work this way. See Sandbox providers.
Branch (branch strategy)
The branch strategy that puts the agent's commits on a branch you name, in a worktree: { type: "branch", branch: "agent/fix-42" }. See Branch strategies.
Branch strategy
How the agent's commits relate to your branches: head, merge-to-head or branch. You choose one per run; leave it out and the kind of sandbox provider picks one. See Branch strategies.
Build-image
The CLI command that rebuilds a provider's container image, such as sandcastle docker build-image. See Sandbox providers.
Built-in prompt argument
A prompt argument Sandcastle fills in for you, such as {{SOURCE_BRANCH}}, so you don't pass it in promptArgs. See Prompts.
Completion signal
The <promise>COMPLETE</promise> marker an agent prints to say there is nothing left to do. Sandcastle stops running iterations when it sees it. It carries no data: for that, use structured output. See Iterations.
Completion timeout
How long Sandcastle waits, once it has seen the completion signal, for the agent's process to exit. Each new line of output restarts the wait, so trailing output is still captured. If it runs out, the run still succeeds, with a warning about a hanging process. Set it with completionTimeoutSeconds (default 60). See Iterations.
Config directory
The .sandcastle/ directory in your repo, which init creates. It holds the main file that calls run(), the prompt, a Dockerfile for Docker, and the .env for your tokens. See Init.
Hanging process
An agent that has printed its completion signal but whose process has not exited, usually because a child process it started still holds its output open. Sandcastle ends the wait after the completion timeout. See Iterations.
Head (branch strategy)
The branch strategy where the agent works directly in your working directory on the host, with no worktree and no extra branch. See Branch strategies.
Host
Your machine: where Sandcastle runs and your real git repo lives, as opposed to the sandbox. See Core concepts.
Host hook
A hook that runs a shell command on the host, not inside the sandbox: { command: string }. See Hooks.
Init
sandcastle init, the command that sets up the config directory in your repo. See Init.
Inline prompt
A prompt you pass as a string with the prompt option. Sandcastle passes it to the agent as written: no prompt arguments and no shell expressions. See Prompts.
Isolated sandbox provider
A sandbox provider whose sandbox has its own filesystem, such as Vercel or Daytona. Sandcastle copies your code in and brings the agent's commits back out. See Sandbox providers.
Issue tracker
Where the agent finds its tasks, chosen during init: GitHub Issues or Beads, for example. See Init.
Iteration
One run of the agent inside the sandbox, making at most one commit for one task. maxIterations sets how many a run may take. See Iterations.
Log-to-file mode
The display mode where Sandcastle writes progress and agent output to a run log instead of the terminal. See Run logs.
Merge-to-head (branch strategy)
The branch strategy where Sandcastle gives the agent a temporary branch in a worktree, then merges its commits back into your current branch. See Branch strategies.
Native sandbox provider
A bind-mount sandbox provider that uses your operating system's own process sandbox (Bubblewrap on Linux, Seatbelt on macOS) instead of a container, so the agent uses the tools already on your host. See Sandbox providers.
No-sandbox provider
noSandbox(), the sandbox provider that creates no sandbox at all: the agent runs directly on your host. See Sandbox providers.
Output schema
The validator, such as a Zod schema, that you pass to Output.object() to parse and check structured output. See Structured output.
Prompt
The instructions the agent gets at the start of each iteration: an inline prompt or a prompt template. See Prompts.
Prompt argument
A value you pass in promptArgs to fill a {{KEY}} placeholder in a prompt template. See Prompts.
Prompt argument substitution
The step that replaces each {{KEY}} in a prompt template with its prompt argument, each time the prompt is used. See Prompts.
Prompt expansion
The step that runs each shell expression in a prompt template and puts its output in its place. See Prompts.
Prompt template
A prompt read from a file with the promptFile option. It can hold {{KEY}} placeholders and !`command` shell expressions, which Sandcastle fills in before the agent sees it. See Prompts.
Remove-image
The CLI command that removes a provider's container image, such as sandcastle docker remove-image. See Sandbox providers.
Run log
The log file Sandcastle writes to .sandcastle/logs/ in log-to-file mode. See Run logs.
Sandbox
The boundary around the agent: a container, a VM or an OS process sandbox that limits what it can reach. See Core concepts.
Sandbox hook
A hook that runs a shell command inside the sandbox, optionally with sudo: { command: string; sudo?: boolean }. See Hooks.
Sandbox provider
The function that creates and manages a sandbox, such as docker() or bwrap(). You pass it to run() as the sandbox option. See Sandbox providers.
Session fork
Starting a new agent session from an existing one, with a new session ID, leaving the original untouched. Call fork() on a run's result. It copies the session only, not the branch or the sandbox. See Agent sessions.
Session resume
Continuing an agent session by adding new turns to the same record, under the same session ID. Call resume() on a run's result. See Agent sessions.
Shell expression
A !`command` marker in a prompt template. Sandcastle runs the command inside the sandbox and replaces the marker with its output. A marker inside an HTML comment never runs. See Prompts.
Source branch
The branch the agent works on. The branch strategy decides which one it is. See Branch strategies.
Structured output
A typed JSON answer the agent prints inside an XML tag you choose, which Sandcastle checks against your output schema and returns on result.output. Your prompt has to ask for the tag. See Structured output.
Target branch
The branch you had checked out when you called run(): the one Sandcastle merges into with merge-to-head. See Branch strategies.
Task
A piece of work from the issue tracker that the agent picks up and works on during an iteration. See Init.
Template argument
A {{KEY}} placeholder in a file init scaffolds, such as the Dockerfile or the prompt, which init fills in from your choices. See Init.
Template argument substitution
The step during init that replaces each template argument with its value. See Init.
Terminal mode
The display mode where Sandcastle shows progress in the terminal, with spinners and status messages. See Run logs.
Worktree
A git worktree Sandcastle creates in .sandcastle/worktrees/ on your host for the merge-to-head and branch strategies. A bind-mount provider mounts it into the sandbox; an isolated provider syncs it in and pulls the commits back to it. Create one yourself with createWorktree(). See Branch strategies.