pi-coding-agent in a Docker image built on aicodebox, with an HTTP API, an OpenAI-compatible endp...
10K+
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.
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. Run pibox from the directory you want Pi to work in. The wrapper mounts that directory at the same path inside the container, keeps Pi's state between runs, forwards every PIBOX_* variable, and passes Pi arguments through unchanged.
# point Pi at an upstream model
export PIBOX_PROVIDER_BASE_URL=https://api.z.ai/api/anthropic
export PIBOX_PROVIDER_API=anthropic-messages
export PIBOX_PROVIDER_API_KEY=your-z-ai-api-key
export PIBOX_PROVIDER_MODEL=your-model-id
# interactive Pi in the current directory
pibox
# one prompt, then exit
pibox -p "list the files in this workspace"
# the full image for this run only
PIBOX_FULL=1 pibox -p "run the test suite"
PIBOX_DETACH=1 starts a long-running mode in the background:
PIBOX_DETACH=1 \
PIBOX_API_MODE=1 \
PIBOX_API_MODE_TOKEN=your-secret \
PIBOX_AVAILABLE_MODELS=your-model-id \
pibox
Install pibox, codexbox, and claudebox in the same command directory when you want one box to launch another. The install guide covers nested launches, plain docker run, upgrades and removal.
psyb0t/pibox:latest is the minimal image.psyb0t/pibox:latest-full starts from the shared aicodebox:v0.18.4-full base, then adds Pi and pibox. It carries the shared development toolchain without rebuilding it in this repository.| Flag | What you get |
|---|---|
PIBOX_API_MODE=1 | FastAPI server on :8080: agent runs, workspace files, and an OpenAI-compatible chat/completions with streaming and client-executed tool calls |
PIBOX_TELEGRAM_MODE=1 | Talk to pi from Telegram, with per-chat workspaces, allowlists and settings |
PIBOX_CRON_MODE=1 | YAML-scheduled pi runs with per-run history |
PIBOX_MCP_MODE=1 | run_prompt and workspace file tools over MCP, next to any other mode |
API wins over the other foreground modes. Telegram and cron run together. MCP coexists with all of them. The modes page has the rules and a page per mode.
The full documentation lives at psyb0t.github.io/docker-pibox.
| Section | What it covers |
|---|---|
| Install and the wrapper | Installer options, wrapper settings, image variants, nested launches |
| Configuration | Every environment variable, aliasing, Git identity, startup hooks |
| LLM providers | OpenAI-compatible, Anthropic Messages and Google endpoints |
| Modes | API, Telegram, cron and MCP |
| GitHub Action | Pi in a workflow on read-only context |
| Agent integrations | Claude Code, Codex and OpenClaw |
| Security | Tokens, exposure and where secrets are stored |
| Troubleshooting | Startup refusals and their fixes |
| Architecture | Wrapper, entrypoint, adapter and the Pi CLI |
| Development | Builds, tests, CI and releases |
The skill works in any agent that reads .agents/skills/ (such as peen), and installs natively in Claude Code, Codex and OpenClaw:
claude plugin marketplace add psyb0t/agents
claude plugin install pibox@psyb0t
codex plugin marketplace add psyb0t/agents
codex plugin add pibox@psyb0t
openclaw skills install @psyb0t/pibox
The agent integrations page covers tokens and the stdio MCP bridge plugin.
make help # list targets
make build-all # build both variants
make lint # shellcheck, ruff and pyright, in containers
make test-ci # offline tests, what CI runs
make test # the e2e suite (needs .env.test)
make docs # build the documentation site
The development page explains the tests, CI and releases.
WTFPL, see LICENSE. Do what the fuck you want.
Content type
Image
Digest
sha256:a8ebb0253…
Size
517.4 MB
Last updated
3 days ago
docker pull psyb0t/pibox