nebius-physical-ai: Instructions file for Claude Code

Nebius Physical AI

Nebius Physical AI is the workbench and workflow layer for running robotics, simulation, perception, and synthetic-data workloads on Nebius infrastructure. The repo centers on the npa CLI/SDK, containerized workbench tools, and SkyPilot workflows that compose those tools through S3 artifacts. The current product shape is a tool marketplace that customers can adapt without hardcoding project-specific infrastructure.

Claude Code should treat this file as a lightweight index. Scan skills/index.yaml first, then load the relevant root skills/ entry before making architecture, review, or domain judgments.

Skill Index

• skills/index.yaml: root manifest with name, when-to-use, path, and CI smoke expectations.
• skills/atomic/architecture/SKILL.md: platform architecture and validation state.
• skills/workflows/first-run-setup/SKILL.md: zero to a first verified result on a fresh machine or new project — an ordered, gated path (install → configure → credential preflight → cheapest-proof workload → validate spec → provision → image pullability → submit), with a stop condition at every step.
• skills/atomic/gpu-first-guidance/SKILL.md: recommending a path, writing user-facing docs, or answering "what should I run first?" — lead with the Nebius GPU path, describe hosted inference by what it does, and stay warm and genuinely helpful when someone asks about cost or has no cluster yet.
• skills/atomic/health-preflight/SKILL.md: there is no npa doctor. Prove service credentials with npa workbench health preflight, request --checks nebius before provisioning, and verify gated-model access with npa workbench health access before spending GPU time.
• skills/atomic/debug-failed-run/SKILL.md: triage a run that failed, hung, or produced no artifacts — status and pod-level reason, stage logs, S3 evidence, image pullability, scheduling, and the resume-vs-cancel decision.
• skills/atomic/teardown-and-cost/SKILL.md: stop spend safely — the mandatory cancel-before-destroy ordering, cloud versus local state, and the orphan audit for leaked clusters, agent VMs, controllers, buckets, and cross-project fleets.
• skills/workflows/add-workbench-tool/SKILL.md: add a new workbench tool end to end — implementation, CLI, SDK, toolRef catalog, container, tests, docs, and skill, in the order that keeps every CI gate green.
• skills/atomic/npa-cli-conventions/SKILL.md: write or modify an npa CLI command or SDK function — registration, the --input-path/--output-path contract, output format, error handling and exit codes, the decorators that are easy to forget, and config/credential access.
• skills/atomic/toolref-argv-contract/SKILL.md: the contract that stops a workflow stage from rendering cleanly and then crashing in the pod.
• skills/atomic/pre-pr-validation/SKILL.md: which of the six PR gates apply to a change, and the exact local command for each, cheapest first.
• skills/atomic/audit-container-docs/SKILL.md: required catalog reconciliation when a workbench image or solution is added, removed, retagged, reclassified, published, or otherwise changed; it keeps the public-image table aligned with repository intent and anonymous GHCR state.
• skills/atomic/guardrail-failures/SKILL.md: map a failing guardrail or CI gate to its cause and fix.
• skills/atomic/agent-development/SKILL.md: build, enhance, or test the NPA chat agent backend (grounded-first routing, cost-aware Token Factory model selection, embedded-backend mechanism, cheap-token test tiers).
• skills/atomic/agent-visual-feedback/SKILL.md: Describe-this viewer feedback for Rerun / video / image / data panes (multimodal vision tier).
• skills/atomic/review-checklist/SKILL.md: review risk classification.
• skills/atomic/physical-ai-context/SKILL.md: robotics, sim-to-real, GPU-routing, Genesis, Isaac Lab, LeRobot, SONIC, GR00T, Cosmos, or BDD100K context.
• skills/tools/scenario-gen/SKILL.md: adversarial scenario generation — an RL adversary that maximizes failures of a policy-under-test, scenario ranking, and the adversarial-scenario-hardening workflow.
• skills/tools/dataset/SKILL.md: dataset-of-record — ingest, validate, curate, and query production sensor data as a versioned, lineage-tracked dataset (FiftyOne curation + LanceDB query index).
• skills/tools/foxglove/SKILL.md: Foxglove embedded viewer — the @foxglove/embed TypeScript SDK in the agent UI, MCAP recordings (convert/inspect/publish), and the npa-foxglove-embed container.
• skills/tools/insights/SKILL.md: lineage graph + common metrics store over workflow-run artifacts — non-invasive ingest-run, query, compare, lineage traversal, and dashboard (CPU-only, append-only S3 JSONL, LanceDB-optional).
• skills/tools/leisaac/SKILL.md: LeIsaac browser teleoperation, secure agent-relay transport, immutable LeRobot datasets, custom bundles, and PAIDF interoperability.
• skills/tools/fleet/SKILL.md: deploy a fleet of Nebius Managed Kubernetes (k8s-training) clusters across one or many projects in a tenant from an npa.fleet/v0.0.1 spec — identical and/or custom clusters, create-on-demand projects, and a k8s-training source that can consume the latest upstream recipe.
• skills/tools/token-factory/SKILL.md: zero-GPU hosted inference (captioning, batch generation, Cosmos physical-AI reasoning) — the cheapest tier that produces a real artifact, with no cluster and no provisioning.
• skills/tools/vlm-eval/SKILL.md: score rollouts with a VLM and turn the score into a gate — run vs loop, rubric/threshold benchmark sweeps, backend selection, and judging against a plan an earlier stage wrote.
• skills/tools/golden-eval/SKILL.md: prove a container image actually works — per-container hello-world manifest, dry-run/local/serverless tiers, batch runs, and the offline manifest validation that gates CI.
• skills/tools/cosmos3-ray-serve/SKILL.md: deploy and operate persistent Cosmos3-Nano generation through NVIDIA Cosmos Framework's native dynamically batched Ray Serve path, with guarded runtime weight fetch and S3 provenance.
• skills/tools/cosmos3-super-benchmark/SKILL.md: reproduce the fixed Cosmos3-Super vLLM-Omni primary sweep on one eight-GPU B200 or H200 node across the 1x8, 2x4, 4x2, and 8x1 arrangements with strict MP4 validity and shared-window throughput accounting.
• skills/tools/burst/SKILL.md: one gang-scheduled multi-node GPU job with torchrun rendezvous, deliberately not a workflow surface.
• skills/tools/gpu-cluster-provisioning/SKILL.md: managed-image vs GPU-Operator driver strategy (operator mode is unsafe on NVSwitch), the post-apply health gates, accelerator-name discovery, and triage for nodes whose GPUs do not work.
• skills/tools/detection-training/SKILL.md: Faster R-CNN detectors trained from LanceDB materialized views (BDD100K failure-mode slices).
• skills/tools/artifact-viz-share/SKILL.md: sim demos → LeRobotDataset → .rrd/MP4, and time-boxed presigned Rerun share links.
• skills/tools/mjlab/SKILL.md: MJLab locomotion evaluation and SONIC checkpoint scoring.
• skills/tools/retargeting/SKILL.md: motion retargeting in SONIC locomotion workflows.
• skills/workflows/sim-to-real/SKILL.md: generic sim-to-real workflow planning.
• skills/workflows/sim2real-operate/SKILL.md: run, monitor, and debug the compositional Sim2Real npa.workflow through the standard SkyPilot runtime (validate/plan/submit, durable S3 resume, health checks, job monitoring).
• skills/workflows/agent-fresh-operate/SKILL.md: npa-driven agent teardown, fresh-setup, tiered verify gates, and deploy failure recovery on the operator/dev VM.
• skills/workflows/author-npa-workflow/SKILL.md: author and validate declarative npa.workflow/v0.0.1 specs (toolRef catalog, validate/plan/run CLI).
• skills/workflows/generate-npa-workflow/SKILL.md: design new creative npa.workflow pipelines from the workbench tool catalog.
• skills/workflows/diagram-to-npa-workflow/SKILL.md: turn an architecture diagram + step write-up into a working npa.workflow/v0.0.1 YAML (boxes, arrows, decision diamonds, and loop back-edges → states, loops, gates, catalog toolRefs); generalizes across sim2real, AV, RL, and Cosmos pipelines.
• skills/workflows/physical-ai-data-factory/SKILL.md: author, run, submit, or view the NVIDIA Physical AI Data Factory blueprint on Nebius + SkyPilot (no OSMO): annotate → Cosmos Transfer augment → Cosmos Evaluator gate → re-label → Cosmos Curator + FiftyOne curate → Rerun visualize. The evaluator and curator are the real Apache-2.0 NVIDIA projects, wrapped as npa workbench cosmos-evaluator and npa workbench cosmos-curate; see skills/NOTICE-NVIDIA-COSMOS-OSS for which upstream code runs where.
• skills/workflows/neural-reconstruction/SKILL.md: NuRec/NRE neural reconstruction on Nebius — NCore V4 capture (including deriving the rig → world pose edge NRE requires) → 3DGUT Gaussian training → renderable USDZ → rig-offset novel views → reports/sim2real.rrd. RT-core GPU only (L40S / RTX PRO 6000, never H100/H200).
• skills/workflows/onboard-world-model/SKILL.md: generic playbook for onboarding and containerizing a world model (learned action-conditioned simulator) as a multi-GPU BYOF registry candidate — containerize, stage a real dataset, encode the train→tokenize→dynamics→dream→visualize loop as capability smokes, and validate on real GPUs (Open Dreamer is the reference example).
• skills/atomic/real-components/SKILL.md: ensure every advertised workbench pipeline stage invokes the real component (Cosmos Transfer, FiftyOne, VLM), not an echo/manifest stub masquerading as real work.
• skills/atomic/solution-licensing/SKILL.md: when adding a solution, tool, image, model, or dataset — classify what the artifact actually bakes, decide whether it may be redistributed (public vs restricted), and record it in the packaging contract where the guards enforce it. Verify the claim against the BUILT image with npa/scripts/scan_image_omniverse_payload.py, not by reading the Dockerfile: the Isaac images were cleared that way, and two of the three problems it found were invisible in the Dockerfile.
• skills/workbench/sim2real-engine/SKILL.md: canonical 14-stage Sim2Real graph, stateless stage adapters, parallel lane joins, ComponentRecords, and durable standard-runtime resume. The preamble/inner/outer/finalize controller is finite legacy compatibility, never the canonical execution path.