# sandcastle | Matt Pocock | Knowledge Base | Instagit

Orchestrate sandboxed coding agents in TypeScript with sandcastle.run()

GitHub Stars: 4.9k

Repository: https://github.com/mattpocock/sandcastle

---

## Articles

### [How AbortSignal Cancels Runs and Preserves Worktrees in Sandcastle](/mattpocock/sandcastle/how-abortsignal-works-for-cancelling-runs-and-preserving-worktrees)

Learn how Sandcastle leverages AbortSignal to safely cancel agent sessions. Discover how it preserves worktrees with uncommitted changes, ensuring your work isn't lost.

- Tags: deep-dive
- Published: 2026-05-24

### [How to Pass Environment Variables to a Sandcastle Sandbox Using the `env` Option](/mattpocock/sandcastle/how-to-pass-environment-variables-to-sandbox-with-env-option)

Learn how to pass environment variables to your Sandcastle sandbox using the env option. Easily inject key-value pairs to override repository and agent variables for custom sandbox behavior.

- Tags: how-to-guide
- Published: 2026-05-24

### [How to Use the Parallel-Planner and Parallel-Planner-With-Review Templates in Sandcastle](/mattpocock/sandcastle/how-to-use-parallel-planner-templates-in-sandcastle)

Learn to use Sandcastle's parallel-planner and parallel-planner-with-review templates for parallel GitHub issue code management. Orchestrate plan, implement, review, and merge workflows.

- Tags: how-to-guide
- Published: 2026-05-24

### [What Files Can Be Copied Using `copyToWorktree` in Sandcastle?](/mattpocock/sandcastle/what-files-can-be-copied-with-copytoworktree)

Learn what files and directories copyToWorktree in Sandcastle can copy from your host repository root, including single files configurations and scripts.

- Tags: how-to-guide
- Published: 2026-05-24

### [How Does copyToWorktree Work in Sandcastle? Copy-on-Write Preloading Explained](/mattpocock/sandcastle/how-copytoworktree-feature-works-in-sandcastle)

Discover how Sandcastle's copyToWorktree uses copy-on-write semantics to efficiently clone host repository paths into worktrees. Learn about reflink support and fallback mechanisms.

- Tags: internals
- Published: 2026-05-24

### [How to Configure SELinux Labels for Docker Mounts Using the `selinuxLabel` Option in Sandcastle](/mattpocock/sandcastle/how-to-configure-selinux-labels-for-docker-mounts)

Master SELinux labels for Docker mounts in Sandcastle. Learn to use the selinuxLabel option with "z", "Z", or false for optimal security and context management. Secure your Docker sandbox.

- Tags: how-to-guide
- Published: 2026-05-24

### [createWorktree vs createSandbox in Sandcastle: Key Differences Explained](/mattpocock/sandcastle/sandcastle-createworktree-vs-createsandbox-difference)

Understand the key differences between createWorktree and createSandbox in Sandcastle. Learn how each function manages Git worktrees and sandbox execution for your projects.

- Tags: deep-dive
- Published: 2026-05-24

### [How to Create a Reusable Sandbox with `createSandbox()` for Multiple Agent Runs in Sandcastle](/mattpocock/sandcastle/how-to-create-reusable-sandbox-with-createsandbox)

Learn how to create a reusable sandbox with createSandbox() in Sandcastle for efficient multiple agent runs. Persist state and lifecycle for streamlined workflows.

- Tags: how-to-guide
- Published: 2026-05-24

### [How to Use Completion Signals to Stop Sandcastle Agent Iterations Early](/mattpocock/sandcastle/how-to-use-completion-signals-to-stop-iterations-early)

Learn how to use completion signals to stop Sandcastle agent iterations early and reduce token costs. Maximize LLM efficiency effortlessly.

- Tags: how-to-guide
- Published: 2026-05-24

### [How Session Capture Works in Sandcastle Using `sandboxSessionStore`](/mattpocock/sandcastle/how-session-capture-works-with-sandboxsessionstore)

Learn how session capture works in Sandcastle using sandboxSessionStore to extract, transfer, and persist AI agent session files for analysis. Understand the process clearly.

- Tags: internals
- Published: 2026-05-24

### [How Session Capture Works in Sandcastle Using `hostSessionStore`](/mattpocock/sandcastle/how-session-capture-works-with-hostsessionstore)

Discover how Sandcastle captures agent sessions with hostSessionStore. Learn how JSON-L session data is transferred and paths are rewritten for seamless host integration.

- Tags: how-to-guide
- Published: 2026-05-24

### [How to Configure Idle Timeout for Agent Runs Using `idleTimeoutSeconds` in Sandcastle](/mattpocock/sandcastle/how-to-configure-idle-timeout-for-agent-runs)

Learn to configure agent run idle timeout in Sandcastle using idleTimeoutSeconds. Prevent silent agent abortions and control wait times effectively. Get the details now!

- Tags: how-to-guide
- Published: 2026-05-24

### [How Shell Command Expansion Works in Sandcastle Prompts: A Deep Dive into `!`command` Syntax](/mattpocock/sandcastle/how-shell-command-expansion-works-in-sandcastle-prompts)

Understand shell command expansion with `!command` syntax in Sandcastle prompts. Learn how Sandcastle executes commands in containers, replaces blocks with stdout, and prevents injection.

- Tags: deep-dive
- Published: 2026-05-24

### [How to Use Prompt Argument Substitution with `{{KEY}}` Placeholders in Sandcastle](/mattpocock/sandcastle/how-to-use-prompt-argument-substitution-with-placeholders)

Learn to use prompt argument substitution with {{KEY}} placeholders in Sandcastle. Inject runtime values via --prompt-args for dynamic LLM agent interaction.

- Tags: how-to-guide
- Published: 2026-05-24

### [How Sandcastle Handles Git Worktree Cleanup with Uncommitted Changes](/mattpocock/sandcastle/sandcastle-worktree-cleanup-uncommitted-changes)

Sandcastle safely cleans Git worktrees with uncommitted changes. It automatically removes clean worktrees and preserves dirty ones for your review.

- Tags: how-to-guide
- Published: 2026-05-24

### [How to Configure Lifecycle Hooks like `onSandboxReady` in Sandcastle](/mattpocock/sandcastle/how-to-configure-onsandboxready-hook-in-sandcastle)

Learn to configure Sandcastle lifecycle hooks like onSandboxReady by passing a hooks object to createSandbox or the init command. Execute host or sandbox commands in parallel on container start.

- Tags: how-to-guide
- Published: 2026-05-24

### [How to Configure Lifecycle Hooks in Sandcastle: Complete Guide to onWorktreeReady](/mattpocock/sandcastle/how-to-configure-onworktreeready-hook-in-sandcastle)

Learn to configure Sandcastle lifecycle hooks like onWorktreeReady. Execute commands after worktree creation but before sandbox start with this complete guide.

- Tags: how-to-guide
- Published: 2026-05-24

### [How to Extract String Output from Agent Responses Using `Output.string()` in Sandcastle](/mattpocock/sandcastle/how-to-extract-string-output-with-output-string)

Learn how to extract string output from agent responses with Output.string() in Sandcastle. Easily get plain text from custom tags as a JavaScript string.

- Tags: how-to-guide
- Published: 2026-05-24

### [How to Extract Structured Output from Agent Responses Using `Output.object()`](/mattpocock/sandcastle/how-to-extract-structured-output-with-output-object)

Easily extract structured output from agent responses with Output.object(). Wrap LLM JSON in XML tags, validate against schemas, and get strongly typed objects.

- Tags: how-to-guide
- Published: 2026-05-24

### [Sandcastle resumeSession Constraints: Validation Rules and File Requirements](/mattpocock/sandcastle/sandcastle-resume-session-feature-constraints)

Explore Sandcastle resumeSession constraints. Learn about maxIterations validation rules and required file paths for uninterrupted Claude Code sessions.

- Tags: best-practices
- Published: 2026-05-24

### [How the Sandcastle `resumeSession` Feature Restores Claude Code Sessions](/mattpocock/sandcastle/how-resume-session-works-in-sandcastle)

Discover how Sandcastle's resumeSession feature restores Claude Code sessions by validating IDs, copying JSONL, and appending the resume flag. Learn more now.

- Tags: how-to-guide
- Published: 2026-05-24

### [Sandcastle Branch Strategies: head, merge-to-head, and branch Explained](/mattpocock/sandcastle/sandcastle-branch-merge-to-head-head-branch-strategies-differences)

Understand Sandcastle branch strategies head merge-to-head and branch. Learn how AI agents write and reconcile code in your repository for efficient development.

- Tags: deep-dive
- Published: 2026-05-24

### [How to Create a Custom Sandbox Provider in Sandcastle Using createIsolatedSandboxProvider](/mattpocock/sandcastle/how-to-create-custom-sandbox-provider-with-createisolatedsandboxprovider)

Learn to create a custom sandbox provider in Sandcastle using createIsolatedSandboxProvider. Implement IsolatedSandboxHandle for isolated agent execution.

- Tags: how-to-guide
- Published: 2026-05-24

### [How to Create a Custom Sandbox Provider in Sandcastle Using `createBindMountSandboxProvider`](/mattpocock/sandcastle/how-to-create-custom-sandbox-provider-with-createbindmountsandboxprovider)

Learn to create a custom sandbox provider in Sandcastle with createBindMountSandboxProvider. Implement key methods and pass your provider to run() or createSandbox() for flexible sandboxing.

- Tags: how-to-guide
- Published: 2026-05-24