English Français العربية

Claudebox

Official registry Developer tools

Self-hosted MCP server exposing Claude Code as an agentic AI tool over streamable HTTP.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

OCI package docker.io/psyb0t/claudebox:v2.8.5
Claude Code 
claude mcp add claudebox -- docker run -i --rm docker.io/psyb0t/claudebox:v2.8.5
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "claudebox": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "docker.io/psyb0t/claudebox:v2.8.5"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. claudebox
  2. Install
  3. First run
  4. Image variants
  5. Modes
  6. Configuration and extensions
  7. Development
  8. Migration and license

claudebox

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

For all native events from HTTP POST /run, request "eventMode": "full". This works with or without jsonSchema. Events include the records Claude Code emits, such as tool calls, tool results, and available thinking content. It does not expose private reasoning that the CLI does not emit. /run returns a completed JSON response; use native stream-json for direct CLI streaming or the OpenAI endpoint's opt-in native SSE events.

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.

Configuration and extensions

  • Environment variables: wrapper settings, forwarded variables, extra mounts, and sibling boxes.
  • Customization: user scripts, first-container 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: local wrapper skills and remote MCP connections for Claude Code, Codex, and OpenClaw.

Install sibling claudebox, codexbox, and pibox wrappers in the same command directory for nested launches. Each sibling mounts its own host state. Do not manually set AICODEBOX_HOST_*.

Development

make help
make test-unit
make test-image-select
make test-programmatic-contract
make test-agent-launcher
make build
make build-full

Builds use the minimal or full aicodebox parent respectively. See Makefile for base-image overrides and the remaining checks. The adapter lives in claudebox/claudebox/adapter.py; the shared server modes live in aicodebox.

Migration and license

Previously named docker-claude-code with image psyb0t/claude-code. Current names are docker-claudebox, psyb0t/claudebox, and claudebox. In v2, latest became minimal and latest-full became the full variant. See CHANGELOG.md for migration history.

WTFPL.

Frequently asked questions

What is Claudebox?

Self-hosted MCP server exposing Claude Code as an agentic AI tool over streamable HTTP.

How do I install Claudebox?

It runs on your machine. In Claude Code: claude mcp add claudebox -- docker run -i --rm docker.io/psyb0t/claudebox:v2.8.5. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Claudebox need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is Claudebox open source?

Yes. Its code is on GitHub under the WTFPL license.

Who maintains Claudebox?

It is published by psyb0t. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.