aicodebox MCP server

aicodebox

The agent-agnostic foundation for putting any terminal-shaped AI coding agent on the network. Pick your poison (claude-code, pi, opencode, hermes, whatever vibes), bolt on a short adapter class, and out the other end you get an HTTP API, an OpenAI-compatible chat completions endpoint, an MCP server, a Telegram bot, and a cron scheduler that fires the agent on whatever schedule you can dream up. One container. Same interfaces. Swap the brain.

You don't fork this. You FROM it.

FROM psyb0t/aicodebox

RUN npm install -g @earendil-works/pi-coding-agent@0.74.0
COPY mypkg /opt/mypkg
RUN pip3 install --break-system-packages /opt/mypkg

ENV AICODEBOX_ADAPTER=mypkg.adapter:MyAdapter \
    AICODEBOX_AGENT_BINARY=pi

That's it. The base owns the modes. Your adapter translates "run this prompt" into whatever your agent's CLI expects. New agent lands in an afternoon.

aicodebox is a base image, not a host launcher. For local agent work, use a child wrapper such as claudebox, codexbox or pibox. Those wrappers mount the requested workspace and the matching agent state. A child agent calls a sibling wrapper directly when it is installed beside its own wrapper. It must not rebuild that wrapper's Docker command or mount another agent's state itself.

Table of Contents

• Documentation
• What's in the box
• Quick start
• Modes
• Development
• Sponsor
• License

Documentation

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

Section	What's there
Child images	Build an image for your agent, minimal or full parent, passthrough.
Adapter contract	AgentAdapter, RunRequest, RunResult, stream and native events.
Modes	How the flags pick a mode, where MCP goes, ports.
HTTP API	/run, schema retries, events, async runs, files, /status, /healthz.
OpenAI-compatible endpoint	Streaming, response_format, tool calling, images, x-aicodebox-* headers.
MCP server	Tools, tokens, host and origin allowlists.
Telegram bot	telegram.yml, commands, files, overrides.
Cron scheduler	Jobs file, schedules, run history, notifications.
Configuration	Every environment variable and its default.
Container startup	UID remapping, Docker socket, Git identity, init scripts, user bin/.
Full image	The latest-full toolchain and its advisories.
Security	What the agent can reach and what to set before exposing it.
Troubleshooting	Exact error messages and fixes.
Development	Layout, Make targets, tests, CI, releases.

What's in the box

Layer	The goods
OS	Ubuntu 24.04. aicode user (UID 1000), passwordless sudo, docker group.
Runtimes	Node.js 24.21.0 (for agents that ship as npm), Python 3.14.8, uv, Docker CE with buildx and compose (in case your agent needs to spawn containers).
Package	aicodebox: the adapter contract plus four mode dispatchers (API, Telegram, cron, MCP). Pure Python, nothing runs until you boot a mode.
Auth	AICODEBOX_API_MODE_TOKEN guards the API, AICODEBOX_MCP_MODE_TOKEN guards MCP. One bearer each, no fallback between them. Empty means no auth. Telegram has its own allowlist.
State	Telegram overrides, cron history, your bin/ and init.d/ live under $HOME/.aicodebox/. Bind-mount it if you want it to outlive the container.

psyb0t/aicodebox:latest is deliberately small. psyb0t/aicodebox:latest-full adds a shared development toolchain for agent images that need it: Go and its tools, pinned Node and Python developer tools, editors, database clients, gh, Terraform, kubectl and Helm. The full image keeps some optional Node tools with known dependency advisories; the advisory list says which and why.

Quick start

Build your child image as above, then boot it in API mode:

docker run --rm -p 127.0.0.1:8080:8080 \
  -e AICODEBOX_API_MODE=1 \
  -e AICODEBOX_API_MODE_TOKEN="$(openssl rand -hex 16)" \
  -e AICODEBOX_AVAILABLE_MODELS=model-a,model-b \
  -v "$PWD/workspace:/workspace" \
  your/child-image:latest

API mode refuses to boot without AICODEBOX_AVAILABLE_MODELS (or available_models on the adapter), because /openai/v1/models needs real model IDs. The adapter itself is one class with a build_argv method; the adapter contract has a complete example.

Modes

Set a flag to 1 and the entrypoint starts that mode. No flag, no mode: the container runs your agent's CLI with its arguments.

Flag	Mode
AICODEBOX_API_MODE	FastAPI on :8080: /run, files, and /openai/v1/chat/completions.
AICODEBOX_TELEGRAM_MODE	A Telegram bot that runs the agent per chat, with uploads, attachments and per-chat overrides.
AICODEBOX_CRON_MODE	Jobs from a YAML file on five or six field cron schedules, with run history and optional Telegram notifications.
AICODEBOX_MCP_MODE	An MCP server, at /mcp/ inside API mode or on :8081 beside anything else.

API, Telegram and cron are foreground modes and don't stack: API wins over the rest, and Telegram plus cron share one process. MCP coexists with any of them. Details on the modes page.

Development

make help        # list targets
make build       # build psyb0t/aicodebox:latest
make build-full  # build latest-full on top of the local minimal image
make lint        # flake8 + pyright, in a pinned uv container
make test-ci     # unit tests, in the same container (what CI runs)
make docs        # build the documentation site into .testing/docs-site

Lint and the CI tests need only Docker. The rest of the targets, the integration tests and the CI pipeline are on the development page.

Sponsor

License

WTFPL, see LICENSE. Do what the fuck you want.