Pibox MCP server

docker-pibox

pi-coding-agent inside an aicodebox container. One image, several ways in: interactive shell, one-shot prompt, HTTP API (with an OpenAI-compatible endpoint), MCP server, Telegram bot, and a cron scheduler that fires pi on whatever schedule you want.

You talk to pibox. pibox talks to pi. pi talks to whatever LLM you point it at. Nobody cares about the middle.

Table of Contents

• Quick start
• Using the pibox wrapper
• Image variants
• Modes
• API mode
• Telegram mode
• Cron mode
• MCP mode
• Configuration
• LLM providers
• Auth
• Agent integrations

Quick start

Install the host wrapper.

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

# Install the full image as the wrapper default.
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-pibox/main/install.sh | PIBOX_FULL=1 bash

The installer creates the Pi, pibox state, and SSH directories, pulls the selected image, and installs pibox on PATH. The minimal image is the default. PIBOX_FULL=1 on the bash side of the pipe selects the full image and bakes that choice into the installed wrapper.

Install pibox, codexbox, and claudebox in the same command directory, normally /usr/local/bin, when you want one box to launch another. Each wrapper finds the sibling wrapper files there and mounts them read-only into its container. A sibling then runs through the host Docker daemon and mounts its own host data directory.

Using the pibox wrapper

Run pibox from the directory you want Pi to work in. The wrapper mounts that directory at the same absolute path inside the container, persists ~/.pi, ~/.aicodebox, and ~/.ssh/pibox, forwards PIBOX_* configuration, and passes Pi arguments through unchanged.

# interactive Pi in the current directory
pibox

# one prompt, then exit
pibox -p "list the files in this workspace"

# use an Anthropic-compatible provider for this run
ANTHROPIC_AUTH_TOKEN=your-token \
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic \
ANTHROPIC_MODEL=glm-4.6 \
pibox -p "explain this project"

# inspect Pi's native command surface
pibox --help

# temporarily use the full image instead of the installed default
PIBOX_FULL=1 pibox -p "run the test suite"

The wrapper is also the normal way to start a long-running mode. PIBOX_DETACH=1 makes the named container run in the background.

PIBOX_DETACH=1 \
PIBOX_API_MODE=1 \
PIBOX_API_MODE_TOKEN=your-secret \
PIBOX_AVAILABLE_MODELS=glm-4.6,glm-4.5-air \
ANTHROPIC_AUTH_TOKEN=your-token \
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic \
ANTHROPIC_MODEL=glm-4.6 \
pibox

Use raw docker run only when you intentionally do not want the host wrapper. The wrapper is the normal interactive and service entry point.

Agent use and nested launches

Shortened. The full README is on GitHub.