Sign inSign up

psyb0t/aicodebox

By psyb0t

•Updated 8 days ago

Base Docker image that wraps any terminal AI coding agent in an HTTP API, an OpenAI-compatible en...

Image
0

10K+

psyb0t/aicodebox repository overview

Source⁠ | Project page⁠

⁠aicodebox

CI version license Docker Pulls

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/[email protected]
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

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

SectionWhat'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

LayerThe goods
OSUbuntu 24.04. aicode user (UID 1000), passwordless sudo, docker group.
RuntimesNode.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).
Packageaicodebox: the adapter contract plus four mode dispatchers (API, Telegram, cron, MCP). Pure Python, nothing runs until you boot a mode.
AuthAICODEBOX_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.
StateTelegram 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.

FlagMode
AICODEBOX_API_MODEFastAPI on :8080: /run, files, and /openai/v1/chat/completions.
AICODEBOX_TELEGRAM_MODEA Telegram bot that runs the agent per chat, with uploads, attachments and per-chat overrides.
AICODEBOX_CRON_MODEJobs from a YAML file on five or six field cron schedules, with run history and optional Telegram notifications.
AICODEBOX_MCP_MODEAn 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

Buy Me a Coffee

⁠License

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

Tag summary

Content type

Image

Digest

sha256:e916b9919…

Size

452.3 MB

Last updated

8 days ago

docker pull psyb0t/aicodebox