psyb0t/claudebox repository overview

Source⁠ | Project page⁠

⁠claudebox

A runtime harness for Claude Code⁠, the agentic coding CLI from Anthropic. The standard wrapper runs Claude in Docker with a mounted workspace, persistent Claude and SSH state, passwordless sudo, the host Docker socket, and --permission-mode bypassPermissions enabled by default.

Host boundary: this is not a sandbox for untrusted prompts. The standard wrapper mounts /var/run/docker.sock, so Claude can control the host Docker daemon. The server Compose examples omit it. Keep the socket out of server deployments unless the workload needs that authority. Use memory, CPU, PID, and log limits for long running containers. The current image installs Claude Code on first start and changes its runtime identity during boot, so do not add read_only: true or drop all capabilities unless you have tested that exact image and launch path.

claudebox wraps Claude Code with several distinct interfaces:

• Interactive CLI — a drop-in replacement for the native claude command, with persistent containers and automatic session resumption across runs
• Programmatic CLI — non-interactive mode for scripts, CI/CD pipelines, and automation; pass a prompt, get structured output, pipe it wherever you need
• HTTP API server — a full REST API with workspace management, file operations, structured output formats, and workspace isolation for multi-tenant deployments
• OpenAI-compatible endpoint — a chat/completions adapter that lets LiteLLM, OpenAI SDKs, and any OpenAI-compatible client talk to Claude Code, complete with streaming SSE, multi-turn conversations, and multimodal image handling
• MCP server — a Model Context Protocol⁠ endpoint over streamable HTTP so other AI agents and tools (Claude Desktop, other Claude Code instances, etc.) can use Claude Code as a tool
• Telegram bot — a conversational interface with per-chat workspaces, configurable models and effort levels, file sharing, and group chat access control
• Cron scheduler — YAML defined Claude jobs running on cron schedules with durable per-job artifacts, second resolution, and overlap protection

Beyond just running Claude Code in Docker, claudebox adds skill injection (auto-load SKILL.md files into every session), init hooks, custom script directories, structured JSON logging, and a workspace management layer that handles multi-tenant isolation with automatic busy/idle tracking.

⁠Table of Contents

• Requirements⁠
• Quick Start⁠
• Using the claudebox wrapper⁠
• Image Variants⁠
• What's Inside (Full Image)⁠
• Authentication⁠
• Modes⁠
  • Interactive mode⁠
  • Programmatic mode⁠
  • API mode⁠
  • Telegram mode⁠
  • Cron mode⁠
  • MCP mode⁠
• Configuration⁠
• Agent integrations⁠
• Gotchas⁠
• License⁠

⁠Requirements

Docker installed and running. That's it.

⁠Quick Start

⁠One-liner install

The install script pulls the Docker image, generates SSH keys for git operations inside the container, downloads the wrapper script, and installs it as a command on your system.

# minimal image — default; Claude installs what it needs on the fly
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash

# full image — every dev tool pre-installed (Go, Python, kubectl, terraform, ...)
export CLAUDEBOX_FULL=1 && curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash

# custom binary name (e.g. if you want to call it 'claude' instead of 'claudebox')
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash -s -- claude
# or: export CLAUDEBOX_BIN_NAME=claude && curl -fsSL .../install.sh | bash

The remote installer downloads wrapper.sh from its matching release tag. Automation can set CLAUDEBOX_INSTALL_DIR, CLAUDEBOX_BIN_NAME, and AICODEBOX_MANAGED_INSTALL=1 when it installs into a different command directory without prompting to replace an existing SSH key.

⁠Manual setup

If you prefer not to pipe scripts to bash:

# 1. create the data directory
mkdir -p ~/.claude

# 2. create SSH keys for git operations inside the container
mkdir -p "$HOME/.ssh/claudebox"
ssh-keygen -t ed25519 -C "[email protected]" -f "$HOME/.ssh/claudebox/id_ed25519" -N ""
# then add the public key to GitHub/GitLab/wherever you push code

# 3. pull the image
docker pull psyb0t/claudebox:latest        # minimal (default)
# or: docker pull psyb0t/claudebox:latest-full   # toolchain-loaded variant

# 4. grab the wrapper script and install it
# see install.sh for exactly how the wrapper is set up

⁠Using the claudebox wrapper

Run claudebox from the directory you want Claude to work in. The wrapper mounts that directory at the same absolute path inside the container, persists ~/.claude and ~/.ssh/claudebox, and resumes the directory's interactive session by default.

claudebox                                  # interactive Claude in this directory
claudebox --no-continue                    # interactive session without resuming
claudebox -p "explain this codebase"        # one prompt, then exit
claudebox setup-token                      # save OAuth credentials in ~/.claude
claudebox doctor                           # passthrough to Claude Code diagnostics
claudebox --version                        # passthrough to Claude Code
claudebox stop                             # stop this directory's running container
claudebox clear-session                    # remove saved sessions, keep auth/config

Set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN on the host for a run, or use claudebox setup-token once. Use claudebox -p "prompt" for a direct programmatic run. See Configuration⁠ for CLAUDEBOX_ENV_*, CLAUDEBOX_MOUNT_*, image selection, and mode settings.

⁠Agent use and nested launches

The installed wrapper is the normal interface for people and agents. An agent should run claudebox from the requested workspace instead of constructing a new docker run command. The wrapper preserves the workspace path, Claude state, SSH state, image choice, and container lifecycle.

claudebox -p "inspect this workspace and report the failing tests"
CLAUDEBOX_FULL=1 claudebox -p "run the full test suite"
claudebox -p "emit machine-readable events" --output-format stream-json

When one box needs another, install claudebox, codexbox, and pibox in the same command directory. A running box can call the sibling command directly. The parent wrapper passes the host launch context and mounts only the sibling wrapper file. Do not set AICODEBOX_HOST_*, copy a wrapper, or manually mount another box's state directory.

⁠Image Variants

⁠psyb0t/claudebox:latest (minimal, default)

The default v2 image. Just enough to run Claude Code on top of the aicodebox base: Ubuntu 24.04, git/curl/wget/jq, Node.js 24 LTS + npm, Python 3.14 + uv, Docker CE. Claude has passwordless sudo, so it will install whatever else it needs on the fly via apt-get, pip, npm, etc. Smaller image, faster pull, first run may take longer while Claude sorts out its own tooling.

curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash

Use /aicodebox-init.d/*.sh hooks (see Init Hooks⁠) to pre-install your tools on first container create so Claude doesn't burn tokens figuring out package management.

⁠psyb0t/claudebox:latest-full (toolchain-loaded)

Everything pre-installed. This variant starts from the immutable aicodebox:v0.17.0-full base, then adds only Claude-specific code. Aicodebox owns the shared Go, Python, Node, C/C++, DevOps, database, editor, and diagnostic toolchain; claudebox stays ready without rebuilding that stack.

export CLAUDEBOX_FULL=1 && curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-claudebox/master/install.sh | bash

⁠Comparison

⁠What's Inside (Full Image)

The shared toolchain is defined and released by aicodebox⁠. Claudebox adds its own adapter, init hooks, configuration, and first-run Claude Code installation on top.

Languages and runtimes:

• Go 1.26.8 with the full toolchain: golangci-lint, gopls, delve, staticcheck, gofumpt, gotests, impl, gomodifytags
• Python 3.14.7 via pyenv — flake8, black, isort, autoflake, pyright, mypy, vulture, pytest, poetry, pipenv, plus common libraries (requests, beautifulsoup4, lxml, pyyaml, toml)
• Node.js LTS — eslint, prettier, typescript, ts-node, yarn, pnpm, nodemon, pm2, framework CLIs (React, Vue, Angular), newman, http-server, serve, lighthouse, storybook
• C/C++ — gcc, g++, make, cmake, clang-format, valgrind, gdb, strace, ltrace

DevOps and infrastructure:

• Docker CE with Docker Compose (docker-in-docker support)
• Terraform, kubectl, helm, GitHub CLI (gh)

Database clients:

• sqlite3, postgresql-client (psql), mysql-client, redis-tools (redis-cli)

Shell and system utilities:

• jq, tree, ripgrep, bat, exa, fd-find, ag (silversearcher), htop, tmux, shellcheck, shfmt, httpie, vim, nano
• Archive tools (zip, unzip, tar), networking (net-tools, iputils-ping, dnsutils)

Container automation:

• Auto-generated CLAUDE.md in each workspace listing all available tools, so Claude knows what it has access to
• Git identity auto-configured from environment variables
• Claude Code CLI with auto-updates disabled by default (opt in with --update)
• Workspace trust dialog pre-accepted — no interactive prompts
• Custom scripts via ~/.claude/bin (added to PATH automatically)
• Init hooks via ~/.claude/init.d/*.sh (run once on first container create)
• Always-active skills via ~/.claude/.always-skills/ (injected into every invocation)
• Session continuity via --continue / --no-continue / --resume <session_id>
• Structured JSON debug logging with DEBUG=true

⁠Authentication

You need either an Anthropic API key or an OAuth token. Set up once, use everywhere:

# interactive OAuth token setup (one-time)
claudebox setup-token

# then use the token for programmatic and headless runs
CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token claudebox -p "do stuff"

# or use an API key directly
ANTHROPIC_API_KEY=your-api-key claudebox -p "do stuff"

⁠Modes

claudebox can run in several modes — pick the one that matches how you want to use Claude Code. Each has its own page with full setup, env vars, and examples.

⁠Interactive Mode →⁠

Drop-in replacement for claude. Persistent per-workspace container, automatic session resumption, plus utility commands like claudebox doctor, claudebox mcp list, claudebox stop, and claudebox clear-session.

claudebox

⁠Programmatic Mode →⁠

Non-interactive prompt → response for scripts, pipelines, and automation. Plain text, JSON, and native stream-json output formats. Model selection, system prompt overrides, JSON-schema-constrained output, and session continuation. For a stable full-event response, use API mode with eventMode: "full".

claudebox -p "explain this codebase" --output-format json --model haiku

⁠API Mode →⁠

Run as a long-lived HTTP server. Full REST API for prompts and file ops with workspace isolation, async runs with run-id polling, OpenAI-compatible chat/completions endpoint (streaming + multimodal + LiteLLM compatible), and an MCP⁠ endpoint over streamable HTTP so other agents can use Claude Code as a tool.

environment:
  - CLAUDEBOX_API_MODE=1
  - CLAUDEBOX_API_MODE_TOKEN=your-secret-token

⁠Telegram Mode →⁠

Talk to Claude from Telegram. Per-chat isolated workspaces, configurable models, effort, and system prompts, explicit chat and group user access control, file, photo, video, and voice ingestion, /fetch, /cancel, /status, /config, and /reload commands, plus [SEND_FILE: path] for Claude to send files back.

environment:
  - CLAUDEBOX_TELEGRAM_MODE=1
  - CLAUDEBOX_TELEGRAM_MODE_TOKEN=...

⁠Cron Mode →⁠

YAML defined scheduled jobs. Use five field cron for minute resolution or six field cron for second resolution. Per-job artifacts live under $HOME/.aicodebox/cron/history/, docker logs shows each tick, and same-name overlaps are skipped. Set root defaults and override them per job as needed.

environment:
  - CLAUDEBOX_CRON_MODE=1
  - CLAUDEBOX_CRON_MODE_FILE=/home/aicode/.aicodebox/cron.yaml

⁠MCP Mode →⁠

Expose Claude Code as an MCP⁠ server over streamable HTTP so other agents can drive it as a tool through run_prompt and workspace-confined file tools. MCP is not a foreground mode. With CLAUDEBOX_MCP_MODE=1, it mounts at /mcp/ in API mode or runs as a sidecar on its own port with Telegram, cron, or interactive mode.

environment:
  - CLAUDEBOX_MCP_MODE=1
  - CLAUDEBOX_MCP_MODE_TOKEN=your-secret-token

⁠Configuration

• Environment variables →⁠ — full table of CLAUDEBOX_* settings the wrapper and entrypoint understand, plus CLAUDEBOX_ENV_* (forward arbitrary vars into the container) and CLAUDEBOX_MOUNT_* (extra volume mounts).
• Customization →⁠ — extend Claude's container with custom scripts (~/.claude/bin), one-time init hooks (~/.claude/init.d), always-active skills auto-injected into every session (~/.claude/.always-skills), and MCP server definitions (project .mcp.json or global ~/.claude.json).

Install claudebox, codexbox, and pibox in the same command directory, normally /usr/local/bin, when one box needs to launch another. The wrapper finds sibling wrapper files there and mounts them read-only into the container. A sibling wrapper then runs through the host Docker daemon and mounts its own host data directory. Claudebox does not directly mount another agent's home.

AICODEBOX_HOST_* is the versioned nested-launch context used by sibling wrappers. It records host bind-source paths and is set automatically by a wrapper. Do not set it for an ordinary host launch.

⁠Agent integrations

The skill⁠ works in any agent that reads .agents/skills/. It tells agents to use the installed wrapper for local work and to use MCP only for an already-running remote server. It installs natively in the clients below.

⁠Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install claudebox@psyb0t

Claude Code prompts for the claudebox server URL and, if the MCP surface has auth enabled, the bearer token — the token is stored in your OS keychain.

⁠Codex

codex plugin marketplace add psyb0t/agents
codex plugin add claudebox@psyb0t

Installed via the marketplace, the skill invokes as $claudebox:claudebox. Codex also picks the skill up automatically, with no install, in any repo containing .agents/skills/ — there it invokes as plain $claudebox.

⁠OpenClaw

The skill is published to ClawHub on every release:

openclaw skills install @psyb0t/claudebox

For MCP clients that speak local stdio, the @psyb0t/claudebox⁠ plugin bridges to the service's /mcp/ endpoint:

openclaw plugins install clawhub:@psyb0t/claudebox

Then set CLAUDEBOX_URL (and CLAUDEBOX_MCP_MODE_TOKEN if the server requires auth).

⁠Gotchas

• --permission-mode bypassPermissions is the adapter's default (modern equivalent of the pre-v2 --dangerously-skip-permissions). Claude has full, unrestricted access to the container. That's the entire point. Override per-request via RunRequest.extra_args.
• SSH keys are mounted from the host for git push/pull inside the container. Do not share your container or image with untrusted parties.
• Host paths are preserved — your project at /home/you/project is mounted at the same path inside the container. This means Docker volume mounts that Claude creates from within the container resolve correctly against host paths.
• UID/GID matching — the container's claude user UID/GID is automatically adjusted to match the host directory owner on startup. File permissions should just work without manual chown.
• Docker-in-Docker — the Docker socket is mounted into the container. Claude can build images and run containers from within its container. This is by design.
• Two containers per workspace — the wrapper creates claude-<path> for interactive (TTY) sessions and claude-<path>_prog for programmatic (no TTY) sessions. Both share the same mounted volumes and data.
• Workspace busy tracking — in API mode, each workspace can only have one active Claude process at a time. Concurrent requests to the same workspace return a 409 Conflict response. Use different workspace subpaths for parallel work.
• Telegram config fallback is open by default — without telegram.yml, TELEGRAM_CHAT_ID becomes the only allowed chat. If both are absent, the compatibility fallback permits every chat. Use an explicit allowed_chats list before exposing the bot.
• Auto-updates disabled — Claude Code CLI auto-updates are disabled by default inside the container to ensure reproducible behavior. Opt in with claudebox --update when you want to update.

⁠License

WTFPL⁠ — do what the fuck you want to.