🐳 dockerized-pi

“There are many coding agents dockerizations, but this one is mine.”

Dockerfiles and scripts to containerize the pi coding agent. Includes various helpers and opinionated customizations.

---

🚀 Setup

1. 📥 Clone the Repository:

   git clone https://github.com/stefan2904/dockerized-pi.git
   cd dockerized-pi
       

2. ⚙️ Configure Environment (Optional): Copy .env.template to .env and fill in your configuration.

   cp .env.template .env
       

   Note: This is optional. You can also log in to model providers directly within the agent using the /login command.

3. 🏗️ Build the Image: Run the build script to create/update the pi-coding-agent Docker image.

   ./build.sh [version]
       

   Note: If no version is specified, it defaults to latest.

4. 🐚 (Optional) Install Zsh Aliases: Install the pi, pic, and picommit aliases for easy access from any directory.

   ./pi.sh --install
       

   Note: This adds aliases to /.zshrc.local. Ensure this file is sourced in your /.zshrc.

📋 Environment Variables

The following environment variables can be configured in .env (see .env.template):

• BOT_GH_TOKEN: GitHub personal access token (for gh CLI authentication).
• BOT_SENTRY_TOKEN: Sentry auth token (for sentry-cli authentication). Get one at Sentry Personal Tokens.
• BOT_GIT_NAME: Git user name (for changes done in the container/by pi).
• BOT_GIT_EMAIL: Git user email (for changes done in the container/by pi).
• PI_SUDO_PASSWORD: Password for sudo inside the container. If not set, a random password is generated and displayed at startup.
• ANTHROPIC_API_KEY: Anthropic API key.
• OPENAI_API_KEY: OpenAI API key.
• GEMINI_API_KEY: Google Gemini API key.
• MISTRAL_API_KEY: Mistral API key.
• HF_TOKEN: Hugging Face API token.
• OPENROUTER_API_KEY: OpenRouter API key.
• PI_CACHE_RETENTION: Cache retention period (e.g., 7d).

📜 Dockerize Scripts (use pi alias or run from repo root)

• ./pi.sh --install: Install pi, pic, and picommit aliases.
• ./pi.sh --update: Update the pi agent to the latest version and rebuild the image.
• ./pi.sh --sessions: List past sessions stored in pi/agent/sessions.
• ./pi.sh --ro or --readonly: Mount the workspace in read-only mode.
• ./pi.sh <args>: Run pi with the given arguments inside the container (see ./pi.sh --help).

⌨️ Pi Aliases

Once installed, use these from any project directory:

• pi: Run the agent in the current directory.
• pic: Continue the last session (pi --continue).
• picommit: Automatically stage and commit changes using the /commit template.

---

✨ Features

🗂️ Project Root Discovery

The pi.sh script automatically detects your project root by searching upwards for .git, .project, or .projectile markers. This ensures that session history and file contexts are consistently mapped even if you run pi from a subdirectory.

🐚 Shell Environment

The container uses zsh with the excellent grml configuration, providing a powerful and interactive shell environment for the agent (and you).

🔐 Sudo Support

The pi user can gain root privileges via sudo. The password is configurable through the PI_SUDO_PASSWORD environment variable (set it in .env). If not set, a random 16-character hex password is generated at container startup and printed to the console:

==========================================
 sudo password for pi: a1b2c3d4e5f67890
==========================================

This allows the agent (or you, when shelling in) to install packages or perform other root operations as needed.

📝 Prompt Templates

• /commit: Automatically stage and commit changes with conventional commit messages.

🧩 Extensions

• /files-changed: Show a list of files read, written, or edited in the current session.
• /quota: Show usage quotas for all logged-in providers.
• /quota-antigravity: Show Antigravity usage limits and quotas.
• /quota-copilot: Show GitHub Copilot usage statistics and quotas.

🧠 Skills

• git-autopep8: Automatically formats changed lines in Python files using git and autopep8.

🛠️ Tools (Custom)

• get_files_changed: List files touched in the session (available to the model).
• get_antigravity_quota: Fetch Antigravity usage limits (available to the model).
• get_copilot_quota: Fetch GitHub Copilot usage limits (available to the model).
• get_gemini_cli_quota: Fetch Google Gemini CLI tier info and model quota availability.
• get_openai_codex_quota: Probe OpenAI Codex quota headers and account plan details.