claudebox
Run Claude Code in Docker, from an interactive terminal, a script, an HTTP client, MCP, Telegram, or a cron schedule. The image psyb0t/claudebox adds the Claude-specific parts to the shared aicodebox runtime: an adapter that turns requests into claude command lines, a launcher that restores session resumption and the permission bypass, first-start setup, and CLAUDEBOX_* names for the shared settings.
The claudebox wrapper on the host mounts your current directory, keeps Claude state and SSH keys between runs, 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. The server examples on this site leave the Docker socket out. See Host access and server deployment.
Quick start
You need Bash, a running Docker daemon your user can reach, curl, ssh-keygen, and sudo to install the wrapper.
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash
Then run it from the directory Claude should work in:
cd /path/to/project
claudebox
Log in inside Claude Code, or export ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN first. One prompt, no TTY:
claudebox -p "explain this codebase"
claudebox -p "review this codebase" --output-format json
Installation and wrapper covers the full image, a reviewed install, image selection and the container lifecycle.
Image variants
| Image | Contents |
|---|---|
psyb0t/claudebox:latest | The minimal aicodebox runtime, the Claude adapter and the first-start setup. |
psyb0t/claudebox:latest-full | The same, on the aicodebox full base with Go, Python, Node, C/C++, infrastructure and database tools. |
Neither image contains the Claude Code CLI. Claude Code is proprietary, so each container installs the pinned version from npm the first time it starts, and that first start needs network access. Releases also publish :vX.Y.Z and :vX.Y.Z-full.
Ways to run it
| Interface | Page |
|---|---|
| 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 |
Modes explains how the container picks one and which ones combine.
Reference
- Environment variables: wrapper settings, forwarded variables, extra mounts and sibling boxes.
- Customization: your own scripts, first-start init hooks, always-active skills and 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 the aicodebox base, and what happens when a container starts.
- Troubleshooting: error messages from the wrapper, the entrypoint and the servers, with their fixes.
- Upgrading: the old
docker-claude-codenames, the v2 image swap, and the legacy variables that still work. - Development: build, lint and test from source, and what CI runs.