# Setup Sandcastle

> One-time setup skill that walks the user through installing and configuring Sandcastle for isolated sandbox environments. Configures the sandbox provider (Docker, Podman, or Firecracker), verifies the runtime, and adds sandbox defaults to CLAUDE.md. Use when user wants to enable parallelized agent work or sandboxed TDD.

- Skill: `mohganji/setup-sandcastle` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mohganji/setup-sandcastle`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mohganji/setup-sandcastle/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: mohganji (https://skillmd.com/u/mohganji)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mohganji/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](https://github.com/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:

```markdown
## 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