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.

This page documents the shared types that appear across run(), createSandbox(), createWorktree(), and interactive(). All types are exported from @ai-hero/sandcastle.

​
Sandbox provider types

Sandcastle dispatches on a tag discriminant to determine how to start and manage a sandbox at runtime.

​
SandboxProvider

type SandboxProvider = BindMountSandboxProvider | IsolatedSandboxProvider;
The union accepted by run() and createSandbox(). Does not include NoSandboxProvider — that is only valid for interactive().

​
AnySandboxProvider

type AnySandboxProvider =
  | BindMountSandboxProvider
  | IsolatedSandboxProvider
  | NoSandboxProvider;
The union accepted by interactive() and wt.interactive(). Adds NoSandboxProvider to the base union.

​
BindMountSandboxProvider

Providers that mount the host worktree directly into the container — no file transfer needed. Built-in examples: docker(), podman().
​
tag
"bind-mount"
Discriminant used for internal dispatch.
​
name
string
Human-readable provider name.
​
env
Record<string, string>
Environment variables injected by this provider at launch time.
​
sandboxHomedir
string | undefined
Absolute path to the home directory inside the sandbox (for example /home/agent). Used to expand ~ in sandboxPath mount configs.

​
IsolatedSandboxProvider

Providers with their own filesystem where the repo must be copied in and out. Built-in example: vercel().
​
tag
"isolated"
Discriminant used for internal dispatch.
​
name
string
Human-readable provider name.
​
env
Record<string, string>
Environment variables injected by this provider at launch time.

​
NoSandboxProvider

Runs the agent directly on the host with no container. Only valid for interactive() and wt.interactive().
​
tag
"none"
Discriminant used for internal dispatch.
​
name
string
Human-readable provider name.
​
env
Record<string, string>
Environment variables injected by this provider.

​
Custom providers

Create a bind-mount provider with createBindMountSandboxProvider(config) or an isolated provider with createIsolatedSandboxProvider(config), both exported from @ai-hero/sandcastle.

​
BranchStrategy

Controls where the agent’s commits land. Three variants are available. 
type BranchStrategy =
  | HeadBranchStrategy
  | MergeToHeadBranchStrategy
  | NamedBranchStrategy;

​
HeadBranchStrategy

interface HeadBranchStrategy {
  readonly type: "head";
}
The agent writes directly to the host working directory. No worktree is created. Only valid for bind-mount and no-sandbox providers. This is the default for bind-mount providers.

​
MergeToHeadBranchStrategy

interface MergeToHeadBranchStrategy {
  readonly type: "merge-to-head";
}
Sandcastle creates a temporary branch in a git worktree. The agent commits there; when the run finishes the changes are merged back to HEAD and the temp branch is deleted. This is the default for isolated providers.

​
NamedBranchStrategy

interface NamedBranchStrategy {
  readonly type: "branch";
  readonly branch: string;
  readonly baseBranch?: string;
}
Commits land on the explicitly named branch. The branch is created from baseBranch (defaults to HEAD) if it does not already exist.
​
type
"branch"
Strategy discriminant.
​
branch
string
The explicit branch name to create or check out.
​
baseBranch
string | undefined
Git ref to branch from when the branch does not yet exist. Defaults to HEAD.

​
SandboxHooks

Lifecycle hooks grouped by where they run. 
type SandboxHooks = {
  readonly host?: {
    readonly onWorktreeReady?: ReadonlyArray<{
      readonly command: string;
      readonly timeoutMs?: number;
    }>;
    readonly onSandboxReady?: ReadonlyArray<{
      readonly command: string;
      readonly timeoutMs?: number;
    }>;
  };
  readonly sandbox?: {
    readonly onSandboxReady?: ReadonlyArray<{
      readonly command: string;
      readonly sudo?: boolean;
      readonly timeoutMs?: number;
    }>;
  };
};

​
host.onWorktreeReady

Runs on the host after copyToWorktree completes, before the sandbox container starts. Working directory is the worktree path (or the host repo root under head strategy). Hooks run sequentially in declared order. Each entry accepts:
​
command
string
Shell command to run on the host.
​
timeoutMs
number
default:"60000"
Per-hook timeout in milliseconds. Overrides the default 60 s.

​
host.onSandboxReady

Runs on the host after the sandbox container is up, in parallel with sandbox.onSandboxReady. Working directory is the worktree path. Same entry shape as host.onWorktreeReady.

​
sandbox.onSandboxReady

Runs inside the sandbox container after it starts, in parallel with host.onSandboxReady. Working directory is the sandbox repo directory. Each entry accepts:
​
command
string
Shell command to run inside the sandbox.
​
sudo
boolean
Run the command with elevated privileges.
​
timeoutMs
number
default:"60000"
Per-hook timeout in milliseconds.
Ordering: copyToWorktree → host.onWorktreeReady (sequential) → sandbox created → host.onSandboxReady + sandbox.onSandboxReady (parallel).

​
MountConfig

A single bind-mount descriptor for docker() and podman() providers. Pass an array of these as mounts in the provider factory. 
interface MountConfig {
  readonly hostPath: string;
  readonly sandboxPath: string;
  readonly readonly?: boolean;
}
​
hostPath
string
Path on the host. Supports absolute paths (/data/cache), tilde-expanded paths (~/data), and relative paths (data) resolved from process.cwd().
​
sandboxPath
string
Path inside the sandbox container. Supports absolute paths, tilde-expanded paths (resolved using the provider’s sandbox home directory), and relative paths resolved from the sandbox repo directory.
​
readonly
boolean
default:"false"
Mount the directory as read-only.

​
Timeouts

Override default timeouts for built-in lifecycle steps. Unset keys keep their defaults. 
interface Timeouts {
  readonly copyToWorktreeMs?: number;
}
​
copyToWorktreeMs
number
default:"60000"
Timeout in milliseconds for the host-side copy of copyToWorktree paths into the worktree.

Build docs developers (and LLMs) love

Get started for freeTalk to us