Skip to navigation
Get Started

Quickstart with Pi

View as Markdown

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

Pi remains a 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. NVIDIA Endpoints and supported fixed hosted providers use native endpoints through sandbox-attached OpenShell providers. Custom and local providers retain the shared inference.local route. The credential remains in OpenShell provider state across rebuild and sandbox destruction. When no sandbox needs that provider, remove it explicitly with nemoclaw credentials reset <provider> --yes.

Stock onboarding selects a 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.

Set optional Pi model metadata before onboarding when the selected model needs an explicit context window, output limit, or reasoning declaration. Refer to Configure Model Limits.

Resume Interrupted Onboarding

Correct the reported condition, then continue the recorded Pi onboarding session.

nemoclaw onboard --resume

Resume reuses the recorded agent, provider, model, and sandbox name. Pi model-tuning environment values are not stored in an incomplete onboarding checkpoint, so re-export NEMOCLAW_CONTEXT_WINDOW, NEMOCLAW_MAX_TOKENS, and NEMOCLAW_REASONING before resuming when the original run supplied them. Resume does not change a completed sandbox. Use nemoclaw onboard --agent pi --name my-pi --fresh to discard an incomplete Pi session and start again. Add --recreate-sandbox when replacing an existing completed sandbox.

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 --no-context-files --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. --no-context-files excludes AGENTS.md and CLAUDE.md from the prompt; omit it only when automation must accept project instructions. --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