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: Network-dependent features (PI_OFFLINE=1, PI_SKIP_VERSION_CHECK=1, PI_TELEMETRY=0) are disabled by default to keep the container self-contained and avoid unexpected outbound traffic.

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

Warning

While process isolation is provided by the container, running coding agents on a local read-write workspace carries inherent security risks (such as prompt injection, credential leaks and host-execution escapes). Please see the Security Advisory to understand these risks and learn how to harden your setup.

Requirements

• DDEV >= v1.25.2
• The trebormc/ddev-ai-ssh add-on (installed automatically as a dependency)

Installation

ddev add-on get mxr576/ddev-pi
ddev restart

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.

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.