README.md

Pi Sandbox Setup

This gist contains tooling for running the pi coding-agent harness inside an isolated Docker sandbox.

create_pi_sandbox.sh

create_pi_sandbox.sh automates building a custom Docker sandbox image that contains the pi CLI and your host ~/.pi/agent configuration files.

Prerequisites

• Docker Sandboxes (sbx) installed and on your PATH.
• Host configuration files present at ~/.pi/agent/models.json and ~/.pi/agent/settings.json.

GitHub API Token

The sandbox needs a valid GitHub personal-access token so that pi can interact with the GitHub API and use the installed gh cli. Set the token before running the script.

sbx secret set -g github

For details see the sbx secret set documentation.

Usage

./create_pi_sandbox.sh

The script will:

1. Create a temporary builder sandbox.
2. Install @mariozechner/pi-coding-agent inside it.
3. Save the builder as a local Docker image template (pi-template:latest).
4. Create the named sandbox pi-sandbox from that template.
5. Copy your host models.json and settings.json into the sandbox.

Once finished, open the sandbox with:

sbx run pi-sandbox

create_pi_sandbox.sh

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

# create_pi_sandbox.sh
# Generates a custom Docker sandbox containing the pi installation, then creates
# a named sandbox from that template with host config files copied in.
# Requires: sbx (Docker Sandboxes CLI) and host ~/.pi/agent configs.

SANDBOX_NAME="pi-sandbox"
BUILDER_NAME="pi-builder"
TEMPLATE_TAG="pi-template:latest"
HOST_PI_DIR="${HOME}/.pi/agent"

# ------------------------------------------------------------------------------
# Pre-flight checks
# ------------------------------------------------------------------------------
if ! command -v sbx &> /dev/null; then
    echo "Error: sbx is not installed or not in PATH" >&2
    exit 1
fi

for f in "${HOST_PI_DIR}/models.json" "${HOST_PI_DIR}/settings.json"; do
    if [[ ! -f "$f" ]]; then
        echo "Error: Missing host file: $f" >&2
        exit 1
    fi
done

# ------------------------------------------------------------------------------
# 1. Clean up any stale builder / target sandbox
# ------------------------------------------------------------------------------
if sbx ls --quiet | grep -qx "${BUILDER_NAME}"; then
    echo "==> Removing existing builder sandbox '${BUILDER_NAME}'..."
    sbx rm -f "${BUILDER_NAME}"
fi

if sbx ls --quiet | grep -qx "${SANDBOX_NAME}"; then
    echo "==> Removing existing sandbox '${SANDBOX_NAME}'..."
    sbx rm -f "${SANDBOX_NAME}"
fi

# ------------------------------------------------------------------------------
# 2. Create a shell sandbox (builder)
# ------------------------------------------------------------------------------
echo "==> Creating builder shell sandbox '${BUILDER_NAME}'..."
sbx create shell . --name "${BUILDER_NAME}"

# ------------------------------------------------------------------------------
# 3. Install pi inside the builder sandbox
# ------------------------------------------------------------------------------
echo "==> Installing pi inside builder..."
sbx exec "${BUILDER_NAME}" -- npm install -g @mariozechner/pi-coding-agent

# ------------------------------------------------------------------------------
# 4. Ensure ~/.pi/agent directory exists inside the builder
# ------------------------------------------------------------------------------
SANDBOX_HOME=$(sbx exec "${BUILDER_NAME}" -- sh -c 'echo "$HOME"')
echo "==> Creating pi agent directory (${SANDBOX_HOME}/.pi/agent)..."
sbx exec "${BUILDER_NAME}" -- mkdir -p "${SANDBOX_HOME}/.pi/agent"

# ------------------------------------------------------------------------------
# 5. Stop the builder so it can be snapshotted cleanly
# ------------------------------------------------------------------------------
echo "==> Stopping builder sandbox..."
sbx stop "${BUILDER_NAME}"

# ------------------------------------------------------------------------------
# 6. Save builder as a template
# ------------------------------------------------------------------------------
echo "==> Saving builder as template '${TEMPLATE_TAG}'..."
sbx template save "${BUILDER_NAME}" "${TEMPLATE_TAG}"

# ------------------------------------------------------------------------------
# 7. Create the new pi-sandbox from the template
# ------------------------------------------------------------------------------
echo "==> Creating sandbox '${SANDBOX_NAME}' from template..."
sbx create shell . --name "${SANDBOX_NAME}" --template "${TEMPLATE_TAG}"

# Re-detect home dir for the new sandbox (same image, but kept for safety)
SANDBOX_HOME=$(sbx exec "${SANDBOX_NAME}" -- sh -c 'echo "$HOME"')
sbx exec "${SANDBOX_NAME}" -- mkdir -p "${SANDBOX_HOME}/.pi/agent"

# ------------------------------------------------------------------------------
# 8. Copy host pi configuration files into the new sandbox
# ------------------------------------------------------------------------------
echo "==> Copying host configuration into '${SANDBOX_NAME}'..."
sbx cp "${HOST_PI_DIR}/models.json" "${SANDBOX_NAME}:${SANDBOX_HOME}/.pi/agent/models.json"
sbx cp "${HOST_PI_DIR}/settings.json" "${SANDBOX_NAME}:${SANDBOX_HOME}/.pi/agent/settings.json"

# ------------------------------------------------------------------------------
# 9. Verify pi is configured correctly
# ------------------------------------------------------------------------------
echo "==> Verifying pi installation and configuration..."
sbx exec "${SANDBOX_NAME}" -- pi --version

echo "==> Done. Sandbox '${SANDBOX_NAME}' is ready to use."
echo "    Open it: sbx run ${SANDBOX_NAME}"
echo "    Or exec: sbx exec -it ${SANDBOX_NAME} bash"