PI-OS — zos CLI

PI-OS (Physical Intelligence Operating System) as an npm install-able, self-contained command-line OS for autonomous robot fleets.

npm install -g pios     # installs the `zos` command
zos                     # interactive OS shell — boots a backend automatically

No repo, no database, no API keys required: the package ships a bundled simulation engine and an embedded backend that auto-starts on first use. Point it at a real PI-OS backend later with one env var.

It implements the "AI Integration for Embedded" architecture as a top-to-bottom command surface:

CLI / REPL              bin + cli/repl          ← top layer
   │
MCP / API Hooks         cli/client · cli/mcp     ← agents (north) + backend (south)
   │
Kernel — QoS router     cli/kernel + engine      ← Robustness | Optimisation | System-Critical
   │
Model layer (VLM·WM·VLA·LLM)   models train/deploy
   │
Cloud (train/store)     hub pull · models train
   │
Hub / Repo (SOCs · HF)  cli/hub                  ← compatible SOCs + HuggingFace registry

Quick start

zos                                  # OS shell (auto-starts the embedded backend)
zos status                           # health · profile · fleet · deployed models
zos intent "Inventory Aisle 4"       # natural-language intent → System-2 plan → dispatch
zos profile optimisation             # switch the kernel QoS profile
zos hub pull openvla/openvla-7b      # load a model from HuggingFace
zos models deploy M4                 # promote a trained model to the fleet
zos watch                            # live activity feed
zos down                             # stop the embedded backend daemon

Bare text in the shell is treated as an intent, so zos feels like a conversational OS console.

How it runs

• Embedded (default). Any command auto-starts a local backend (cli/embedded.mjs) running the bundled engine over the same WS+HTTP protocol the full PI-OS server speaks. State persists to ~/.pi-os/embedded-state.json. Intent parsing is the deterministic offline parser (no keys). zos up runs it in the foreground; zos down stops the daemon.

• Connected. Point at a full backend (with a live LLM, ROS, MLflow, auth):

  export PIOS_HOST=http://your-host:8787
  export PIOS_WS_URL=ws://your-host:8787
  zos status
  # or persist:  zos config set host your-host && zos config set port 8787

The Kernel — QoS profile router

Every intent is routed through one execution profile; the engine applies it, biasing Safety-Broker scrutiny and execution speed.

| Profile | Speed | Safety gating | Use | |---|---|---|---| | balanced | nominal | nominal | kernel default | | robustness | −5% | +20% | many SOCs/buses, multi-system spread | | optimisation | +40% | −50% | fast routine tasks, speed > deliberation | | system-critical | −18% | +80% | precise, high-integrity work |

zos profile                       # list + active
zos profile system-critical
zos intent "Retrieve the green box from Aisle 3" --profile system-critical

Commands

status                          backend health, profile, fleet, deployed models
intent "<text>" [--profile p]   submit a natural-language intent
safety [authorize|reroute|abort] show / resolve the Human-in-the-Loop gate
watch                           stream the live activity feed
pause | resume | reset          fleet lifecycle

profile [name]                  kernel QoS router

fleet                           list robots
fleet enroll --chassis "<c>" [--name <n>] [--aisle <n>]

models                          model registry (vla→S2, act→S1, mhal→S0)
models train --kind vla|act|mhal [--name <n>] [--embodiment <e>]
models deploy <id>

hub [socs|chassis|models]       compatible SOCs, embodiments, model registry
hub pull <key|hf-id>            load a model from HF (e.g. pi0, openvla/openvla-7b)

up [--ros] [--force] [--embedded]   boot a backend
down                            stop the embedded backend daemon
mcp                             run the MCP server (expose PI-OS to AI agents over stdio)
login [user]                    fetch + store a dev JWT
metrics                         Prometheus exposition
config [set <key> <value>]      backend host/port/token

MCP — drive the fleet from an AI agent

zos mcp runs a Model-Context-Protocol server over stdio (JSON-RPC 2.0). Tools: pios_status, pios_intent, pios_set_profile, pios_fleet, pios_models, pios_deploy_model, pios_resolve_safety, pios_hub.

{
  "mcpServers": {
    "pi-os": { "command": "zos", "args": ["mcp"], "env": { "PIOS_HOST": "http://127.0.0.1:8787" } }
  }
}

Environment

| Var | Meaning | |---|---| | PIOS_HOST | backend HTTP base (e.g. http://10.0.0.5:8787) | | PIOS_WS_URL | backend WS base | | PIOS_TOKEN | JWT for an auth-enabled backend (zos login fetches a dev token) | | PIOS_NO_AUTOSTART | disable embedded auto-start | | NO_COLOR | disable ANSI color |

Config persists to ~/.pi-os/config.json.

Publishing (maintainers)

The publishable package is assembled from this repo into cli-dist/ — lean (only ws), self-contained (bundled engine), free of the web-app deps.

npm run build:pkg              # → cli-dist/  (esbuild bundle + cli/ + bin/ + package.json)
cd cli-dist
npm publish --access public    # requires `npm login`

Requires Node ≥ 18 (uses the global WebSocket client on Node 21+, falls back to ws on older runtimes).