Skip to content

Run Pi Coding Agent with Podman

run.sh starts Pi under rootless Podman on the current directory, passing any arguments to pi.

Images: GHCRghcr.io/hambn/pi-agent
Docker Hubdocker.io/hambn/pi-agent
Use case: Rootless sessions on a workstation
Upstream: github.com/earendil-works/pi (opens in new tab)
Source: tools/ai/pi-agent/docs/podman (opens in new tab)

On this page

Prerequisites
Run Pi
Variables
Workspace
Files
File contents
run.sh

Prerequisites

Rootless Podman 4.3 or later, for --userns=keep-id:uid=1000,gid=1000.
An account or API key for a model provider Pi supports.

Run Pi

Shell

./run.sh

Run /login inside Pi to connect a provider; the login is removed with the container. To use an environment key, add -e ANTHROPIC_API_KEY (or another provider's variable) to the podman run line in run.sh.

Variables

Variable	Required	Purpose
`PI_AGENT_IMAGE`	no	Image to run. Defaults to `ghcr.io/hambn/pi-agent:ubuntu-browser`; set a digest reference to pin one build.

Workspace

The current directory is mounted at /workspace with :Z, so SELinux hosts relabel it for the container. --userns=keep-id maps your host user to sysadmin (UID 1000), so files Pi writes stay owned by you.

Files

run.sh runs the published image with rootless Podman.

File contents

run.sh8 lines

#!/usr/bin/env bash
# Run Pi rootlessly against the current directory; :Z relabels it on SELinux hosts.
set -euo pipefail

image=${PI_AGENT_IMAGE:-ghcr.io/hambn/pi-agent:ubuntu-browser}
podman run -it --rm --userns=keep-id:uid=1000,gid=1000 \
    -v "$PWD:/workspace:Z" \
    "$image" "$@"

Topics