tool-containers
Search docs…Ctrl K
Menu
GitHub (opens in new tab)

Run Pi Coding Agent with Docker Compose

The pi-agent service runs Pi on the directory in WORKSPACE. compose.sh checks that WORKSPACE is an absolute path, because Compose would resolve a relative one against this directory, then runs docker compose here.

Images
  • GHCRghcr.io/hambn/pi-agent
  • Docker Hubdocker.io/hambn/pi-agent
Use case
Repeatable local sessions
Upstream
github.com/earendil-works/pi (opens in new tab)
Source
tools/ai/pi-agent/docs/docker-compose (opens in new tab)
On this page

Prerequisites

  • Docker Engine with the Compose v2 plugin.
  • An account or API key for a model provider Pi supports.

Run Pi

Shell
WORKSPACE="$PWD" ./compose.sh run --rm pi-agent

Run /login inside Pi to connect a provider; the login is removed with the container. To pass a key from your shell, add -e ANTHROPIC_API_KEY (or another provider's variable) before the service name.

Run without registry access

On a connected machine, run docker save ghcr.io/hambn/pi-agent:ubuntu-browser -o pi-agent.tar. On the offline host, load it and use the air-gapped file, which sets pull_policy: never:

Shell
docker load -i pi-agent.tar
WORKSPACE="$PWD" ./compose.sh -f airgapped.docker-compose.yml run --rm pi-agent

Variables

Variable Required Purpose
WORKSPACE yes Absolute host path mounted at /workspace.
PI_AGENT_IMAGE no Image for both Compose files. Defaults to ghcr.io/hambn/pi-agent:ubuntu-browser; set a digest reference to pin one build.

Workspace

WORKSPACE is mounted at /workspace. Pi runs as UID 1000, so new files belong to UID 1000 on the host.

Files

File contents

airgapped.docker-compose.yml12 lines
# Offline: docker load -i pi-agent.tar first, then
# WORKSPACE="$PWD" ./compose.sh -f airgapped.docker-compose.yml run --rm pi-agent
name: pi-agent

services:
  pi-agent:
    image: ${PI_AGENT_IMAGE:-ghcr.io/hambn/pi-agent:ubuntu-browser}
    pull_policy: never
    volumes:
      - ${WORKSPACE:?Set WORKSPACE to an absolute host path}:/workspace
    stdin_open: true
    tty: true
compose.sh18 lines
#!/usr/bin/env bash
# Compose resolves relative paths against this directory, so require an absolute WORKSPACE.
set -euo pipefail

case "${WORKSPACE:-}" in
/*) ;;
"")
    echo "Set WORKSPACE to an absolute host path." >&2
    exit 2
    ;;
*)
    echo "WORKSPACE must be an absolute host path: $WORKSPACE" >&2
    exit 2
    ;;
esac

cd -- "$(dirname -- "${BASH_SOURCE[0]}")"
exec docker compose "$@"
docker-compose.yml10 lines
# WORKSPACE="$PWD" ./compose.sh run --rm pi-agent
name: pi-agent

services:
  pi-agent:
    image: ${PI_AGENT_IMAGE:-ghcr.io/hambn/pi-agent:ubuntu-browser}
    volumes:
      - ${WORKSPACE:?Set WORKSPACE to an absolute host path}:/workspace
    stdin_open: true
    tty: true

Topics