Claude Sandbox Design

Sandboxed Claude Code environment for autonomous agent work on the Orcha monorepo.

Goals

• Claude Code runs inside Docker (not on host)
• Uses --dangerously-skip-permissions safely because it's sandboxed
• Worktree code is the only host filesystem Claude can access
• Each sandbox includes: postgres, localstack, nREPL
• nREPL exposed to host for editor connection

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        sandbox-network                               │
│                                                                      │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    claude-sandbox                            │    │
│  │                                                              │    │
│  │   ┌──────────────┐    ┌──────────────┐    ┌─────────────┐   │    │
│  │   │ Claude Code  │───▶│ clj-nrepl-eval│───▶│   nREPL     │   │    │
│  │   │   (TTY)      │    │              │    │  :7888      │   │    │
│  │   └──────────────┘    └──────────────┘    └─────────────┘   │    │
│  │         │                                        │          │    │
│  │         │              Clojure app connects to:  │          │    │
│  │         │              - postgres:5432           │          │    │
│  │         │              - localstack:4566         │          │    │
│  │         ▼                                        ▼          │    │
│  │   /workspace (mounted worktree)                             │    │
│  │   /root/.claude (host auth + sandbox projects)              │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                      │
│  ┌──────────────┐              ┌──────────────┐                     │
│  │   postgres   │              │  localstack  │                     │
│  │    :5432     │              │    :4566     │                     │
│  └──────────────┘              └──────────────┘                     │
└─────────────────────────────────────────────────────────────────────┘

File Structure

orcha/
├── sandbox/
│   ├── docker-compose.yml    # Sandbox services
│   ├── Dockerfile            # Claude + Clojure + Babashka image
│   └── entrypoint.sh         # Starts nREPL, then Claude
├── .worktrees/
│   └── feature/
│       └── <name>/
│           ├── .claude-sandbox/
│           │   └── projects/     # Conversation persistence
│           ├── .nrepl-port       # Port file for editor connection
│           └── <code>
└── .gitignore                    # Add .claude-sandbox/

Container Image

sandbox/Dockerfile:

• Base: eclipse-temurin:21-jdk-alpine
• Clojure CLI
• Babashka + bbin
• clj-nrepl-eval (via bbin)
• Node.js + Claude Code CLI

Docker Compose

sandbox/docker-compose.yml:

• Project name: orcha-sandbox-${FEATURE_NAME} (isolates volumes)
• Services: postgres, localstack, claude
• Claude depends on healthy postgres/localstack
• Volumes:
  • ${WORKTREE_PATH}:/workspace
  • ${HOME}/.claude:/root/.claude:ro (auth from host)
  • ${WORKTREE_PATH}/.claude-sandbox/projects:/root/.claude/projects (persistence)
  • ${HOME}/.m2:/root/.m2 (Maven deps)
  • ${HOME}/.gitlibs:/root/.gitlibs (Git deps)
  • ${HOME}/.clojure/.cpcache:/root/.clojure/.cpcache (classpath cache)
• Port: ${NREPL_HOST_PORT}:7888 (nREPL to host)

nREPL Configuration

Entrypoint starts nREPL with cider middleware:

clojure -Sdeps '{:deps {nrepl/nrepl {:mvn/version "1.3.1"}
                        cider/cider-nrepl {:mvn/version "0.56.0"}
                        refactor-nrepl/refactor-nrepl {:mvn/version "3.11.0"}}
                 :aliases {:cider/nrepl {:main-opts ["-m" "nrepl.cmdline"
                           "--middleware" "[refactor-nrepl.middleware/wrap-refactor,cider.nrepl/cider-middleware]"]}}}' \
    -M:dev:test:cider/nrepl \
    -p 7888 \
    -b 0.0.0.0

User can start full Integrant system with (go) if needed.

Port Allocation

• Default: hash(feature-name) % 1000 + 17000 → range 17000-17999
• Override: bb sandbox:start foo --port 18000
• Always written to .worktrees/feature/<name>/.nrepl-port

Clojure App Configuration

Add :sandbox profile to config.edn:

:com.getorcha/aws
{:config {:endpoint #profile {:local-dev "http://localhost:4566"
                              :sandbox   "http://localstack:4566"
                              :default   nil}}}

:com.getorcha/db-credentials-json
#profile {:local-dev "{\"host\":\"localhost\",...}"
          :sandbox   "{\"host\":\"postgres\",...}"
          :default   #orcha/param "/v1-orcha/db-credentials"}

Profile activated via ENVIRON_NAME=sandbox in entrypoint.

bb Tasks

bb sandbox:start <name> [--port PORT]   # Create worktree, start containers, attach to Claude
bb sandbox:stop <name>                  # Stop containers
bb sandbox:list                         # List running sandboxes
bb sandbox:clean <name> [--worktree]    # Remove containers/volumes, optionally worktree

Workflow

Start:

$ bb sandbox:start booking-ocr
Creating worktree .worktrees/feature/booking-ocr from main...
nREPL will be exposed on port 17342
Starting sandbox containers...
claude>

Connect editor:

$ cat .worktrees/feature/booking-ocr/.nrepl-port
17342
# Connect to localhost:17342

Resume after exit:

$ bb sandbox:start booking-ocr
# Worktree exists, just starts containers
# Conversation history preserved in .claude-sandbox/projects/

Clean up:

$ bb sandbox:clean booking-ocr --worktree

Auth Strategy

• Host ~/.claude/ mounted read-only for subscription auth
• .claude-sandbox/projects/ overlays for conversation persistence
• No API key needed; uses Claude subscription

Dependency Caching

Host directories mounted read-write to avoid re-downloading:

• ~/.m2 - Maven deps
• ~/.gitlibs - Git deps
• ~/.clojure/.cpcache - Classpath cache