v1.7.0 to v1.7.1

---

name: environments

description: >

Virtual-environment-first setup for robotics projects: decide uv/venv vs Docker,

make local and remote-server runs reproduce identically, handle GPU passthrough

and headless/display forwarding. Use when: setting up any new robotics project

environment; 'uv', 'venv', 'virtualenv', 'docker for this project', 'reproducible

environment', 'works locally but not on the server', 'GPU in container'. Load

early in any robium build, right after architect. Decision rule of thumb:

pure-Python ML stacks → uv; anything needing ROS 2 or system deps → Docker. Not

for: multi-module application Dockerfiles and compose wiring (integration skill).

---

# environments

The environment-strategy umbrella for robium. Every robium build needs an answer

to "how does this run, identically, on my laptop and on whatever server it ends

up on" before the first line of application code is written. This skill decides

and remote/headless display right. It does not own multi-module application

Dockerfiles or compose wiring across nodes; that's `integration`.

## When to use this skill

- Starting any new robotics project and the environment strategy isn't decided

- The trigger phrases in the description: 'uv', 'venv', 'virtualenv', 'docker

for this project', 'reproducible environment', 'GPU in container'.

environment-parity bug, not an application bug.

- Wiring multiple app modules together, Dockerfiles for a multi-node app, or

compose files spanning services → `integration` (this skill covers a

*single* environment's shape; `integration` covers the app that runs in it).

- Remote visualization once headless is decided → `foxglove`.

- ROS 2-specific package/build questions once Docker + ROS 2 is chosen →

`ros2`.

- Picking a manipulation/training framework once the env is settled →

`lerobot`.

- Deploying a headless container to Google Cloud Run (the CPU deploy target,

path and the sim-on-Cloud-Run gotchas → `cloud-run`.

- The whole-stack decision this feeds into → `architect` (load that first if

you haven't; it routes here).

## Key directives

- **Delegation posture: embed.** The decision logic (uv vs venv vs Docker) and

the concrete patterns (pyproject.toml shape, Dockerfile shape, GPU/display

every-build concern, not a thin pointer to someone else's docs.

- **Environment before code.** <!-- id: env-before-code --> Decide and record the environment strategy

before writing application code. An undecided environment is an open risk,

not a detail to fix later.

- **Preflight the machine before deciding.** <!-- id: preflight-with-doctor --> Run `npx robium-ai doctor --json`

(the robium CLI, npm package robium-ai) at the start of an environment

shell probes. `npx robium-ai doctor` is the human-readable variant. If npx

is unavailable, fall back to probing manually; the decision logic below is

unchanged either way.

- **Never `pip install` into the system Python.** <!-- id: never-pip-install-system-python --> Not on the host, not inside

a container's base image. Every install goes into a project-scoped uv

environment (`uv sync`, `uv run`) or, inside Docker, a venv managed the same

way. The only sanctioned exception is a deliberate, explicit `--system`

flag (or `UV_SYSTEM_PYTHON=1`) inside a container build stage that is itself

- **Every project states its env strategy in the architecture brief.** <!-- id: record-strategy-in-brief --> If

you're routed here from `architect`, write the choice (uv / venv / Docker,

and why) into `docs/architecture-brief.md`'s env-strategy section before

reads.

- **Local == remote is the acceptance test.** <!-- id: local-remote-parity-acceptance-test --> An environment strategy isn't

done until you can state, concretely, why the same commands produce the

same result on a laptop and on a headless remote server (same base image

digest or lockfile, same Python/CUDA versions, no host-only assumptions). If

checklist in `references/docker-patterns.md`.

- **Never write image tags or version numbers from memory.** <!-- id: never-write-versions-from-memory --> Verify current

uv usage against [docs.astral.sh/uv](https://docs.astral.sh/uv/), current

ROS 2 image tags against

[hub.docker.com/_/ros](https://hub.docker.com/_/ros), and NVIDIA Container

Toolkit steps against

[docs.nvidia.com](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/)

before committing them to a real project. Every example in this skill is

starting shape to re-check, not a pinned truth.

## Quick start

**1. Answer one question: does this project need ROS 2 or other system-level

dependencies (apt packages, native libs, a specific OS)?**

use **uv**. `uv init`, define dependencies in `pyproject.toml`, commit

`uv.lock`, run everything through `uv run`. See

`references/uv-patterns.md` and `examples/pyproject-uv.toml`.

use **Docker**, built on an official ROS 2 image, with uv installed inside

for any pure-Python pieces of the workspace. See

`references/docker-patterns.md` and `examples/Dockerfile.ros2`.

still Docker, but run uv *inside* the container for the Python side rather

than fighting the container's system Python. See

`references/docker-patterns.md`.

**2. If Docker, and the project needs a GPU (training, Isaac Sim, CUDA

inference):** confirm `nvidia-container-toolkit` is installed on the host

(Linux only), and run with `docker run --gpus all …`. See

`references/gpu-and-remote.md` and `examples/Dockerfile.gpu-ml`.

**3. If the project runs on a headless/remote server:** don't reach for X11

works over SSH/remote with no display). Reserve X11/Wayland forwarding for

local-Linux-only, single-user cases. See `references/gpu-and-remote.md`.

**4. Record the decision.** Write the chosen strategy (and why) into

`docs/architecture-brief.md`'s environment-strategy section.

## Decision guidance

```

Does the project need ROS 2, system apt packages, or a specific OS?

│

├─ No → pure-Python stack

│ └─ uv

│ - `uv init`, pyproject.toml + uv.lock (commit the lock file)

│ - `uv venv` only if you need a venv without full project management

│ - See references/uv-patterns.md

│

├─ Yes, and it's ROS 2 / system deps only → Docker

│ └─ Base on an official ROS 2 image (hub.docker.com/_/ros); add a project

│ venv with uv inside only if there's Python glue code beyond ROS 2 nodes.

│ See references/docker-patterns.md, examples/Dockerfile.ros2.

│

└─ Yes, mixed: ROS 2/system deps AND a heavy pure-Python ML stack → Docker

└─ Docker for the system layer, uv for the Python layer *inside* the

container (multi-stage build: uv resolves deps in a builder stage, the

runtime stage copies the resulting venv). Do not `pip install` into

the container's system Python even though you're already in Docker.

See references/docker-patterns.md, examples/Dockerfile.gpu-ml.

```

**Local vs remote parity checklist** (the acceptance test from Key

- [ ] <!-- id: pinned-base-image-not-latest --> Base image is pinned to a specific tag (and ideally digest), not

- [ ] <!-- id: lockfile-single-source-of-truth --> `uv.lock` (or the container image itself) is the single source of

as a workaround anywhere.

- [ ] GPU projects: the CUDA version baked into the image matches what the

assume the dev laptop's CUDA matches the server's.

- [ ] No hardcoded local paths, display assumptions, or "run this manual step

first" instructions that only work on one machine.

- [ ] The same `docker run` / `uv run` invocation (modulo GPU flags) is

documented for both local and remote use.

- [ ] <!-- id: clean-room-cache-caveat --> "Clean-room" claims name what was actually cold: `docker compose down

--rmi local` removes the image but NOT the buildx layer cache, so a

not that a cold host (fresh apt downloads) reproduces it. A truly cold

check additionally needs `docker builder prune`. Verified 2026-07-11

(nav-trial).

## Platform gotchas

- **macOS has no native ROS 2.** <!-- id: macos-no-native-ros2-docker-required --> There is no supported native ROS 2 install

straight to Docker, even for local development. Don't try to install ROS 2

natively on macOS as a shortcut. If plain Docker Desktop performance or

networking is a problem, Lima (a lightweight Linux VM manager for macOS)

is a solid alternative for running Docker/containers, and falling back to

a Linux machine (local or remote) is always an option too.

- **GPU containers need `nvidia-container-toolkit`, and it's Linux-only.** <!-- id: gpu-toolkit-linux-only -->

GPU passthrough into Docker (`--gpus all`) requires the NVIDIA Container

Toolkit installed on the *host*, and NVIDIA's own install guide covers

first-party Windows/macOS host path. A remote Linux GPU server is the

reliable target for GPU workloads; a local macOS dev machine cannot run

GPU containers at all. See `references/gpu-and-remote.md`.

- **arm64 slim images need a compiler for source-only wheels.** <!-- id: arm64-slim-needs-build-essential --> On

linux/arm64 a `python:3.x-slim` base fails at install time for any dependency

`error: command 'gcc' failed: No such file or directory`. Seen with pymunk

(pulled by `lerobot[pusht]`), which has no arm64 wheel on any version. Fix:

`apt-get install -y build-essential` before the pip/uv install (or use a

non-slim base). (observed 2026-07-15, manip-trial)

latency decision, not a preference.** <!-- id: docker-macos-no-mps-cpu-fallback --> Docker containers on macOS run in a

Linux VM with no Metal/MPS passthrough, so any policy inference inside a

CPU-only regardless of host. Measured on SmolVLA: 0.55s/forward pass on

roughly 17x. For an ML policy on Apple Silicon, the number that decides

"can I containerize this" is CPU inference latency, not whether Docker

itself works (seen 2x: manip-trial, vla-trial).

- **X11/Wayland forwarding vs headless + web viz.** <!-- id: x11-forwarding-breaks-remote-headless-default --> Forwarding a display out

of a container (X11 sockets, `DISPLAY` env, `xhost`) works for local-Linux

development but breaks down over SSH to a remote server and doesn't work

from macOS/Windows hosts without extra tooling. For anything remote or

cross-platform, default to headless containers plus web-based

display forwarding.

services.** <!-- id: mac-network-service-order-robot-lan --> macOS ranks a wired (USB-Ethernet) service above Wi-Fi, so when

you cable a Mac into a robot's private router (common for a real-robot bring

-up), the default route goes down that dead-end LAN and the browser goes

though the robot WebSocket rides the LAN. Fix: System Settings → Network →

⋯ → Set Service Order → drag Wi-Fi above the USB LAN. The directly-connected

robot subnet still routes out the cable regardless of default-route order.

Verified 2026-07-24 (tb4-teleop).

or lockfile matters.** <!-- id: real-robot-networking-own-layer --> IPv6 link-local first contact, netplan Wi-Fi

reconfig, why the ROS↔browser bridge must run on the robot (DDS multicast

crosses neither NAT nor Docker Desktop's VM), two-DHCP-servers-per-SSID,

Wi-Fi MAC randomization, and validating a camera panel on a Mac with no

exception to local==remote.** <!-- id: no-macos-path-for-some-gpu-apps --> Isaac Sim / Isaac Lab (Omniverse Kit needs

NVIDIA RTX+CUDA on Linux/Windows), GR00T, and heavy-CUDA training have no

macOS path and Docker can't pass through a nonexistent Mac GPU: the Mac is

a thin SSH/browser client and the work runs on a cloud GPU. Provider and

the sharp RunPod networking edges (silently-dead HTTP proxy, no SSH `-L`,

ports fixed at pod creation, GCP's global-quota auto-deny) are in

`references/gpu-cloud.md` (go2-locomotion, 2026-07-28).

with ground truth before terminating.** <!-- id: runpod-verify-before-terminating -->

A cold pull of a large (10-20GB) image plus per-attempt proxy-exec

round-trips (15-20s each) look identical to a hung container from

console message ("Jupyter Lab... taking longer than expected") just

means nothing is listening on 8888 yet, not that the container is

terminating or recreating a pod on a hang guess; a wrong guess costs

a real pod plus a full re-pull. See `references/gpu-cloud.md` for

the fuller RunPod networking picture (provider choice, proxy

quirks, GCP quota gotchas).

## Customization

<version>` for uv projects, or the base image tag for Docker (e.g. the

on whatever the environment happens to have.

- **Different ROS 2 distro:** swap the base image tag in

`examples/Dockerfile.ros2` (e.g. `jazzy` ↔ `lyrical`); re-verify the tag

see `architect`'s Platform gotchas for the current distro

recommendation (Lyrical Luth generally; Jazzy Jalisco for the Nav2

vertical).

- **Different GPU / CUDA version:** swap the `nvidia/cuda` base tag in

`examples/Dockerfile.gpu-ml` to match the target host's driver-supported

- **Adding system packages to a uv-only project:** that's the signal to

graduate from uv to Docker, not to reach for `pip install --system` or

Exception (verified 2026-07-12, manip-trial): a single trivial host

package (e.g. `ffmpeg` for dataset video decode) on a macOS ML project,

project README and stay on uv.

## References

lockfiles, dependency groups, and when to graduate to Docker.

official ROS 2 image tags and variants, local/remote parity mechanics.

all`, headless/remote display strategy and the handoff to `foxglove`.

IPv6 link-local first contact, IPv4-alias fallback, netplan Wi-Fi reconfig,

DDS-vs-NAT, bridge-on-robot, DHCP/MAC gotchas, Mac camera-panel validation.

exception): RunPod-first provider choice, RunPod networking edges, GCP GPU

quota gotchas. Robium's owner for the cross-cutting GPU-cloud/RunPod facts.

unverified).

Python-glue layer (status: unverified).

training/inference container (status: unverified).

- Upstream: [uv docs](https://docs.astral.sh/uv/), [uv + Docker

guide](https://docs.astral.sh/uv/guides/integration/docker/), [official ROS

2 images](https://hub.docker.com/_/ros), [NVIDIA Container Toolkit

docs](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/).

Sibling skills: `architect` (routes here early), `integration`

(remote/headless visualization), `cloud-run` (the CPU Cloud Run deploy

## Changelog

<!-- One dated line per battle-tested change, added by skill-author hardening sessions. -->

- 1.7.0 (2026-08-02): add Platform gotchas [reasons: obs-environments-001] (applied by apply_deltas)

- 1.6.1 (2026-08-01): anchor IDs added to claim-bearing items (learning-engine Phase 1); no content changes.

the CPU Cloud Run deploy target, sibling to the GPU-cloud/RunPod facts this

skill owns (When to use + References sibling list).

`references/robot-networking.md` (tb4-teleop real-robot bring-up: IPv6

link-local, netplan Wi-Fi, DDS-vs-NAT, bridge-on-robot, DHCP/MAC gotchas,

Mac camera-panel validation) and `references/gpu-cloud.md` (go2-locomotion:

cloud-GPU as the one local==remote exception, RunPod-first provider choice

pointer bullet for each. environments now owns the cross-cutting

GPU-cloud/RunPod networking facts.

macOS network-service-order gotcha: a Mac cabled to a no-internet robot LAN

routes its default (internet) down the dead-end LAN unless Wi-Fi is ordered

above the USB LAN.

- 1.3.0 (2026-07-18): Key directives gains the machine-preflight bullet:

run `npx robium-ai doctor --json` (robium CLI 0.1.0, shipped 2026-07-18)

before the env decision instead of ad-hoc shell probes.

quantified Docker-macOS-MPS latency gotcha (0.55s MPS vs ~9s CPU, ~17x),

generalizing the manip-trial exception into an ML/VLA containerization

decision rule (seen 2x).

rule gains the macOS/MPS exception (one trivial host dep, e.g. ffmpeg,

doesn't justify losing the accelerator to Docker).

buildx-cache caveat (`down --rmi local` ≠ cold rebuild; add `docker

builder prune` for a true cold check). Dockerfile.ros2 shape exercised

successfully via adaptation in a real arm64 build (not verbatim, so the

example stays unverified).