docker-pibox

pi-coding-agent inside an aicodebox container. One image, five ways in: interactive shell, one-shot API, 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
• Modes
  • API mode
  • Telegram mode
  • Cron mode
• Configuration
• Auth
• Development
• Tests
• License

Quick start

# one-shot prompt
docker run --rm \
  -e ANTHROPIC_AUTH_TOKEN=your-token \
  -e ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic \
  -e ANTHROPIC_MODEL=glm-4.6 \
  psyb0t/pibox:latest \
  -p "list the files in /workspace"

# API server
docker run -d --network host \
  -e PIBOX_API_MODE=1 \
  -e PIBOX_API_MODE_TOKEN=your-secret \
  -e PIBOX_AVAILABLE_MODELS=glm-4.6,glm-4.5-air \
  -e ANTHROPIC_AUTH_TOKEN=your-token \
  -e ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic \
  -e ANTHROPIC_MODEL=glm-4.6 \
  -v "$PWD/workspace:/workspace" \
  psyb0t/pibox:latest

Modes

Foreground modes (API / Telegram / Cron) are mutually exclusive — except PIBOX_TELEGRAM_MODE=1 + PIBOX_CRON_MODE=1, which run together (cron in-thread inside telegram). API wins if set alongside anything else.

MCP mode (PIBOX_MCP_MODE=1) is independent — it coexists with whatever foreground mode is running. In API mode it's mounted at /mcp on the API port; in other modes it runs as a sidecar uvicorn on its own port.

API mode

PIBOX_API_MODE=1. FastAPI server on :8080 (override with PIBOX_API_MODE_PORT).

Required: PIBOX_AVAILABLE_MODELS=<csv> (e.g. glm-4.6,claude-sonnet-4-6). API mode refuses to boot without it — /openai/v1/models needs a real list and there's no sensible default (pi can drive any provider's models). Pick the ones your configured ANTHROPIC_BASE_URL / provider actually serves.

All /files/* paths are resolved against the workspace root with traversal checking — .. segments that escape the root return 400. Same Authorization: Bearer ... token gates them as the rest of the API.

# upload a file
curl -sS -X PUT \
  -H "Authorization: Bearer your-secret" \
  --data-binary @local.txt \
  http://localhost:8080/files/notes/hello.txt

# download it back
curl -sS -H "Authorization: Bearer your-secret" \
  http://localhost:8080/files/notes/hello.txt

# list the dir
curl -sS -H "Authorization: Bearer your-secret" \
  http://localhost:8080/files/notes | jq

# delete it
curl -sS -X DELETE -H "Authorization: Bearer your-secret" \
  http://localhost:8080/files/notes/hello.txt

POST /run body: prompt (required), workspace, model, systemPrompt, appendSystemPrompt, jsonSchema, noContinue, resume, timeoutSeconds, thinking, noTools, toolsAllowlist, includeRaw, async, fireAndForget. With jsonSchema set the response includes text, json, events, sessionId, usage, attempts; without it the response is {runId, workspace, exitCode, text}.

curl -s http://localhost:8080/run \
  -H "Authorization: Bearer your-secret" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "say HELLO", "workspace": "/workspace"}'

Telegram mode

PIBOX_TELEGRAM_MODE=1 + PIBOX_TELEGRAM_MODE_TOKEN=<token>.

• Text in → pi runs → Markdown→HTML rendered response back.
• File uploads land in the chat's workspace. [SEND_FILE: path] in pi's output delivers workspace files as Telegram attachments.
• Per-chat overrides: /model, /effort (maps to pi's --thinking levels), /system_prompt, /append_system_prompt. Persisted across restarts.
• /cancel kills the in-flight run. /reload re-reads config. /config dumps merged settings. /fetch <path> downloads a file.
• Replies to cron messages inject the job's instruction + result so pi has full context for follow-ups.

Config at $HOME/.aicodebox/telegram.yml (override via PIBOX_TELEGRAM_MODE_CONFIG):

allowed_chats: [-100123, 42]
default:
  model: glm-4.6
  workspace: shared
chats:
  -100123:
    workspace: alpha
    allowed_users: [10, 20]

Cron mode

PIBOX_CRON_MODE=1 + PIBOX_CRON_MODE_FILE=/path/to/cron.yaml. 6-field schedules via croniter. Each job fires pi with the given instruction.

jobs:
  - name: morning-standup
    schedule: "0 0 9 * * 1-5"
    instruction: |
      Summarize what changed in /workspace since yesterday.
      Be brief. One paragraph max.
    workspace: myproject
    telegram_chat_id: -100123
    model: glm-4.6
    thinking: low

Each run gets a history dir at $HOME/.aicodebox/cron/history/<workspace>/<timestamp>-<job>/ with meta.json, stdout.log, stderr.log, result.txt. If telegram is configured, telegram.json lands there too and the next run's prompt gets a "prior run" hint so pi can reference its own history without you wiring it up.

MCP mode

PIBOX_MCP_MODE=1. Exposes the MCP (Model Context Protocol) surface — run_prompt, list_files, read_file, write_file, delete_file as tools. Coexists with any foreground mode:

Auth: PIBOX_MCP_MODE_TOKEN=<token> — bearer in the Authorization: Bearer … header, or ?apiToken=… for clients that can't set headers. Empty = no auth. No fallback to API_MODE_TOKEN — MCP has its own bearer.

Configuration

Naming convention: PIBOX_<MODE>_MODE=1 is the on/off flag, PIBOX_<MODE>_MODE_<KNOB>=... is its config. Non-mode-scoped vars (workspace, container name, available models) are bare.

The image is built on top of aicodebox, so the equivalent AICODEBOX_* names also work — the entrypoint translates PIBOX_X to AICODEBOX_X when only the pibox-prefixed one is set. If you set both, AICODEBOX_* wins.

Mode flags

API mode config

Telegram mode config

Cron mode config

MCP mode config

Workspace & runtime

Auth

pi speaks the Anthropic wire protocol. Point it at any Anthropic-compatible endpoint:

Z.AI's GLM models are fast and cheap for most tasks — ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic + ANTHROPIC_MODEL=glm-4.6 is the recommended default.

pi's thinking levels (--thinking): off, minimal, low, medium, high, xhigh. Exposed as the /effort command in telegram mode and as thinking in API requests.

Development

make help   # list targets
make build  # pull the published aicodebox base, build + tag psyb0t/pibox:v<VERSION> and :latest
make test   # run the full e2e suite (needs .env.test)
make clean  # remove built images

VERSION is read from pibox/pyproject.toml. make build pulls the published psyb0t/aicodebox base pinned in the Dockerfile; set SKIP_BASE_PULL=1 to use a locally-built base instead (e.g. from a sibling ../docker-aicodebox checkout), or override with make build BASE_IMAGE=....

Tests

End-to-end tests build the image and run it against a real LLM endpoint. Telegram tests use psyb0t/telethon-plus as a real MTProto userbot.

cp .env.test.example .env.test
$EDITOR .env.test   # fill in ANTHROPIC_* and optionally Telegram creds
make test

Telegram tests auto-skip if AICODEBOX_TELEGRAM_MODE_TOKEN is empty. Everything else only needs ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL.

License

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