Run Pi Coding Agent with Docker

Prerequisites#

• Docker Engine 23 or later.
• An account or API key for a model provider Pi supports.

Run Pi#

./run.sh

The scripts pass no credentials. Inside Pi, run /login to connect a subscription or API key; Pi saves it in the container, and --rm deletes it when you exit. To use an environment key instead, add -e ANTHROPIC_API_KEY (or -e OPENAI_API_KEY, -e GEMINI_API_KEY) to the docker run line in run.sh and export it.

Run without registry access#

On a machine that can pull, save the image:

docker save ghcr.io/hambn/pi-agent:ubuntu-browser -o pi-agent.tar

Copy the tar to the offline host and pass its path first; the remaining arguments go to pi:

./airgapped.run.sh pi-agent.tar

The script loads the tar and runs PI_AGENT_IMAGE with --pull=never, so set that variable if you saved a different tag.

Variables#

Workspace#

The current directory is mounted at /workspace, the image's working directory. Pi runs as sysadmin (UID 1000), so new files belong to UID 1000 on the host.

Files#

• run.sh pulls the image if needed and runs it.
• airgapped.run.sh loads a saved tar and runs it without pulling.

#!/usr/bin/env bash
# Offline host: load the image from a tar saved on an online host, never pull.
#   docker save ghcr.io/hambn/pi-agent:ubuntu-browser -o pi-agent.tar
set -euo pipefail

image=${PI_AGENT_IMAGE:-ghcr.io/hambn/pi-agent:ubuntu-browser}
tar=${1:-pi-agent.tar}
shift $(($# > 0 ? 1 : 0))
[[ -f "$tar" ]] || {
    echo "missing $tar; docker save it on an online host first" >&2
    exit 1
}

docker load -i "$tar"
docker run -it --rm --pull=never \
    -v "$PWD:/workspace" \
    "$image" "$@"

#!/usr/bin/env bash
# Run Pi against the current directory.
set -euo pipefail

image=${PI_AGENT_IMAGE:-ghcr.io/hambn/pi-agent:ubuntu-browser}
docker run -it --rm \
    -v "$PWD:/workspace" \
    "$image" "$@"