Claude Code in a Docker image built on aicodebox, with an HTTP API, an OpenAI-compatible endpoint...
10K+
Run Claude Code in Docker, from an interactive terminal, a script, an HTTP client, MCP, Telegram, or a cron schedule. Claudebox adds Claude-specific setup to the shared aicodebox runtime.
The wrapper mounts your current directory, persists Claude state and SSH keys, and resumes the workspace's last session by default.
Not a security sandbox: the standard wrapper uses host networking, mounts the host Docker socket, gives Claude passwordless sudo, and bypasses Claude's permission prompts. Use it only with trusted workloads. Separate workspace directories do not isolate untrusted tenants. Server examples omit the Docker socket.
You need Bash, Docker running and accessible to your user, curl, SSH key-generation tools, and sudo permission to install the wrapper. The installer pulls the image, creates Claude state and an SSH key, and installs the claudebox command.
Minimal image, the default:
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash
Full development image:
export CLAUDEBOX_FULL=1 && curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash
The full-image choice stays in the installed wrapper. Both variants install the pinned Claude Code CLI from npm when a fresh container first starts, so that start needs network access.
For a reviewed local install, a custom command name, image overrides, or wrapper updates, see Installation and wrapper. The remote installer currently fetches the wrapper from its embedded release ref, not necessarily master.
Run from the directory Claude should work in:
cd /path/to/project
claudebox
Authenticate in Claude Code, or supply ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN through your environment. claudebox setup-token runs Claude Code's OAuth token flow; keep the resulting token in a secret store and export it when needed.
claudebox --no-continue
claudebox -p "explain this codebase"
claudebox -p "review this codebase" --output-format json
claudebox -p "inspect the workspace" --output-format stream-json
claudebox stop
The wrapper supports a defined set of flags, not every native Claude Code argument. See Programmatic mode for output formats, model selection, and session control.
| Image | Contents |
|---|---|
psyb0t/claudebox:latest | Minimal aicodebox runtime, Claude adapter, and first-start setup. |
psyb0t/claudebox:latest-full | The same Claude interfaces plus aicodebox's shared development toolchain. |
The full variant adds Go and its tools, Python and Node development tools, C/C++ tools, infrastructure tools, database clients, and shell utilities. The shared Dockerfile.full and lockfiles own the package inventory. Neither Claudebox variant bundles the Claude Code CLI in the published image.
Set CLAUDEBOX_IMAGE to use an explicit image tag or digest. An existing container keeps its original image and launch configuration until recreated. See Wrapper lifecycle.
| Interface | Guide |
|---|---|
| Interactive terminal with persistent sessions | Interactive mode |
| One prompt with text, JSON, or native NDJSON output | Programmatic mode |
HTTP /run, files, async polling, and OpenAI-compatible chat | API mode |
| Streamable HTTP tools for other agents | MCP mode |
| Chat workspaces, attachments, and access lists | Telegram mode |
| Scheduled jobs and durable run artifacts | Cron mode |
API and MCP authentication are independent. An unset token leaves its endpoint open. Configure explicit Telegram chat access too. Use the loopback-bound deployment examples in each mode guide before exposing a server.
The full documentation lives at psyb0t.github.io/docker-claudebox.
| Section | Covers |
|---|---|
| Installation and wrapper | Install routes, image selection, authentication, Git identity, container lifecycle, host access |
| Modes | How the container picks a mode, and one page per mode |
| Environment variables | Wrapper settings, forwarded variables, extra mounts, sibling boxes |
| Customization | Your own scripts, init hooks, always-active skills, external MCP servers |
| GitHub Action | One-shot jobs with a read-only context and a writable output directory |
| Agent integrations | The skill and plugins for Claude Code, Codex and OpenClaw |
| Architecture | What claudebox adds to aicodebox, and the startup order |
| Troubleshooting | Error messages and their fixes |
| Upgrading | The old docker-claude-code names, v2 changes, legacy variables |
| Development | Building, lint, tests and CI |
make help
make build
make lint
make test-ci
make lint and make test-ci run in containers and need only Docker. See Development for the other test suites and base-image overrides.
WTFPL. Previously named docker-claude-code with the image psyb0t/claude-code; see Upgrading and the CHANGELOG.
Content type
Image
Digest
sha256:bb60e00bc…
Size
452.8 MB
Last updated
2 days ago
docker pull psyb0t/claudebox