# ZelPi — `zos` CLI **ZelPi** (Physical Intelligence Operating System) as an `npm install`-able, self-contained command-line OS for autonomous robot fleets. ```bash 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 ZelPi 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 ```bash 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 ZelPi server speaks. State persists to `~/.pi-os/embedded-state.json`. Intent parsing uses a real LLM when one is available — if the **Claude Code CLI** is installed and logged in, System 2 reasons on **Claude Haiku via your own Claude Pro/Max plan** (no API key; set `PIOS_LLM_PROVIDER=claude` to force it) — and degrades to the deterministic offline parser otherwise. `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): ```bash 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 | ```bash 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 "" [--profile p] submit a natural-language intent safety [override|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 stack | arch live 9-layer architecture + two-path latency budget agent [""] Agent layer: planner · plan-cache · instruction firewall memory [recall ""|clear] Memory layer: episodic · semantic · skill optimise [clear] per-layer optimisers (Agent LLM · World Model · Policy) hal [connect |disconnect] Hardware Abstraction Layer — link a real robot (native, no ROS) spe State Perception Engine status (quant · cache · horizon · latency budget) perceive "" predict objects, affordances & task-relevance the robot will understand spe predict [--horizon n] world-model trajectory (proprio/visual/perception confidence) tactile [--robot ] grasp prediction (contact, force, slip, stability) firewall [assembly|human-collab|precision] validate the fleet vs. the ISO/ANSI safety envelope spe quant set inference quantisation; spe task sets the firewall constraints fleet list robots fleet enroll --chassis "" [--name ] [--aisle ] models model registry (vla→S2, act→S1, mhal→S0) models train --kind vla|act|mhal [--name ] [--embodiment ] models deploy hub [socs|chassis|models] compatible SOCs, embodiments, model registry hub pull download REAL weights, then register in the fleet sim (--sim-only skips download) hub install download REAL weights only; hub status lists what's on disk gpu [setup] detect NVIDIA GPU · install CUDA torch into the models venv (hub install/pull auto-offer this when they detect an unused GPU) hyworld task|text|image|video HunyuanWorld-2.0 — 3D worlds from text/images/video (isolated venv) hyworld install [--gpu] install · --gpu upgrades the venv: CUDA torch + real gsplat where possible pybullet load [<.ply>] drop the generated world into PyBullet physics with the RX1 robot lingbot install LingBot-World — interactive video world model (isolated venv) lingbot pull [fast|cam|act] download a checkpoint (fast≈75GB, cam/act≈160GB — disk preflight + confirm) lingbot generate --footage --prompt "

" footage/image + prompt → explorable video world babyros up [--port 9091] built-in ROS-like broker — rosbridge v2 wire protocol, no ROS install; zelros / roslibjs / createRosDriver connect to it unchanged babyros status | topics broker reachability · rosapi introspection babyros echo stream messages; babyros pub publishes one slam launch [--duration s] [--speed x] SLAM demo stack: sim world (lidar + drifting odom + biased IMU) + EKF sensor fusion + occupancy-grid SLAM as babyros nodes; prints fused-vs-odometry error live slam attach --url REAL robot: run only fusion+SLAM against a live rosbridge feed (--scan/--odom/--imu remap topic names) slam map [--out map.pgm] render the current /map (terminal ASCII + PGM export) slam status fused pose · gyro-bias estimate · map fill % docs [name] read the bundled reference docs (cli · hardware · architecture · spe · backend) up [--ros] [--force] [--embedded] boot a backend down stop the embedded backend daemon mcp run the MCP server (expose ZelPi to AI agents over stdio) login [user] fetch + store a dev JWT metrics Prometheus exposition config [set ] 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`, and the SPE tools `pios_spe_status`, `pios_perceive`, `pios_firewall`, `pios_tactile`. ```json { "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. ```bash 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).