Self-hosted MCP server exposing Claude Code as an agentic AI tool over streamable HTTP.
io.github.psyb0t/claudebox — Self-hosted MCP server for Claude Code
This self-hosted Model Context Protocol (MCP) server exposes Claude Code as an agentic AI tool over streamable HTTP. It is packaged as a Docker container image intended for development-agent and code-agent workflows, with support for programmatic web-api access.
🛠️ Key Features
Self-hosted MCP server (mcp, mcp-server)
Claude Code exposed as an agentic tool (claude, claude-code, ai-agent, code-agent)
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.
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:
bash
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.
bash
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
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.
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.