docs: run a minimal agent on the pi runtime locally (no fleet repo); verify on Linux and macOS

[waynesun09]

Problem

Running agents locally assumes the fleet: clone fullsend-ai/agents, run triage/review/code on Claude Code. With runtime: pi landing in #6467 (#6464) developers want to build on the pi runtime now — but the fleet side (fullsend-ai/agents#935: **/pi policies, .pi/ protected paths, harness image-digest bumps) is not done, so a full fleet agent run on pi is not possible yet.

A basic local run on pi is already possible without the fleet repo, because fullsend run --fullsend-dir <dir> resolves a config-registered agent to a local harness and runtime: pi in that directory's config.yaml selects the backend (internal/cli/run.go resolveAgentSource / backendFromConfigFile). Nothing documents that path, and it has not been verified on both supported platforms.

What to document

A new section in docs/guides/user/running-agents-locally.md (and a pointer from docs/runtimes.md "Pi-specific known constraints"): "Run a minimal agent on the pi runtime" — no fullsend-ai/agents clone required.

Minimal --fullsend-dir layout to describe and ship as a copy-pasteable example (e.g. docs/examples/pi-hello/ or an eval/-style fixture):

pi-hello/
├── config.yaml          # version: "1", runtime: pi, agents: [{name: hello, source: harness/hello.yaml}]
├── harness/hello.yaml   # agent: agents/hello.md, role: triage, image: <sandbox image with PI_VERSION>,
│                        # policy: policies/local.yaml (Vertex egress), model: haiku
├── agents/hello.md      # Claude-style agent file: frontmatter tools: Bash(ls), Write + a deterministic task
└── policies/local.yaml  # minimal OpenShell policy: *.googleapis.com, binaries **/node (and **/pi)

Run shape:

fullsend run hello \
  --fullsend-dir ./pi-hello --target-repo /tmp/target-repo \
  --env-file fullsend-gcp.env --no-post-script --keep-sandbox --output-dir /tmp/fullsend
# expect: runtime: selected "pi" from ./pi-hello/config.yaml

Cover: what the run prints (runtime: selected "pi", pi --version preflight), the artifacts (output.jsonl session header, transcripts/<agent>-<timestamp>_<id>.jsonl, metrics.json with "runtime": "pi", pi-debug.log with --debug), skills/analyze-transcript on the session file, the knobs (FULLSEND_PI_MODEL, FULLSEND_PI_PROVIDER, FULLSEND_PI_BASH_ALLOWLIST=enforce), credentials (a service-account key or WIF config in GOOGLE_APPLICATION_CREDENTIALS; the local-run guide's existing GCP section applies — the pi Vertex provider reads the same variables), and the security hooks (on by default; the run refuses to start without the adapter, exit 97).

Image and CLI until the release ships

• Until a release publishes sandbox images built from feat(#6464): add the pi runtime (stream parser, Bootstrap/Run, Vertex provider, enablement) #6467, build images/sandbox/Containerfile locally (podman build -t localhost/fullsend-sandbox:pi images/sandbox) and point the run at it with FULLSEND_SANDBOX_IMAGE=localhost/fullsend-sandbox:pi (or set image: in the local harness). Document that this goes away once the published fullsend-sandbox image carries PI_VERSION.
• Build the CLI from the branch/tag (make build); on macOS note --fullsend-binary for the Linux binary copied into the sandbox and FULLSEND_SANDBOX_ARCH (see the guide's Platform notes).

Verification

• Fedora + rootless Podman (the existing Linux notes): the minimal run completes, metrics.json says runtime: pi, a toolCall appears in the session transcript, analyze-transcript summary works
• macOS (Apple silicon, Podman machine; an internal Mac host is available for this): same run, plus the arch/--fullsend-binary notes verified
• A planted .pi/extensions/evil.js in the target repo is not loaded (the --no-approve / defaultProjectTrust: never guarantee) — cheap to include as a "what the sandbox protects you from" step
• After the release: replace the local-image step with the published image and re-run once on each platform

Acceptance criteria

• Guide section + example directory merged; docs/runtimes.md links to it
• Both platform checklists above ticked with the CLI/image versions used
• No dependency on fullsend-ai/agents for the minimal run (fleet agents on pi remain tracked in Enable fleet agents on the pi runtime agents#935)

Related

• Track pi (earendil-works/pi) as a supported agent runtime #6464 — pi runtime tracker; feat(#6464): add the pi runtime (stream parser, Bootstrap/Run, Vertex provider, enablement) #6467 — implementation PR
• Enable fleet agents on the pi runtime agents#935 — fleet enablement (C1 plumbing, C2 pilot)
• docs/runtimes.md — Pi-specific known constraints, selection, knobs

[fullsend-ai-triage]

🤖 Triage · ⚠️ Cancelled · Started 5:54 PM UTC · Ended 5:54 PM UTC

Commit: 55de229 · View workflow run →

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 5:56 PM UTC · Completed 6:01 PM UTC

Commit: 55de229 · View workflow run →

[fullsend-ai-triage]

This documentation task depends on PR #6467 (pi runtime implementation), which is still open. The guide section, example directory, and verification checklist all require runtime: pi to be functional — the verification steps check metrics.json for "runtime": "pi", expect toolCall entries in session transcripts, and require ticking platform checklists with specific CLI/image versions.

While draft work could proceed by building from the #6467 branch, the docs cannot be verified end-to-end or merged until that PR lands. Once #6467 merges, this issue is ready to pick up — the specification is thorough and includes everything a contributor needs: the target file (docs/guides/user/running-agents-locally.md), the example directory layout (pi-hello/), run command shape, artifacts to document, knobs to cover, and acceptance criteria.

Note: The issue correctly scopes out fleet enablement (fullsend-ai/agents#935) — only the minimal local run path is in scope here.

Blocked by:

• feat(#6464): add the pi runtime (stream parser, Bootstrap/Run, Vertex provider, enablement) #6467

---

Labels: Documentation task touching the docs guide and the runner/sandbox components for the pi runtime, at medium priority since it is blocked on #6467.

[waynesun09]

Unblocked — a minimal local pi run now works end to end

This was filed when no real pi run had ever happened. One has now, on Fedora with the published sandbox image, and it reached the model:

runtime: selected "pi" from /tmp/fs-pi/agents-pi/config.yaml
→ Agent: claude-haiku-4-5 (v0.84.2)
→ Result: stop     Turns: 2
    Tokens: in=7601 out=360 reasoning=185
  ✓ Agent exited with code 0 (6.7s)

Verified from artifacts, not just the log: metrics.json carries {"runtime": "pi", ...}; the agent's agent-result.json landed in iteration-1/output/; a pi session transcript was extracted with 3 toolCall / 2 toolResult records; the hook manifest loaded with the full plan (PreToolUse[Bash]: tirith_check.py; PreToolUse[Bash|WebFetch]: ssrf_pretool.py; PreToolUse[*]: canary_pretool.py; PostToolUse[*]: posttool_chain.py; PostToolUseFailure[*]); security findings were clean.

Two prerequisites landed since this issue was written: the sandbox image now carries pi 0.84.2 + the Vertex extension, and #6505 moved that extension out of /opt, which the sandbox filesystem policy denies (#6504) — before that fix every pi run died at 0 turns with EACCES.

The recipe that works

The premise in the description — that a bare --fullsend-dir with config.yaml + harness/ + agents/ is enough — is not sufficient, and that is the main thing to document. A hand-rolled minimal directory gets as far as loading the extension and then fails with:

[pi-anthropic-vertex] disabled: set GOOGLE_CLOUD_PROJECT or ANTHROPIC_VERTEX_PROJECT_ID
Error: Model "anthropic-vertex/claude-haiku-4-5" not found.

because sandbox environment comes only from the harness (ADR 0055 env.sandbox → .env.d/) and credentials come from host_files. Neither is inherited from --env-file, which sets the runner environment only. The working harness mirrors harness/triage.yaml:

agent: agents/pi-smoke.md
policy: policies/base.yaml
openshell:
  profiles:
    - profiles/fullsend-vertex-ai.yaml     # egress allowlist for Vertex
providers:
  - providers/vertex-ai.yaml               # OpenShell inference provider

role: triage
slug: fullsend-ai-pi-smoke
model: haiku
image: ghcr.io/fullsend-ai/fullsend-sandbox:latest

host_files:
  - src: env/gcp-vertex.env
    dest: /sandbox/workspace/.env.d/gcp-vertex.env
    expand: true
  - src: ${GOOGLE_APPLICATION_CREDENTIALS}
    dest: /tmp/.gcp-credentials.json

config.yaml must both register the harness and select the runtime — registering only the file on disk is not enough (resolveAgentSource fails with "no config and agents-repo fallback unavailable"):

version: "1"
agents:
  - source: harness/pi-smoke.yaml
defaults:
  runtime: pi

Because the harness references policies/, profiles/, providers/ and env/, the quickest honest path today is to copy those four directories out of an fullsend-ai/agents clone (or ship them in the example). If the goal is a genuinely fleet-free example, the doc needs a self-contained policies/local.yaml + Vertex profile/provider too — worth deciding which of the two this example should be.

Invocation:

fullsend run pi-smoke \
  --fullsend-dir ./pi-hello \
  --target-repo /path/to/any/git/repo \
  --env-file ./fullsend-gcp.env \
  --no-post-script \
  --output-dir /tmp/fullsend-out

Three traps worth calling out in the doc

1. --debug needs =. It is an optional-value flag, so --debug "*" makes cobra read * as a second positional and fail with accepts 1 arg(s), received 2. Use --debug='*'.
2. A stale cached :latest surfaces as a confusing error. Podman reuses whatever it cached, so an image predating the pi layers fails at pi preflight: pi --version exited 127: sh: 1: pi: not found rather than saying the image is old. podman pull ghcr.io/fullsend-ai/fullsend-sandbox:latest before the run belongs in the prerequisites. (Good news: the preflight fails closed rather than proceeding.)
3. A custom harness must carry its own host_files and OpenShell profile, per above — otherwise the agent starts with no credentials and the failure appears one layer away from its cause, in pi-debug.log, not in the runner output.

Caveat on scope

This run authenticated with gcloud ADC (GOOGLE_APPLICATION_CREDENTIALS pointing at application_default_credentials.json), not the WIF external_account path CI mints. The doc should say which it covers; ADC is the realistic local path, and it works.

macOS (mac-mini) is still unverified — that half of this issue stands.