Setup Sandcastle

Setup Sandcastle

One-time guided setup. Installs Sandcastle and configures an isolated sandbox provider so agents can run in parallel without stepping on each other.

Workflow

Step 1 -- Detect environment

• Check if sandcastle is already installed (npx sandcastle --version or check package.json)
• Detect available container runtimes: Docker, Podman, or Firecracker
• Check if the project is TypeScript/JavaScript (Sandcastle is a TS library)
• Check for existing sandbox or container configuration

Present findings to user before proceeding.

If detection is ambiguous, use AskUserQuestion to clarify:

• If no container runtime detected: explain that Docker, Podman, or Firecracker is required, ask which they'd like to install, and link to install docs
• If the project is not JS/TS: explain Sandcastle is a TS library, ask if they still want to proceed (it can still orchestrate non-JS agent tasks inside containers)

Step 2 -- Ask user preferences

Use AskUserQuestion for each:

1. Sandbox provider -- which runtime to use:
   • Docker (recommended) -- most common, easiest setup
   • Podman -- rootless alternative to Docker
   • Firecracker (Vercel) -- microVM isolation, strongest sandboxing
2. Branch strategy -- how agent changes get merged back:
   • Auto-merge (recommended) -- commits merge back to the working branch automatically
   • PR per sandbox -- each sandbox run creates a PR for review
3. Default parallelism -- how many sandboxes can run concurrently:
   • Suggest based on available CPU/memory

Step 3 -- Install and configure

• Install Sandcastle from mattpocock/sandcastle: npm install sandcastle (or add to devDependencies)
• Verify the selected container runtime is running and accessible
• Create a minimal sandcastle.config.ts with the selected provider and branch strategy
• Run a smoke test: create a sandbox, run echo "hello", verify output, destroy sandbox

Step 4 -- Update CLAUDE.md

Append to CLAUDE.md:

## Sandboxed Execution

Use Sandcastle for isolated agent runs. Provider: {selected_provider}. Run `/sandcastle` to execute tasks in parallel sandboxes.

Step 5 -- Verify

• Show the user the generated config
• Confirm the smoke test passed
• Suggest trying /sandcastle with a simple task

Key rules

• Never install a container runtime for the user -- only detect and configure what's already available
• If no container runtime is found, explain what's needed and exit
• Idempotent -- running again detects existing setup and skips