Sandbox REPL/Claude Split Design

Status: Implemented (2026-02-24)

Split the sandbox environment so the Clojure REPL runs separately from Claude Code. This allows daemonizing the infrastructure while running Claude interactively.

Current State

Single claude container runs both nREPL (background process) and Claude CLI (foreground). The entrypoint starts nREPL, waits for it, then execs into claude. Cannot daemonize without also daemonizing claude.

Design

Docker Architecture

┌─────────────────────────────────────────────────────────────┐
│  orcha-sandbox-<feature>                                    │
│                                                             │
│  ┌──────────┐  ┌────────────┐  ┌──────────────────────────┐ │
│  │ postgres │  │ localstack │  │ repl                     │ │
│  │ :5432    │  │ :4566      │  │ JDK + Clojure + nREPL    │ │
│  └──────────┘  └────────────┘  │ :7888                    │ │
│                                └──────────────────────────┘ │
│                                              ▲              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │ claude (ephemeral, docker-compose run)                  ││
│  │ Node + claude CLI + clj-nrepl-eval                      ││
│  │ connects to repl:7888                                   ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

Dockerfiles

Dockerfile.repl — JDK, Clojure, Babashka. Runs nREPL as main process (not backgrounded). Entrypoint initializes AWS resources then starts nREPL in foreground.

Dockerfile.claude — Node, Claude CLI, clj-nrepl-eval (MCP tool for REPL access). Minimal image, no JDK needed.

Services (docker-compose.yml)

postgres — unchanged
localstack — unchanged
repl — new service, depends on postgres/localstack health, exposes nREPL port to host
claude — ephemeral (run via docker-compose run), no health dependencies, just needs network access

Command Interface

Command	Behavior
`sandbox:start <branch>`	Setup worktree, `docker-compose up` (foreground)
`sandbox:start <branch> -d`	Setup worktree, `docker-compose up -d` (daemon)
`sandbox:claude <branch>`	Setup worktree, `docker-compose run --rm claude`
`sandbox:stop <branch>`	`docker-compose down`
`sandbox:logs <branch> [service]`	`docker-compose logs -f [service]`

Worktree setup (branch detection, confirmation, creation) is shared between start and claude.

Networking

Docker-compose creates network orcha-sandbox-<feature>_default. All services including ephemeral claude containers attach to it.

Claude's clj-nrepl-eval connects to repl:7888
Repl connects to postgres:5432 and localstack:4566
Host port exposure (${NREPL_HOST_PORT}:7888) on repl service

Volume Mounts

repl service:

Worktree → /workspace
.m2 cache

claude service:

Worktree → /workspace
~/.claude.json, ~/.claude/ (Claude config)
.claude-sandbox/projects (isolated conversation history)

Updates to Existing Commands

sandbox:expose/unexpose/exposed — reference repl container instead of claude container for port forwarding

Constraints

One active claude instance per sandbox at a time