How I Run Pi in a Docker Sandbox

schemaVersion: "1"
kind: agent
name: pi
displayName: pi
description: "Pi coding agent with mise, running on Docker shell sandbox image"

agent:
  image: "docker/sandbox-templates:shell-docker"
  # Commented out `aiFilename` to prevent this image from including a base AGENTS.md that is too wordy
  # aiFilename: AGENTS.md
  persistence: persistent
  entrypoint:
    run:
      - /usr/local/bin/sbx-pi-entrypoint

# Cannot use memory because `aiFilename` is commented out
# memory:

environment:
  variables:
    LANG: "C.UTF-8"
    LC_ALL: "C.UTF-8"
    # The sandbox proxy enables Node's env proxy support, which emits a noisy
    # experimental Undici warning on every npm/node invocation. Suppress only
    # that warning code so other Node warnings remain visible.
    NODE_OPTIONS: "--disable-warning=UNDICI-EHPA"
    # Host-mounted Pi config directory. The sbx-pi wrapper mounts this path by
    # default so Pi can load shared settings, AGENTS.md, extensions, skills,
    # prompts, themes, etc. Override together with PI_SBX_AGENT_DIR if needed.
    PI_CODING_AGENT_DIR: "/path/to/agent/pi"

commands:
  startup:
    - description: "Update Pi on sandbox startup"
      user: "1000"
      command:
        - /bin/bash
        - -lc
        - |
          set +eu

          pi update
  install:
    - description: "Install base packages needed for mise, npm packages, and native builds"
      user: "0"
      command: |
        set -eu

        export DEBIAN_FRONTEND=noninteractive

        apt-get update && apt-get install -y --no-install-recommends \
          ca-certificates \
          curl \
          gnupg

        install -d -m 0755 /etc/apt/keyrings
        curl --fail --location --show-error --silent https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
          | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
        echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_24.x nodistro main" \
          > /etc/apt/sources.list.d/nodesource.list

        apt-get update && apt-get install -y --no-install-recommends \
          git \
          openssh-client \
          build-essential \
          nodejs \
          fd-find \
          pkg-config \
          python3 \
          python3-pip \
          unzip \
          xz-utils

        if command -v fdfind >/dev/null 2>&1 && ! command -v fd >/dev/null 2>&1; then
          ln -s /usr/bin/fdfind /usr/local/bin/fd
        fi

        # Keep package indexes for live/interactive sandboxes so later ad-hoc
        # apt-get install commands do not require another apt-get update.
        apt-get clean

    - description: "Install mise"
      user: "1000"
      command: |
        set -eu

        mkdir -p /home/agent/.local/bin /home/agent/.config/mise
        curl --fail --location --show-error --silent https://mise.run | sh
    - description: "Install sandbox entrypoint wrapper"
      user: "0"
      command: |
        set -eu

        cat > /usr/local/bin/sbx-pi-entrypoint <<'EOF'
        #!/usr/bin/env bash
        set +e

        # Configure Git SSH signing from the forwarded SSH agent at runtime.
        # The SSH agent socket is available in interactive runs, but may not be
        # available when Docker Sandboxes executes kit startup commands.
        signing_key="$(ssh-add -L 2>/dev/null | head -n 1 || true)"
        if [ -n "$signing_key" ]; then
          git config --global commit.gpgsign true
          git config --global tag.gpgsign true
          git config --global gpg.format ssh
          git config --global user.signingkey "key::${signing_key}"
        else
          echo "No SSH public key available from ssh-add; skipping Git SSH signing config." >&2
        fi

        # Start Pi in the directory where sbx-pi was invoked on the host
        original_pwd="${PI_SBX_ORIGINAL_PWD:-}"
        if [ -n "$original_pwd" ] && [ -d "$original_pwd" ]; then
          cd "$original_pwd"
        fi

        # Pi runs commands non-interactively, so use mise shims for the
        # inherited environment. Install the active project toolset after cd so
        # .tool-versions/mise.toml in the project is detected.
        eval "$(/home/agent/.local/bin/mise activate bash --shims)"
        mise install --yes || true

        pi "$@"
        status=$?

        echo
        echo "pi exited with status ${status}; dropping into sandbox shell."
        echo "Run 'exit' to close the sandbox session."
        echo

        # If Pi exits and we drop into a shell inside the sandbox, put that
        # shell in the same original directory too.
        if [ -n "${original_pwd:-}" ] && [ -d "$original_pwd" ]; then
          cd "$original_pwd"
        fi

        # Prefer normal PATH activation for the fallback interactive shell.
        eval "$(/home/agent/.local/bin/mise activate bash)"

        exec /bin/bash -l
        EOF

        chmod 755 /usr/local/bin/sbx-pi-entrypoint

    - description: "Install Pi globally"
      user: "1000"
      command: |
        set -eu

        npm install -g @earendil-works/pi-coding-agent
        pi --version || true

## Environment

You run in a Docker sandbox with internet access. The workspace is mounted at its host path.
`sudo` is passwordless. Docker is available; nested containers are isolated in the microVM.

Prefer `mise` for project tooling and expose build/test/run commands as mise tasks; use `hk` for git hooks. For one-off
tools, prefer ephemeral execution, e.g. `uv run --with <pkg>`, instead of system installs.

## Work style

Ask clarifying questions only when needed to avoid likely rework.
Fix root causes rather than symptoms.
For bugs, reproduce the issue first when practical; prefer regression tests when the repo supports them.
Before finishing, verify the result; if verification is unclear, ask the user.

Do not revert unexpected user/agent changes. Work around them; if they block you, ask before stashing or reverting.
Ask before destructive actions such as deleting large paths, resetting history, or discarding changes.

## Communication

Be direct. Say when you do not know something or when a request seems wrong.
When asking for guidance, present options and a recommendation.
Use ASCII diagrams when they make complex flows clearer.

## Security

Treat secrets, tokens, credentials, private keys, and `.env` files as sensitive.
Prefer local files and official docs before internet searches. Do not pipe remote scripts to shells without inspection.

#!/usr/bin/env bash
set -euo pipefail

# Run the pi Docker Sandbox kit from anywhere.
# Defaults to this dotfiles checkout's kit, but can be overridden with PI_SBX_KIT.
KIT="${PI_SBX_KIT:-/path/to/sbx/kits/pi}"
AGENT_NAME="${PI_SBX_NAME:-pi}"
ORIGINAL_PWD="$PWD"

# If invoked from inside a Git repository, use the repository root as the
# primary workspace so the whole repo is mounted into the sandbox. This script
# does not cd, so the host shell remains wherever sbx-pi was invoked from. The
# sandbox entrypoint cd's back to ORIGINAL_PWD before starting Pi.
if GIT_ROOT="$(git -C "$ORIGINAL_PWD" rev-parse --show-toplevel 2>/dev/null)"; then
  WORKSPACE_DIR="$GIT_ROOT"
else
  WORKSPACE_DIR="$ORIGINAL_PWD"
fi

PROJECT_NAME="$(basename "$WORKSPACE_DIR")"
SANDBOX_NAME="${PI_SBX_SANDBOX_NAME:-${AGENT_NAME}-${PROJECT_NAME}}"
PI_SBX_AGENT_DIR="${PI_SBX_AGENT_DIR:-/path/to/pi-agent}"

if ! command -v sbx >/dev/null 2>&1; then
  echo "sbx-pi: 'sbx' command not found in PATH" >&2
  exit 127
fi

if [ ! -f "$KIT/spec.yaml" ]; then
  echo "sbx-pi: kit not found: $KIT" >&2
  echo "Set PI_SBX_KIT to the directory containing spec.yaml." >&2
  exit 1
fi

args=("$AGENT_NAME" --kit "$KIT")

# Keep the Git repository root as the primary workspace when called from inside
# a repo, otherwise keep the caller's current directory. Extra workspaces follow
# it, so the sandbox starts in the project rather than in the shared Pi config
# directory.
args+=("$WORKSPACE_DIR")

# Mount the shared Pi config directory as an additional workspace. Docker
# Sandboxes mount workspaces at their absolute host paths, matching the
# PI_CODING_AGENT_DIR configured in the kit.
#
# Set PI_SBX_AGENT_DIR= to disable this automatic mount, or point it at a
# different host-side Pi config directory if you also override the kit env var.
if [ -n "$PI_SBX_AGENT_DIR" ]; then
  if [ ! -d "$PI_SBX_AGENT_DIR" ]; then
    echo "sbx-pi: shared Pi config directory not found: $PI_SBX_AGENT_DIR" >&2
    echo "Set PI_SBX_AGENT_DIR= to disable, or create the directory." >&2
    exit 1
  fi

  args+=("$PI_SBX_AGENT_DIR")
fi

args+=("$@")

set_sandbox_env() {
  sbx exec -d "$SANDBOX_NAME" bash -lc '
    set -e
    original_pwd=$1
    file=/etc/sandbox-persistent.sh
    tmp=$(mktemp)
    if [ -f "$file" ]; then
      grep -Ev "^export (PI_SBX_ORIGINAL_PWD|GIT_DISCOVERY_ACROSS_FILESYSTEM)=" "$file" > "$tmp" || true
    fi
    printf "export PI_SBX_ORIGINAL_PWD=%q\n" "$original_pwd" >> "$tmp"
    printf "export GIT_DISCOVERY_ACROSS_FILESYSTEM=1\n" >> "$tmp"
    cat "$tmp" > "$file"
    rm -f "$tmp"
  ' bash "$ORIGINAL_PWD"
}

# If the sandbox already exists, run it by name. Recent sbx versions reject
# passing workspace arguments to an existing sandbox.
if sbx ls --quiet | grep -qxF "$SANDBOX_NAME"; then
  set_sandbox_env
  existing_args=("$SANDBOX_NAME" --kit "$KIT")
  existing_args+=("$@")
  exec sbx run "${existing_args[@]}"
fi

create_args=("${args[@]}" --name "$SANDBOX_NAME")
sbx create "${create_args[@]}"
set_sandbox_env
exec sbx run "$SANDBOX_NAME" --kit "$KIT" "$@"