HUB
Sign inSign up

psyb0t/pibox

By psyb0t

•Updated 3 days ago

pi-coding-agent in a Docker image built on aicodebox, with an HTTP API, an OpenAI-compatible endp...

Image
0

10K+

psyb0t/pibox repository overview

Source⁠ | Project page⁠

⁠pibox

CI version license Docker Pulls

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

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.

⁠Image variants

  • 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.

⁠Modes

FlagWhat you get
PIBOX_API_MODE=1FastAPI server on :8080: agent runs, workspace files, and an OpenAI-compatible chat/completions with streaming and client-executed tool calls
PIBOX_TELEGRAM_MODE=1Talk to pi from Telegram, with per-chat workspaces, allowlists and settings
PIBOX_CRON_MODE=1YAML-scheduled pi runs with per-run history
PIBOX_MCP_MODE=1run_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.

⁠Documentation

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

SectionWhat 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

⁠Agent integrations

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.

⁠Development

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.

⁠Sponsor

Buy Me a Coffee

⁠License

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

Tag summary

Content type

Image

Digest

sha256:a8ebb0253…

Size

517.4 MB

Last updated

3 days ago

docker pull psyb0t/pibox