claudebox

A small cross-platform launcher for an OpenAI-compatible API proxy for the Claude Code CLI, running in Docker — so you don't need a local Claude CLI install.

Install

npm install -g @chumano/claudebox
# or, without installing anything:
npx @chumano/claudebox start

This gives you a claudebox command that works the same on Linux, macOS, and Windows (it's a Node script — no shell-specific scripting involved).

Requirements: Docker, and a Claude CLI login on the host machine (claude login) so ~/.claude/.credentials.json exists — claudebox reads that file (read-only) to authenticate the container, it never touches the rest of your local ~/.claude.

Usage

# Run one prompt in a throwaway container (no server, auto-removed after)
claudebox prompt "explain how DNS works"
claudebox prompt --model opus "summarize this file"

# Start the HTTP API server in the background (pulls the image on first run)
claudebox start
claudebox start --port 8080 --workspace ./my-project

curl http://localhost:3456/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4","messages":[{"role":"user","content":"Hello!"}]}'

claudebox logs -f      # follow server logs
claudebox status       # is it running?
claudebox restart
claudebox stop

By default, --workspace is the directory you run claudebox from — it's mounted read-write at /workspace inside the container, so Claude Code's Read/Edit/Bash tools operate on your real files.

All options:

| Flag | Default | Meaning | | ---------------- | ------------------------ | ----------------------------------------- | | --port | 3456 | Host port to publish | | --workspace | current directory | Mounted at /workspace (Claude CLI's cwd) | | --config-dir | ~/.claude | Where .credentials.json is read from | | --state-dir | ~/.claudebox/state | Persistent container state (session cache) | | --image | ghcr.io/chumano/claudebox:<version> | Docker image tag (pulled by default) | | --name | claudebox | Container name | | --model | sonnet | Model for prompt | | --tools | all | Restrict available tools (comma list, or none) | | --no-build | off | Fail instead of auto-pulling/building a missing image |

Env var equivalents: CLAUDEBOX_PORT, CLAUDEBOX_WORKSPACE, CLAUDE_CONFIG_DIR, CLAUDEBOX_STATE_DIR, CLAUDEBOX_IMAGE, CLAUDEBOX_CONTAINER_NAME.