Pibox

docker-pibox

aicodebox コンテナ内で動作する pi-coding-agent です。1つのイメージから、対話型シェル、単発プロンプト、HTTP API（OpenAI 互換エンドポイント付き）、MCP サーバー、Telegram ボット、お好きなスケジュールで pi を起動する cron スケジューラーなど、さまざまな方法で利用できます。

pibox に話しかけると、pibox は pi に話しかけます。pi は指定された LLM に話しかけます。途中のことは誰も気にしません。

目次

• クイックスタート
• pibox ラッパーの使用
• イメージのバリエーション
• モード
  • API モード
  • Telegram モード
  • Cron モード
  • MCP モード
• 設定
• LLM プロバイダー
• 認証
• エージェント連携
• GitHub Action
• 開発
• テスト
• ライセンス

クイックスタート

ホストラッパーをインストールします。

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

インストーラーは Pi、pibox の状態データ、SSH の各ディレクトリを作成し、選択したイメージを取得して、pibox を PATH にインストールします。デフォルトでは最小イメージが選択されます。パイプの bash 側で PIBOX_FULL=1 を指定すると、フルイメージが選択され、その設定がインストールされたラッパーに適用されます。

1つのボックスから別のボックスを起動する場合は、pibox、codexbox、claudebox を同じコマンドディレクトリ（通常は /usr/local/bin）にインストールしてください。各ラッパーはそこにある兄弟ラッパーファイルを見つけ、読み取り専用でコンテナにマウントします。兄弟ラッパーはホストの Docker デーモンを介して実行され、独自のホストデータディレクトリをマウントします。

pibox ラッパーの使用

Pi に作業させたいディレクトリから pibox を実行します。ラッパーはそのディレクトリをコンテナ内の同じ絶対パスにマウントし、~/.pi、~/.aicodebox、~/.ssh/pibox を永続化して、PIBOX_* 設定を転送し、Pi の引数を変更せずに渡します。

# 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"

長時間実行するモードを起動する場合も、通常はラッパーを使います。PIBOX_DETACH=1 を指定すると、名前付きコンテナがバックグラウンドで実行されます。

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

ホストラッパーを意図的に使わない場合に限り、生の docker run を使用してください。対話型の利用やサービスの起動には、通常ラッパーを使用します。

エージェントでの利用とネストした起動

インストール済みのラッパーが、ユーザーとエージェント向けの通常のインターフェースです。エージェントは新しい docker run コマンドを組み立てるのではなく、指定されたワークスペースから pibox を実行してください。ラッパーはワークスペースのパス、Pi の状態、aicodebox の状態、SSH の状態、イメージの選択、コンテナのライフサイクルを維持します。

pibox -p "inspect this workspace and report the failing tests"
PIBOX_FULL=1 pibox -p "run the full test suite"
pibox -p "list the files" --thinking high

あるボックスから別のボックスを使う場合は、pibox、codexbox、claudebox を同じコマンドディレクトリにインストールしてください。実行中のボックスから、兄弟のコマンドを直接呼び出せます。親ラッパーはホスト側の起動コンテキストを渡し、兄弟ラッパーファイルのみをマウントします。AICODEBOX_HOST_* を設定したり、ラッパーをコピーしたり、別のボックスの状態ディレクトリを手動でマウントしたりしないでください。

イメージのバリエーション

• psyb0t/pibox:latest は最小イメージです。
• psyb0t/pibox:latest-full は共有の aicodebox:latest-full ベースから起動し、その後 Pi と pibox を追加します。このリポジトリで再ビルドすることなく、共有の開発ツールチェーンを利用できます。

モード

フォアグラウンドモード（API／Telegram／Cron）は相互排他的です。ただし、PIBOX_TELEGRAM_MODE=1 と PIBOX_CRON_MODE=1 を同時に設定した場合は、Telegram 内で Cron が実行され、両方が動作します。ほかのモードと同時に設定されている場合は、API が優先されます。

MCP モード（PIBOX_MCP_MODE=1）は独立しており、実行中のフォアグラウンドモードと共存します。API モードでは API ポートの /mcp/ にマウントされます（末尾のスラッシュがない /mcp も同じハンドラーに到達します）。それ以外のモードでは、専用ポートのルートでサービスを提供するサイドカーの uvicorn として実行されます。

各モードのページでは、詳細なセットアップ方法、環境変数、例を確認できます。

API モード →

:8080 で稼働する長時間実行の FastAPI サーバーです。エージェントの実行（同期、実行 ID のポーリングによる非同期、キャンセル可能）、ワークスペース内のファイルのアップロード／ダウンロード／一覧表示／削除（パストラバーサルチェック付き）、ストリーミングとクライアント実行のツール呼び出しに対応した OpenAI 互換の chat/completions エンドポイントを提供します。

environment:
  - PIBOX_API_MODE=1
  - PIBOX_API_MODE_TOKEN=your-secret
  - PIBOX_AVAILABLE_MODELS=glm-4.6,glm-4.5-air

Telegram モード →

Telegram から pi と会話できます。チャットごとに分離されたワークスペース、許可するチャットとユーザーのチャット単位の制御、ファイルの取り込み、ファイルを受け取るための [SEND_FILE: path]、再起動後も保持されるチャットごとの /model、/effort、/system_prompt、/append_system_prompt の上書きに対応しています。

environment:
  - PIBOX_TELEGRAM_MODE=1
  - PIBOX_TELEGRAM_MODE_TOKEN=123456:ABC

Cron モード →

6 フィールドの croniter スケジュールで定義する、YAML ベースのスケジュール済みジョブです。実行ごとの履歴ディレクトリに meta.json、stdout.log、stderr.log、result.txt が保存されます。また、ジョブが自身の履歴を参照できるよう、「前回の実行」に関するヒントも提供します。

environment:
  - PIBOX_CRON_MODE=1
  - PIBOX_CRON_MODE_FILE=/home/aicode/.aicodebox/cron.yaml

MCP モード →

ストリーミング可能な HTTP 経由で run_prompt と、ワークスペース内に限定されたファイルツールを公開します。これにより、ほかのエージェントから pi をツールとして利用できます。任意のフォアグラウンドモードと共存し、API モードでは API ポートの /mcp/ にマウントされ、それ以外のモードでは専用ポートのサイドカーとして稼働します。

environment:
  - PIBOX_MCP_MODE=1
  - PIBOX_MCP_MODE_TOKEN=your-secret

設定

ホストで PIBOX_GIT_NAME と PIBOX_GIT_EMAIL を設定すると、起動時のフックより前にランタイムユーザーのグローバル Git ID を設定できます。コンテナを直接デプロイする場合も、同じ名前を使用できます。コンテナ内の値が空でない AICODEBOX_GIT_NAME と AICODEBOX_GIT_EMAIL は、これらより優先されます。ラッパー経由の場合は、共有する値を AICODEBOX_ENV_AICODEBOX_GIT_NAME と AICODEBOX_ENV_AICODEBOX_GIT_EMAIL として指定してください。空の設定では既存の Git 設定が保持されます。複数行の値は拒否されます。

make version V=X.Y.Z は、パッケージのメタデータ、ロックファイル、Codex プラグインのマニフェスト、インストーラーのラッパーリリース参照を同期します。コミットやタグ付けは行いません。リモートインストールでは、PIBOX_INSTALL_REF で上書きしない限り、対応するリリースのラッパーがダウンロードされます。イメージを更新しても、インストール済みのラッパーは更新されません。

命名規則：PIBOX_<MODE>_MODE=1 はオン／オフのフラグ、PIBOX_<MODE>_MODE_<KNOB>=... はその設定です。ワークスペース、コンテナ名、利用可能なモデルなど、モードに限定されない変数は接頭辞なしです。

このイメージは aicodebox をベースにしているため、同等の AICODEBOX_* 名も使用できます。pibox 接頭辞付きの変数のみが設定されている場合、エントリーポイントが PIBOX_X を AICODEBOX_X に変換します。両方を設定した場合は、AICODEBOX_* が優先されます。

LLM プロバイダーで、アップストリームのエンドポイント URL、プロトコル、API キーまたはトークン、モデルを設定してください。PIBOX_PROVIDER_* は、Pi がドキュメントで公開している OpenAI、Anthropic、Google のカスタム HTTP API に対応しています。以下の ANTHROPIC_* 変数は、既存の Anthropic 互換デプロイメントとの互換性を維持するための設定です。

モードフラグ

変数	デフォルト	説明
PIBOX_API_MODE	0	HTTP API サーバーを起動します（フォアグラウンド）
PIBOX_TELEGRAM_MODE	0	Telegram ボットを起動します（フォアグラウンド）
PIBOX_CRON_MODE	0	cron スケジューラーを起動します（フォアグラウンド。Telegram も有効な場合はスレッド内で実行）
PIBOX_MCP_MODE	0	MCP を公開します。API モードでは /mcp/ にマウントし、それ以外ではサイドカーとして実行します

各モード固有の設定（ポート、トークン、設定パス、履歴ディレクトリ）は、各モードのページに記載されています：api.md、telegram.md、cron.md、mcp.md。

ワークスペースとランタイム

変数	デフォルト	説明
PIBOX_WORKSPACE	/workspace	コンテナ内のルートワークスペースディレクトリ
PIBOX_CONTAINER_NAME	aicodebox	コンテナごとの状態ファイル（認証情報など）のスコープに使用します
PIBOX_AVAILABLE_MODELS	—	API モードでは必須です。 /openai/v1/models から返され、Telegram の /model ピッカーに表示される CSV 形式のリストです。pibox はリストされたすべてのモデルを、PIBOX_PROVIDER_API で指定されたアップストリームプロバイダーに登録します。これが設定されていない場合、API モードは起動を拒否します。Telegram の /model ピッカーは「この環境変数を設定してください」という返信に切り替わります。
PIBOX_AVAILABLE_EFFORTS	adapter list	Telegram の /effort ピッカーに表示する effort／--thinking リストを上書きします（カンマ区切り）
PIBOX_DATA_DIR	~/.pi	ホスト側の Pi 設定、認証情報、拡張機能、セッションのディレクトリ
PIBOX_STATE_DIR	~/.aicodebox	ホスト側の pibox モード設定および履歴のディレクトリ
PIBOX_SSH_DIR	~/.ssh/pibox	コンテナにマウントされるホスト側の SSH ディレクトリ
PIBOX_IMAGE	installed image	インストール済みラッパーが選択したイメージを上書きします
PIBOX_FULL	installed choice	0 は最小構成、1 は完全構成を選択します
PIBOX_DETACH	0	1 にすると、破棄されるフォアグラウンドコンテナではなく、名前付きのバックグラウンドコンテナを起動します
PIBOX_ENV_*	none	pibox 環境変数をコンテナに引き渡します
PIBOX_MOUNT_*	none	同一パスまたは host:container のバインドマウントを追加します
AICODEBOX_ENV_*	none	共有環境変数を、プレフィックスを取り除いて起動したコンテナに引き渡します
AICODEBOX_MOUNT_*	none	起動したコンテナに、共有の同一パスまたは host:container のバインドマウントを追加します

自動化では、PIBOX_INSTALL_DIR と PIBOX_BIN_NAME を使用して、別のコマンドディレクトリにラッパーをインストールできます。インストールされたラッパーは、バージョン管理された AICODEBOX_HOST_* のネスト起動コンテキストを受け入れます。これらのホストパスを Docker のバインドソースとして使用し、隣接するラッパーを利用可能にして、共有の AICODEBOX_ENV_* と AICODEBOX_MOUNT_* の値を子コンテナに適用します。

デフォルトでは ~/.aicodebox の PIBOX_STATE_DIR の下にあるもの：

• bin/ に配置した実行ファイルは、すべてのモードの pi、初期化スクリプト、docker exec シェルで、ほかのすべてのパスより優先して PATH に追加されます。
• init.d/*.sh に配置したスクリプトは、各コンテナで一度、イメージ独自の初期化スクリプトの後に、パスワードなしの sudo を使う aicode として実行されます。スクリプトが失敗した場合はログに記録され、残りのスクリプトは引き続き実行されます。新しいコンテナでは再度実行されるため、繰り返し実行しても安全な内容にしてください。

認証

Anthropic 互換エンドポイントでは、以下の互換性変数を使用します。LiteLLM またはその他の OpenAI 互換エンドポイントでは、汎用プロバイダーの設定を使用してください。

Var	用途
ANTHROPIC_AUTH_TOKEN	ベアラートークン（Z.AI、Anthropic の直接接続など）
ANTHROPIC_API_KEY	同じものです。pi は両方を読み取ります
ANTHROPIC_BASE_URL	エンドポイントの上書き（デフォルト：https://api.anthropic.com）
ANTHROPIC_MODEL	呼び出し元がモデルを指定しない場合のデフォルトモデル

Z.AI の GLM モデルは、ほとんどのタスクで高速かつ低コストです。推奨されるデフォルトは ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic + ANTHROPIC_MODEL=glm-4.6 です。

pi の思考レベル（--thinking）：off、minimal、low、medium、high、xhigh。Telegram モードでは /effort コマンドとして、API リクエストでは thinking として利用できます。

エージェントとの連携

スキルは、.agents/skills/ を読み取るあらゆるエージェント（peenなど）で動作します。ローカル作業にはインストール済みのラッパーを使用し、すでに実行中のリモートサーバーに対してのみ MCP を使用するよう、エージェントに指示します。以下のクライアントにはネイティブにインストールできます。

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install pibox@psyb0t

Claude Code では pibox の URL と、認証が有効な場合は API トークンと MCP トークンを入力します。機密情報は OS のキーチェーンに保存されます。

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add pibox@psyb0t

マーケットプレイス経由でインストールすると、スキルは $pibox:pibox として呼び出されます。また、Codex は .agents/skills/ を含むあらゆるリポジトリでインストールなしにスキルを自動的に認識し、単に $pibox として呼び出します。

OpenClaw

スキルはリリースのたびに ClawHub に公開されます。

openclaw skills install @psyb0t/pibox

ローカル stdio で通信する MCP クライアントには、@psyb0t/pibox プラグインを使って、サービスの /mcp/ エンドポイントに接続できます。

openclaw plugins install clawhub:@psyb0t/pibox

次に PIBOX_URL を設定します（サーバーの起動時に MCP 認証が有効になっている場合は PIBOX_MCP_MODE_TOKEN も設定します）。

開発

読み取り専用のコンテキスト、リアルタイムのツールログ、収集された出力ファイルを利用できる、単発の GitHub ジョブについては、GitHub Actionを参照してください。

make help   # list targets
make build      # build the minimal image
make build-full # build the full image from aicodebox full
make build-all  # build both variants
make test   # run the full e2e suite (needs .env.test)
make test-action # test the GitHub Action contract without credentials
make clean  # remove built images

VERSION は pibox/pyproject.toml から読み取られます。make build は Dockerfile で固定された公開済みの psyb0t/aicodebox ベースイメージを取得します。ローカルでビルドしたベースイメージを使用する場合（たとえば、隣接する ../docker-aicodebox のチェックアウトからビルドしたもの）は SKIP_BASE_PULL=1 を設定するか、make build BASE_IMAGE=... で上書きしてください。

テスト

エンドツーエンドテストでは、イメージをビルドし、実際の LLM エンドポイントに対して実行します。Telegram テストでは、実際の MTProto ユーザーボットとして psyb0t/telethon-plus を使用します。

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

AICODEBOX_TELEGRAM_MODE_TOKEN が空の場合、Telegram テストは自動的にスキップされます。汎用プロバイダーのテストでは、両方の Z.AI Coding Plan エンドポイントを使用し、ZAI_CODING_AUTH_TOKEN が設定されていない場合は ANTHROPIC_AUTH_TOKEN を再利用します。

ライセンス

WTFPL — LICENSEを参照してください。好きなようにしてください。