DDEV add-on for Pi Coding Agent

This DDEV add-on provides a fully containerized, isolated environment for the Pi Coding Agent.

Architecture & security

• Full isolation: The agent runs in a dedicated sidecar container. The host machine’s ~/.pi directory is explicitly not mounted, so agent state is scoped strictly to the project and avoids cross-contamination with your host environment.
• Project access: The project root is mounted at /var/www/html with read/write permissions, allowing Pi to interact with your codebase.
• Network: The agent is isolated within the DDEV project network.
• Sensitive data: No host-level sensitive directories (e.g., ~/.ssh) are mounted.
• Offline by default: PI_OFFLINE=1 is set to block all Pi-initiated outbound network traffic that is not required for normal agent use — this includes background model-catalog refreshes, version checks, package-update probes, install telemetry, automatic tool downloads, and silent bug-report uploads. PI_SKIP_VERSION_CHECK=1 and PI_TELEMETRY=0 are set alongside it for defence-in-depth, independently preventing version checks and telemetry even if PI_OFFLINE is overridden. Set PI_OFFLINE=0 in your DDEV project configuration to restore internet access (e.g., to contact an external LLM provider API directly). See the Offline Mode section of the Architecture document for the full breakdown.
• Supply-chain: Pi is installed via npm ci --ignore-scripts using upstream’s official release package-lock.json, cryptographically pinning all direct and transitive dependencies at image build time. The agent version is controlled by the PI_VERSION build argument, which defaults to latest. Lock PI_VERSION to an exact version for reproducible, tamper-resistant builds — see Pi installation method & supply-chain hardening.

For a detailed diagram and breakdown of the system’s components and security boundaries, please see the Architecture document.

Requirements

• DDEV >= v1.25.2
• The trebormc/ddev-ai-ssh add-on (installed automatically as a dependency)
• Optional: python3 installed on the host machine (recommended for universal host clipboard integration across all terminals and arbitrary payload sizes; if omitted, clipboard sync falls back to terminal OSC 52)

Installation

ddev add-on get mxr576/ddev-pi
ddev restart && ddev start --profiles=pi

Updating

When updating this add-on (or changing files that affect the Pi Docker image), a standard ddev restart or ddev restart --no-cache will not rebuild the Pi container image because the Pi service is gated behind an optional Docker Compose profile (tracked in ddev/ddev#8817).

To update the add-on and properly rebuild and restart the Pi service:

ddev add-on get mxr576/ddev-pi
ddev debug rebuild -s pi
ddev restart && ddev start --profiles=pi

Note: ddev debug rebuild -s <service> (or its alias ddev utility rebuild -s <service>) for profile-gated services requires DDEV >= v1.25.3 (ddev/ddev#8463). Following up with ddev restart && ddev start --profiles=pi ensures all project containers and profile services restart cleanly together (see ddev/ddev#7904).

Usage

The Pi agent runs as a DDEV service under the pi profile. You must start DDEV with that profile active.

1. Start DDEV with the Pi profile enabled:

   ddev start --profiles=pi
   

2. Run Pi commands via the ddev pi wrapper:

   ddev pi [command]
   

Example:

ddev pi status

Note: The ddev pi command is a thin wrapper that runs ddev exec --service=pi pi "$@" inside the sidecar container. The container’s working directory is /var/www/html (your project root).

Configuration

Default configurations are initialized in your project’s .pi/ directory during installation (settings.json is copied from the add-on defaults). Modify settings.json there to configure providers and agent preferences.

Note: Re-running ddev add-on get will not overwrite an existing .pi/ directory. Defaults are only copied when .pi/ is empty.

Extensibility

This add-on provides several ways to customize the container environment, manage Pi extensions, and easily install AI skills:

• To extend or customize the container environment and DDEV hooks, see the Extensibility document.
• To easily install, manage, and configure AI skills, see the AI Skills document.

Experimental Host Clipboard Integration

This add-on features a cross-platform clipboard integration that bridges the containerized Pi Coding Agent to your host system’s clipboard using a hybrid strategy:

1. Shared Volume File Bridge (Default): When python3 is available on your host, using the /copy command writes payload content to a temporary pending file inside the shared workspace volume (.ddev/pi/.clipboard_pending). A lightweight, background Python daemon (pi/clipboard-helper.py) running on your host monitors this file, copies its contents to your host clipboard using native system utilities (pbcopy, clip.exe, powershell.exe, or wl-copy/xclip), and deletes the file.
   • Advantages: Universal terminal compatibility (including macOS Terminal.app and GNOME Terminal) and unlimited payload sizes (handles large code files and transcripts without truncation).
2. Terminal OSC 52 Fallback (Zero Host Dependencies): If python3 is not found on your host machine, ddev pi automatically falls back to Pi’s native remote session clipboard support (PI_CLIPBOARD_OSC52=1). Copied text is emitted directly through standard ANSI OSC 52 terminal escape sequences to your host terminal.
   • Requirements: Requires an OSC 52-compatible terminal emulator (such as Ghostty, iTerm2, Windows Terminal, Kitty, WezTerm, or Alacritty). Payloads are capped by Pi at ~75 KB (100,000 base64 characters).

You can explicitly force or disable OSC 52 sync at any time by setting PI_CLIPBOARD_OSC52=1 or PI_CLIPBOARD_OSC52=0.

OS Support & Feedback

Since clipboard tools vary depending on your host OS and available terminal utilities, this feature is currently marked as experimental. We welcome your feedback, bugs, and success stories for different operating systems!

• macOS: Fully supported and tested using native pbcopy.
• Windows (WSL/native): Fully supported and tested using clip.exe / PowerShell.
• Linux (X11/Wayland): Fully supported and tested using wl-copy, xclip, or xsel.

If clipboard sharing is not working on your host, check the log file at .ddev/pi/clipboard.log for debugging details.

Uninstalling

ddev addon remove pi

The .pi/ folder in your project root and the pi-agent Docker volume are not removed automatically. Clean them up manually if needed:

# Remove the project Pi configuration
rm -rf .pi/

# Remove the named Docker volume
docker volume rm ddev-<your-project-name>-pi-agent

Credits

Contributed and maintained by @mxr576. The initial proof of concept and early development were sponsored by Pronovix.