[Epic] Support Pi as a first-class NemoClaw agent runtime

[prekshivyas]

Summary

Make Pi a supported NemoClaw agent runtime alongside OpenClaw, Hermes, and LangChain Deep Agents Code.

A user must be able to select Pi during canonical onboarding. NemoClaw must manage Pi through the supported sandbox lifecycle without coupling Pi to one compute runtime.

Delivery target

Target the first supported release during the two-week window from 2026-07-30 through 2026-08-13.

Context

NemoClaw already uses Pi in contributor and CI workflows:

• The root project pins @earendil-works/pi-coding-agent and exposes it through npm run agent.
• Trusted advisor and conflict-resolution workflows use the Pi SDK.
• Those workflows use a digest-pinned OpenShell community Pi sandbox image.

These uses show technical compatibility. They do not establish Pi as a supported NemoClaw agent runtime.

Podman epic #7744 is establishing buildless managed onboarding and compute-runtime contracts. Pi must use those shared contracts rather than add a Docker-only or Podman-specific lifecycle.

Problem Statement

Users cannot select Pi through the supported NemoClaw onboarding path. Pi has no NemoClaw agent manifest or defined product lifecycle.

Manual Pi sandbox configurations do not define:

• artifact ownership and update cadence;
• supported inference providers, models, and API families;
• credential custody and network policy;
• tool, skill, extension, and prompt trust boundaries;
• persistent state, backup, rebuild, and upgrade behavior;
• status, logs, diagnostics, and failure recovery;
• platform and compute-runtime compatibility;
• managed-image publication and release qualification.

Without these contracts, each Pi deployment is a custom solution that NemoClaw cannot qualify or support.

Desired Behavior

A user can select Pi through interactive onboarding or a supported non-interactive command such as:

nemoclaw onboard --agent pi

Stock onboarding selects an exact Pi managed-image digest. It does not build a repository Dockerfile on the user's host.

NemoClaw creates an OpenShell sandbox with a pinned Pi runtime. Pi uses managed inference without receiving the upstream provider credential.

The public NemoClaw lifecycle must identify the sandbox as a Pi sandbox. Supported commands must cover onboarding, connection, status, logs, rebuild, backup, upgrade, and destroy behavior where applicable.

Pi must support one documented interactive terminal flow and one documented non-interactive flow.

Compute-runtime boundary

Pi is an agent runtime. Docker, Podman, and future providers such as MXC are compute runtimes.

• Pi-specific code owns the agent manifest, startup profile, configuration, state, tools, policies, and entry points.
• Compute-runtime providers own image launch, lifecycle mutation, recovery, snapshot, and cleanup mechanics.
• Pi code must not branch on Docker or Podman.
• Docker or Podman code must not branch on Pi.
• Shared managed-image, bootstrap, lifecycle, and inference contracts compose the two dimensions.

A reviewed Dockerfile may remain a CI image-build source. It is not the stock onboarding mechanism.

Pi does not need to wait for Podman activation unless the accepted v1 scope includes Podman at launch. If Pi ships first, #7744 must include Pi in its all-shipped-agent activation gate.

Product Decision Required

Maintainers must accept this epic before Pi becomes a supported product surface. The accepted decision must name:

• the product and engineering owners;
• the canonical agent ID;
• the supported Pi package, managed image, build source, and distribution source;
• the version pin and update cadence;
• the supported host platforms and architectures;
• the supported compute runtimes at Pi launch;
• whether Podman is launch scope or joins when [Epic] Support native Podman with buildless managed onboarding #7744 activates;
• the supported inference providers, models, and API families;
• the owner of each lifecycle and persistent-state boundary;
• the credential, network, filesystem, tool, skill, and extension policies;
• the managed-image catalog, publication cohort, and startup-profile contracts;
• the release qualification environment and required evidence;
• the support lifecycle and compatibility policy after launch.

Minimal v1 Scope

• One Pi agent manifest under agents/pi/.
• One integrity-verifiable Pi runtime package and managed OCI image.
• Exact managed-image digests for each accepted platform and architecture.
• Registration in the managed-image catalog and atomic publication cohort.
• Interactive and non-interactive terminal execution.
• Managed inference through the supported inference.local route.
• A Pi-specific baseline network policy.
• Declared persistent and reconstructible state.
• Shared, compute-runtime-neutral onboarding, inventory, status, logs, recovery, rebuild, backup, upgrade, and destroy integration.
• Actionable errors for unsupported models, missing configuration, inference failure, runtime startup failure, and unsupported compute runtimes.
• Targeted unit, integration, package-contract, and live E2E coverage.
• User documentation, troubleshooting, compatibility limits, and release material.

Constraints and Non-goals

• Do not add a shared multi-agent manifest. Pi must have its own agent manifest and evidence.
• Do not treat the existing contributor dependency or CI image as product approval.
• Do not use an unpinned package, image tag, or runtime auto-update path.
• Do not build the stock Pi image from a Dockerfile during user onboarding.
• Do not expose upstream provider credentials to the Pi sandbox.
• Do not add a Pi-specific Docker, Podman, gateway, lifecycle, snapshot, or recovery branch.
• Do not add Pi behavior to the current feat(runtime): add native Podman support for all agents #7872 draft architecture. Use the accepted [Epic] Support native Podman with buildless managed onboarding #7744 contracts.
• Do not refactor every agent integration as part of this epic.
• Messaging channels and a dashboard are outside v1 unless the accepted product decision adds them.
• Replacing the repository-pinned contributor command or existing Pi CI automation is outside v1.

Implementation Idea

Use the existing manifest-first agent architecture:

agents/pi/
  manifest.yaml
  start.sh
  generate-config.ts
  policy-additions.yaml
  Dockerfile          # reviewed CI image-build source, if required
  Dockerfile.base     # reviewed CI base-image source, if required

Add Pi to agent discovery, the managed-image contract and repository map, the atomic publication cohort, and onboarding through the existing registries.

Pi must provide data for the shared startup-profile and image-runtime contracts. It must not add compute-runtime orchestration.

Reuse the existing Pi package or OpenShell community image only after maintainers accept its ownership, integrity, lifecycle, startup-profile, and compatibility contracts.

Coordinate the implementation with #7744, #7756, and #7772. Do not make the Pi release depend on unfinished Podman activation unless the accepted product decision requires Podman at launch.

Acceptance Criteria

• Maintainers accept the product decision and record every required owner and lifecycle contract.
• Carlos Villela reviews the selected Pi runtime, managed-image, startup-profile, and agent-specific lifecycle boundaries.
• Interactive onboarding and nemoclaw onboard --agent pi select and persist the Pi agent.
• Stock onboarding selects an exact managed-image digest without a host Dockerfile build.
• Pi is registered in the managed-image catalog and atomic publication cohort.
• A fresh supported installation starts the pinned Pi runtime through a documented public command.
• Interactive and non-interactive Pi sessions complete a tool-using task through managed inference.
• The Pi sandbox does not contain the upstream provider credential.
• Inventory, status, logs, diagnostics, rebuild, backup, upgrade, and destroy behavior identify and preserve the declared Pi contracts.
• Pi integration contains no Docker- or Podman-specific lifecycle branch.
• Policy tests permit only the required inference and tool endpoints.
• Negative tests deny undeclared network access, host control, and credential access.
• Package and image identities are pinned and integrity-verifiable.
• Supported host platforms, architectures, and compute runtimes pass the accepted compatibility matrix.
• If Podman is not Pi launch scope, [Epic] Support native Podman with buildless managed onboarding #7744 records Pi as required before Podman activation.
• A fresh live environment reproduces onboarding and the acceptance task from the exact candidate commit.
• Documentation explains onboarding, operation, state, security boundaries, compatibility limits, and recovery.
• A documentation writer reviews the implementation and documentation evidence.

Work Tracking

• [Pi 1/7] Accept product scope, ownership, threat model, and compatibility matrix #7926 — Accept product scope, ownership, threat model, and compatibility matrix.
• [Pi 2/7] Add the pinned Pi runtime, image, manifest, and entry points #7925 — Add the pinned Pi runtime, managed image, manifest, and entry points.
• [Pi 3/7] Integrate Pi onboarding, lifecycle, state, and recovery #7927 — Integrate Pi onboarding, lifecycle, state, and recovery.
• [Pi 4/7] Integrate managed inference and credential handling #7930 — Integrate managed inference and credential handling.
• [Pi 5/7] Define Pi tool, skill, extension, filesystem, and network policies #7924 — Define Pi tool, skill, extension, filesystem, and network policies.
• [Pi 6/7] Add deterministic tests and live E2E qualification #7928 — Add deterministic tests and live E2E qualification.
• [Pi 7/7] Document Pi onboarding, operations, and release support #7929 — Document Pi onboarding, operations, and release support.

Category

Feature

Checklist

• I searched open and closed issues and this is not a duplicate.
• I described the problem and desired behavior.