Get Started

Quickstart with Pi

View as Markdown

Run the pinned Pi coding agent inside a NemoClaw-managed OpenShell sandbox.

Pi remains a qualified release candidate until the final activation change adds it to the supported agent inventory and managed-image release cohort. Normal installations reject --agent pi before that activation. The qualification controls are not a user setup path.

Requirements

Pi v1 requires:

  • Linux on AMD64 or ARM64.
  • Docker as the OpenShell compute runtime.
  • Node.js 22.19 or later for NemoClaw.
  • A provider and model that support OpenAI Chat Completions, streaming, and structured tool calls.

Native Podman, macOS, Windows, WSL, messaging channels, dashboards, host mounts, and managed MCP are outside the initial Pi support matrix.

Install and Onboard

After Pi activation is available in the selected NemoClaw release, install NemoClaw and select Pi explicitly.

$curl -fsSL https://www.nvidia.com/nemoclaw.sh | \
>  NEMOCLAW_AGENT=pi \
>  NEMOCLAW_SANDBOX_NAME=my-pi \
>  bash

For an existing installation, run the canonical onboarding command.

$nemoclaw onboard --agent pi --name my-pi

Choose a provider and model that use the OpenAI Chat Completions API. NemoClaw keeps the upstream provider credential in OpenShell and gives Pi only the managed https://inference.local/v1 route. The credential remains in the gateway across rebuild and sandbox destruction. When no sandbox needs that provider, remove it explicitly with nemoclaw credentials reset <provider> --yes.

Stock onboarding selects an exact Pi managed-image digest. It does not build the Pi Dockerfile on the host. The reviewed Dockerfile is a trusted CI image-build source, not a user onboarding mechanism. A missing, incomplete, mutable, or inconsistent image contract fails before sandbox creation.

Check the Sandbox

Wait for onboarding to finish, then inspect the registered agent and runtime.

$nemoclaw my-pi status
$nemoclaw list

The status output identifies Pi as a terminal runtime. Pi has no dashboard, messaging, device-pairing, or managed MCP surface.

Start an Interactive Session

Run Pi through the normal launch preflight.

$nemoclaw launch my-pi

You can also open a shell and start Pi directly.

$nemoclaw my-pi connect
$pi

Interactive Pi can ask before it trusts project-local skills, extensions, prompts, and packages. Pi loads AGENTS.md and CLAUDE.md context files before that trust decision; use pi --no-context-files when those files must not enter the prompt. OpenShell policy remains the execution and network authority.

Run a Headless Task

Run one headless task through the public sandbox command boundary.

$nemoclaw my-pi exec --workdir /sandbox --no-tty -- \
>  pi --no-approve --print "Summarise the files in this workspace"

Use JSON mode when automation needs structured event evidence.

$nemoclaw my-pi exec --workdir /sandbox --no-tty -- \
>  pi --no-approve --mode json --print --tools read \
>    "Use the read tool to inspect README.md and report its title"

--no-approve ignores project-local executable resources but does not disable context files; add --no-context-files when required. --tools read limits that invocation to Pi’s read tool. JSON mode writes newline-delimited session events, including structured tool execution events and the final assistant message.

Continue