HUB
Sign inSign up

psyb0t/claudebox

By psyb0t

•Updated 2 days ago

Claude Code in a Docker image built on aicodebox, with an HTTP API, an OpenAI-compatible endpoint...

Image
0

10K+

psyb0t/claudebox repository overview

Source⁠ | Project page⁠

⁠claudebox

CI version license Docker Pulls

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.

⁠Install

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.

⁠First run

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 variants

ImageContents
psyb0t/claudebox:latestMinimal aicodebox runtime, Claude adapter, and first-start setup.
psyb0t/claudebox:latest-fullThe 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⁠.

⁠Modes

InterfaceGuide
Interactive terminal with persistent sessionsInteractive mode⁠
One prompt with text, JSON, or native NDJSON outputProgrammatic mode⁠
HTTP /run, files, async polling, and OpenAI-compatible chatAPI mode⁠
Streamable HTTP tools for other agentsMCP mode⁠
Chat workspaces, attachments, and access listsTelegram mode⁠
Scheduled jobs and durable run artifactsCron 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.

⁠Documentation

The full documentation lives at psyb0t.github.io/docker-claudebox⁠.

SectionCovers
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

⁠Development

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.

⁠Sponsor

Buy Me a Coffee

⁠License

WTFPL⁠. Previously named docker-claude-code with the image psyb0t/claude-code; see Upgrading⁠ and the CHANGELOG⁠.

Tag summary

Content type

Image

Digest

sha256:bb60e00bc…

Size

452.8 MB

Last updated

2 days ago

docker pull psyb0t/claudebox