nebius-physical-ai
The control plane your coding agent uses to run physical-AI workloads on Nebius.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nebius/nebius-physical-ai with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nebius/nebius-physical-ai'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/nebius--nebius-physical-ai)HTML
<a href="/listings/nebius--nebius-physical-ai"><img src="/api/listings/nebius--nebius-physical-ai/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Using a coding agent? Open this checkout in your agent and paste one of the maintained prompts:
- [Set up Workbench for a task](docs/workbench/agent-first-run.md#set-up-workbench). - [Run the Cosmos 3 generation workflow](docs/workbench/agent-first-run.md#run-cosmos-3-generation).
The prompts keep credentials private, stop at human approval gates, validate the plan before provisioning, and stay with the run through artifact inspection. The manual path below exposes the same control-plane steps.
1. Install
Use Python **3.10+** on macOS, Linux, or WSL2 Ubuntu. Clone the repository, then run the remaining commands from its root:
git clone https://github.com/nebius/nebius-physical-ai.git cd nebius-physical-ai python3 -m venv .venv source .venv/bin/activate pip install -e npa npa --version
You should see the installed `npa` version. Remote GPU workloads use their container dependencies; you do not need CUDA or a local GPU to use the CLI. [Installation](docs/install.md) covers platform setup and optional dependencies.
2. Connect your project
Install the tested Nebius CLI and configure your project:
curl -fsSL https://storage.eu-north1.nebius.cloud/cli/install.sh \
| NEBIUS_CLI_VERSION=0.12.254 bash
export PATH="${HOME}/.nebius/bin:${PATH}"
npa configure
npa workbench health preflight --checks nebius --jsonThe preflight should report working Nebius authentication. It does not reserve GPUs or verify model access. Interactive configuration provisions object storage by default and needs project admin permission for that setup. Use `npa configure --no-provision` to save settings without creating storage. See [configuration](docs/configuration.md) for SSO, existing projects, and tokens.
Check a project's saved storage with its configured alias in place of `<alias>`:
npa workbench health preflight --project '<alias>' --checks s3,nebius --json
Missing or invalid project storage fails without borrowing shell or host-file credentials or changing configuration. S3 readiness uses a bounded listing call; it does not enumerate the dataset or verify write access. Without `--project`, the S3 check keeps the existing host credential selection.
3. Run and inspect
Choose one guide below and follow it through input preparation, GPU setup, submission, and output inspection. [Workbench setup](docs/workbench/getting-started.md) provides the shared cluster and SkyPilot steps; complete them once per project. Keep the returned run ID: you use it to inspect logs, find artifacts, and resume.
For video augmentation, the [PAIDF + Cosmos 3 runbook](workflows/guides/paidf-cosmos3.md) includes a public source-video example and full submission commands.
<a id="pick-your-first-win"></a>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 359 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- # Nebius Physical AI
- **The agent control plane for Physical AI on Nebius.**
- <img src="docs/assets/workbench-architecture.png" alt="Workbench architecture: selected NVIDIA and open-ecosystem integrations are packaged into public GHCR images. npa uses workflow YAML, its workflow engine, and SkyPilot to run workloads on Nebius Kubernetes. Kubernetes pulls images; Object Storage holds artifacts and run state. Token Factory provides hosted inference. Models and vendor runtimes are fetched at runtime where required." width="960" />
- [](LICENSE)
- [](https://www.python.org/downloads/)
- [](docs/install.md)
- [](https://github.com/nebius/nebius-physical-ai/actions/workflows/test.yml)
- [](CONTRIBUTING.md)
- **[Quickstart](docs/quickstart.md)** ·
- **[Guides](docs/workbench/guides/README.md)** ·
- **[Manual workflows](docs/workbench/guides/manual-workflow-operations.md)** ·
- **[Workbench docs](docs/workbench/README.md)** ·
- **[Shared access](docs/workbench/shared-workbench-quickstart.md)** ·
- **[Benchmarks](benchmark/README.md)** ·
- **[Operator tools](docs/tools/README.md)** ·
- **[CLI reference](docs/cli/README.md)** ·
- **[Python & API](docs/workbench/cli-sdk-yaml-walkthrough.md)** ·
- **[Cookbooks](docs/workbench/cookbooks/README.md)** ·
- **[Contributing](CONTRIBUTING.md)**
- </div>
- ## Demos
- **Video augmentation · 8 seconds**
- One ALOHA recording, twelve Cosmos3 appearance variants. This batch did not pass
- its quality gate. [Workflow](workflows/main/paidf-cosmos3.yaml) ·
- [Runbook](workflows/guides/paidf-cosmos3.md) ·
- [MP4](https://github.com/user-attachments/assets/95917c76-7920-420f-af08-c13590a36a3f)
- <img src="https://github.com/user-attachments/assets/5df4f2c0-c213-4662-a892-5856e90c8269" alt="One ALOHA recording alongside twelve Cosmos3 appearance variants, looping automatically." width="640" />
- **Robot locomotion · 8 seconds**
- A Unitree G1 policy rollout in MJLab simulation.
- [Workflow](workflows/testing/mjlab-render.yaml) ·
- [MP4](https://github.com/user-attachments/assets/7e605a6d-b32b-4746-808c-51258a11b21a)
- <img src="https://github.com/user-attachments/assets/34e720b9-df15-43a6-b14d-680e01ce4ee4" alt="A Unitree G1 walking in MJLab simulation, looping automatically." width="640" />
- **Video segmentation · 6 seconds**
- SAM 2.1 follows an object through generated video.
- [Workflow](workflows/testing/byof-sam2.1.yaml) ·
- [MP4](https://github.com/user-attachments/assets/f629401a-346d-4862-b221-34b5ecc28128)
- <img src="https://github.com/user-attachments/assets/e4edfa25-ce1a-4ab9-a745-8d3680d86967" alt="SAM 2.1 tracking a generated mobile robot with a colored mask, looping automatically." width="640" />
- [Clip sources and scope](docs/demos/readme-videos.md)
- For a shared Workbench endpoint, start with the
- [shared-access quickstart](docs/workbench/shared-workbench-quickstart.md).
- Operators install the HTTPS service once; users and coding agents connect with
- `npa login` using a personal key or Nebius human sign-in. Workbench access adds
- personal namespaces, GPU caps, and scoped storage. The CLI and agents reuse
- the saved connection through the same authenticated API.
- Operators managing Kubernetes directly can use
- [team namespaces](docs/workbench/namespaces.md) to select namespaces and private
- SkyPilot contexts with `npa workbench namespace`.
- ## What is Workbench?
- Workbench is NPA's agent control plane for Physical AI on Nebius AI Cloud,
- covering infrastructure setup and management, simulation, robot policy training,
- synthetic data, and evaluation. Codex, Claude Code, or another coding agent with
- terminal access to this checkout uses repository skills and `npa` to configure
- projects, check access, provision GPU clusters and object storage, run
- containerized tools and workflows, and inspect artifacts with you. You can use
- the same operations directly through the CLI; supported tools also expose
- Python interfaces.
- ### How Workbench runs a task
- The architecture overview maps selected NVIDIA and open-ecosystem solutions to
- NPA's [public GHCR container catalog](docs/workbench/container-image-catalog.md)
- at `ghcr.io/nebius/nebius-physical-ai` and the Nebius services that run and support
- them. Some images fetch models or vendor runtimes at execution time; the
- [packaging contract](docs/workbench/container-packaging.md) records those boundaries.
- For the standard Kubernetes workflow path, the
- [workflow engine](docs/workbench/npa-workflow-guide.md#runtime-orchestrator---runtime)
- plans execution waves, submits them through SkyPilot, and uses S3 artifacts and
- durable run state to evaluate decisions and resume runs. The operator-side
- [SkyPilot environment](docs/orchestration/skypilot-setup.md) submits the jobs;
- the workload containers run on Nebius GPU or CPU nodes.
- [Token Factory](docs/workbench/token-factory.md) is a separate hosted inference
- API. Direct calls need no cluster; workflow stages can also call it from their
- containers. Individual tools additionally support the
- [runtime modes documented for that tool](docs/workbench/README.md).
- Inspect the resulting artifacts with Rerun, Foxglove, media viewers, or reports.
- You remain in the loop for choices and human-bound approvals such as accepting
- model terms. The [diagram reference](docs/assets/workbench-architecture.md)
- records the scope and source files behind the visuals.
- Start with a [workload guide](#pick-your-first-win). The guide tells you which
- data, model access, GPU, and output to expect.
- ## Quickstart
- Using a coding agent? Open this checkout in your agent and paste one of the
- maintained prompts:
- - [Set up Workbench for a task](docs/workbench/agent-first-run.md#set-up-workbench).
- - [Run the Cosmos 3 generation workflow](docs/workbench/agent-first-run.md#run-cosmos-3-generation).
- The prompts keep credentials private, stop at human approval gates, validate
- the plan before provisioning, and stay with the run through artifact inspection.
- The manual path below exposes the same control-plane steps.
- Joining an existing shared Workbench? Complete **1. Install**, then follow the
- [shared-access quickstart](docs/workbench/shared-workbench-quickstart.md).
- The project connection steps below are for operators; `npa configure` does not
- install the shared service or its LoadBalancer.
- ### 1. Install
- Use Python **3.11+** on macOS, Linux, or WSL2 Ubuntu. Clone the repository,
- then run the remaining commands from its root:
- ```bash
- git clone https://github.com/nebius/nebius-physical-ai.git
- cd nebius-physical-ai
- python3 -m venv .venv
- source .venv/bin/activate
- pip install -e npa
- npa --version
- ```
- You should see the installed `npa` version. Remote GPU workloads use their
- container dependencies; you do not need CUDA or a local GPU to use the CLI.
- [Installation](docs/install.md) covers platform setup and optional dependencies.
- ### 2. Connect your project
- Install the tested Nebius CLI and configure your project:
- ```bash
- curl -fsSL https://storage.eu-north1.nebius.cloud/cli/install.sh \
- | NEBIUS_CLI_VERSION=0.12.298 bash
- export PATH="${HOME}/.nebius/bin:${PATH}"
- npa configure
- npa workbench health preflight --checks nebius --json
- ```
- The preflight should report working Nebius authentication. It does not reserve
- GPUs or verify model access. Interactive configuration provisions object storage
- by default and needs project admin permission for that setup. Use
- `npa configure --no-provision` to save settings without creating storage.
- See [configuration](docs/configuration.md) for SSO, existing projects, and tokens.
- Check a project's saved storage with its configured alias in place of `<alias>`:
- ```bash
- npa workbench health preflight --project '<alias>' --checks s3,nebius --json
- ```
- Missing or invalid project storage fails without borrowing shell or host-file
- credentials or changing configuration. S3 readiness uses a bounded listing call;
- it does not enumerate the dataset or verify write access. Without `--project`,
- the S3 check keeps the existing host credential selection.
- ### 3. Run and inspect
- Choose one guide below and follow it through input preparation, GPU setup,
- submission, and output inspection. [Workbench setup](docs/workbench/getting-started.md)
- provides the shared cluster and SkyPilot steps; complete them once per project.
- Keep the returned run ID: you use it to inspect logs, find artifacts, and resume.
- For video augmentation, the [PAIDF + Cosmos 3 runbook](workflows/guides/paidf-cosmos3.md)
- includes a public source-video example and full submission commands.
- For a shared installation, [team PAIDF](docs/workbench/team-paidf.md) covers
- new-user sign-in, local groups, scoped allocations, and 20 LeRobot episodes
- submitted through the shared CLI or SDK.
- <a id="pick-your-first-win"></a>
- ## Choose your first workload
- | Result | Guide | Main requirement |
- | --- | --- | --- |
- | Generated images or video | [Cosmos 3 generation](docs/quickstart.md#standalone-cosmos-3-generation) | Compatible GPU and model access |
- | Augmented video with evaluation and curation reports | [PAIDF + Cosmos 3](workflows/guides/paidf-cosmos3.md) | Source video, GPU, S3, hosted inference |
- | A labeled video dataset | [Physical AI Data Factory](docs/workbench/guides/physical-ai-data-factory-deploy.md) | Source video, RT-core GPU, S3 |
- | A reconstructed 3D scene and novel views | [Neural reconstruction](docs/workbench/guides/neural-reconstruction.md) | Sensor capture and RT-core GPU |
- | A robot-policy training checkpoint | [Reachy 2 + LeRobot](docs/workbench/guides/reachy2-lerobot-policy.md) | Matching recorded dataset and GPU |
- | A Franka training and evaluation exercise | [Franka + Genesis](docs/workbench/guides/franka-pick-and-place-genesis.md) | GPU; recorded run did not solve the task |
- | Quadruped reinforcement learning | [Isaac Lab](docs/workbench/guides/quadruped-isaac-lab.md) | RT-core GPU |
- | A G1 locomotion evaluation or training path | [G1 + SONIC](docs/workbench/guides/g1-humanoid-walk-sonic.md) | Runtime-specific GPU and checkpoints |
- | A browser workbench and artifact viewer | [Deploy the agent](docs/agent.md) | Terraform, S3, SSH key, Token Factory key |
- The [guide index](docs/workbench/guides/README.md) records validation scope.
- [Cookbooks](docs/workbench/cookbooks/README.md) cover longer training and data
- pipelines. GPU names alone do not establish image compatibility; check the
- [image/GPU matrix](docs/workbench/image-gpu-compatibility-matrix.md) before provisioning.
- ## Compose it into a workflow
- A workflow is a YAML state graph: each `toolRef` selects a Workbench operation;
- outputs become inputs to later stages. SkyPilot schedules the work on Nebius.
- These commands validate and plan a checked-in example **locally**:
- ```bash
- npa workbench workflow validate-spec workflows/testing/cosmos3-generate.yaml
- npa workbench workflow plan-spec workflows/testing/cosmos3-generate.yaml --run-id demo
- ```
- Expect a valid specification and a plan containing the `generate` stage.
- The example's storage values are placeholders. Planning creates no workload and
- does not prove its inputs, credentials, image, or GPU are ready for execution.
- For a real run, follow the selected guide's `prepare-run`, image preflight,
- `submit --runtime`, and monitoring instructions with your own project and input.
- Collect executed actions across physical scene variations with the
- [physical augmentation demo](docs/workbench/guides/physical-augmentation.md):
- one launch command produces an offline interactive replay, comparison film,
- and verified action dataset from actual RTX simulation.
- See the [workflow catalog](workflows/README.md),
- [authoring guide](docs/workbench/npa-workflow-guide.md), and
- [run lifecycle](docs/run-lifecycle.md). The canonical
- [14-stage Sim2Real pipeline](docs/workbench/guides/sim2real-workflow.md) uses this
- same runtime at [`workflows/main/sim2real.yaml`](workflows/main/sim2real.yaml)
- and requires its own prepared images, task data, and resource profiles.
- Its manual runbook starts with a fresh CLI install and a qualified five-image
- release gate before provisioning; running it requires no agent deployment.
- Its [data contracts](docs/workbench/guides/sim2real-data-contracts.md) preserve
- simulator episode resets across sparse samples and exclude reset intervals from
- training credit. The older `sim2real/runbook.yaml` is a legacy path.
- Fresh stock-Franka training uses `NPA_BYO_ISAAC_BOOTSTRAP=auto` to initialize its
- learned actor from native Isaac demonstrations on the sealed training split,
- then runs the full PPO pass. Resumed checkpoints and custom robots retain their
- existing training path. Set `NPA_BYO_ISAAC_BOOTSTRAP=none` to disable the warm
- start, or use `franka-cartesian-gru-distillation-v2` to require its supported
- task boundary.
- See the [training and evaluation contract](docs/workbench/guides/sim2real-workflow.md).
- The canonical stock-Franka scenario task uses upstream task-space arm drives
- with robot gravity compensation and 200 Hz physics. Its policy still acts at
- 50 Hz. Training and held-out artifacts attest this same control profile.
- <a id="whats-in-the-box"></a>
- ## Find a tool or integration
- | Task | Reference |
- | --- | --- |
- | Discover tools by task | [Workbench docs](docs/workbench/README.md) |
- | Use FA4 in your own RTX PRO 6000 container | [RTX PRO 6000 FA4 adoption guide](docs/workbench/guides/rtx6000-fa4.md) |
- | Compare standalone FA2 and tuned FA4 | [RTX PRO 6000 measurements and actual renders](docs/workbench/fa2-fa4-validation.md) |
- | Find a command or option | [CLI index](docs/cli/README.md), then `npa workbench <tool> --help` |
- | Call a tool from Python or HTTP | [CLI / SDK walkthrough](docs/workbench/cli-sdk-yaml-walkthrough.md) — supported interfaces vary by tool |
- | Develop a native Ray application | [Ray guide](docs/workbench/ray.md) |
- | Inspect or share run outputs | [Rerun](docs/workbench/rerun-sharing.md) · [Foxglove/MCAP](docs/workbench/foxglove-export.md) |
- | Diagnose a failed run | [Troubleshooting](docs/workbench/troubleshooting/known-footguns.md) |
- ## When you're done, tear it down
- Cancel active jobs before deleting their infrastructure. Preview project cleanup:
- ```bash
- npa destroy --project "<alias>" --all
- ```
- This is read-only until you pass `--yes`. Review the listed resources and save
- needed artifacts before deleting storage. [Teardown](docs/teardown.md) covers
- service, controller, cluster, and storage cleanup. Local `npa cleanup` alone
- does not stop cloud resources.
- ## Container images
- Use the [public image catalog](docs/workbench/container-image-catalog.md) to pull
- available GHCR images. Repository-owned runtime defaults already select GHCR;
- `npa configure` needs no registry setup. Some images fetch separately licensed
- runtimes or model weights at startup, so check their access requirements too.
- For modified or private images, follow the
- [build and packaging guide](docs/workbench/container-packaging.md) and select
- the image explicitly. `NPA_REGISTRY` alone does not change runtime defaults.
- ## Validated on Nebius
- The [image/GPU matrix](docs/workbench/image-gpu-compatibility-matrix.md) records
- hardware tests and distinguishes them from expected compatibility. Each guide
- states what its run established: a working container, a generated artifact, a
- training checkpoint, or measured task performance. A smoke test is not evidence
- of policy convergence. See also the
- [LeRobot benchmarks](docs/workbench/cookbooks/lerobot-gpu-benchmarks.md) and
- [planned partner capabilities](docs/architecture/partner-skills-roadmap.md).
- ## Repository layout
- | Directory | Contents |
- | --- | --- |
- | [`npa/`](npa/README.md) | Python package, CLI, SDK, and tests |
- | [`workflows/`](workflows/README.md) | Declarative workflow catalog and runbooks |
- | [`docs/`](docs/README.md) | Setup, tool guides, cookbooks, and references |
- | [`deploy/cluster/`](deploy/cluster/README.md) | Managed Kubernetes Terraform wrapper |
- | [`skills/`](skills/index.yaml) | Operating and contribution instructions for agents |
- | [`workbench/mlflow/`](workbench/mlflow/README.md) | Local MLflow and Postgres stack |
- | [`research/`](research/lerobot-deploy/README.md) | Historical standalone deployment research |
- ## Documentation
- Use the [documentation index](docs/README.md) to find setup, operations, and
- contributor references. For workflow operations, start with
- [manual runs](docs/workbench/guides/manual-workflow-operations.md),
- [episode batches and capacity](docs/workbench/guides/paidf-dataset-batches.md), or
- [quality reports](docs/workbench/insights-reports.md).
- Report a broken example with its command, `npa` version,
- and redacted error in [GitHub Issues](https://github.com/nebius/nebius-physical-ai/issues).
- Keep credentials and private infrastructure identifiers out of issue text.
- ## Contributing
- For dedicated CI capacity, operators can set the repository Actions variables
- `NPA_CI_PRIORITY_RUNNER` and `NPA_CI_TEST_RUNNER` to approved Ubuntu runner labels.
- Both default to `ubuntu-latest`; neither reserves capacity by itself. See
- [validation concurrency](CONTRIBUTING.md#validation-concurrency) for routing and setup.
- The [temporary CPU runner guide](.github/ci-runners/README.md) covers disposable
- Nebius workers. `make ci-runners-down` restores routing and safely drains the
- configured pool; `make ci-runners-status` reports its state.
- See [CONTRIBUTING.md](CONTRIBUTING.md) for the development environment, required
- checks, and PR process. [The package README](npa/README.md#developing-and-testing-npa)
- has the shortest test commands. Update the relevant documentation and
- [root skill](skills/index.yaml) when changing behavior.
- Run `make precheck` for fast local CI checks. After committing, fetch main and run
- `make merge-precheck` to check the combined dependency inputs. The
- [merge-readiness guide](CONTRIBUTING.md#merge-readiness-and-queue-rejections)
- also explains the automatic PR comments for merge-queue rejections.
- Security disclosures: [SECURITY.md](SECURITY.md).
- ## License
- [Apache License 2.0](LICENSE). Third-party software, models, and datasets retain
- their own licenses and access terms.
- ### MJLab robot learning
- [MJLab integration](docs/workbench/mjlab.md) provides native training and resume,
- measured evaluation, ONNX export, a scoped authenticated service, and CLI/SDK
- clients. Use the [train/evaluate workflow](workflows/testing/mjlab-train-eval.yaml)
- on a Nebius GPU with an explicitly built MJLab image. Native GPU acceptance
- results are recorded in the guide; public image promotion remains gated.
- `eval --video` publishes the rendered MP4 and a self-contained HTML report with
- measured episode results and checkpoint provenance.
- The former deterministic scoring placeholder has been removed.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.