Environments
Define the runtime contract before writing around machine-specific accidents.
Local and remote runs should differ only where the hardware genuinely differs.
Choose the smallest sufficient boundary
- uv: pure-Python robotics, ML, data, and tooling without required system
packages. Commit the lockfile and run project commands through
uv run.
- Docker: ROS 2, native libraries, apt packages, an exact Linux userspace,
or deployment as a container.
- Docker plus uv: use Docker for the system layer and a project environment
for substantial Python dependencies; do not turn the image's system Python
into an untracked package set.
- Remote GPU host: use when the workload has no viable local hardware path.
Record this as a deliberate exception to local/remote symmetry.
Preflight the actual machine before deciding. Confirm architecture, OS, Docker
daemon, accelerator, driver, disk, and available Python tooling. Use the Robium
doctor if present; fall back to direct probes when it is not.
Keep the contract reproducible
- Pin Python and dependency resolution with a lockfile, or pin the container
base and build inputs. Avoid
latest for reproducible applications.
- Keep dependency declarations in one source of truth; do not preserve manual
installation steps as hidden prerequisites.
- Match container CUDA/runtime requirements to the target host driver rather
than the developer laptop.
- Design remote work as headless first. Use web visualization instead of making
X forwarding part of the normal workflow.
- Test the same entry command in the target environment and prove important
hardware, file, device, network, and display assumptions.
- Before claiming first-run reproducibility, run the complete setup from a
clean project copy with the relevant package, model, and asset caches empty.
A warm development checkout can hide broken fetch and bootstrap behavior.
Go deeper only when needed
- Pure Python and lockfiles: uv patterns.
- ROS/system images, build layout, and parity: Docker patterns.
- NVIDIA passthrough and headless operation: GPU and remote.
- Real-robot LAN, Wi-Fi, DDS/NAT, and Mac host issues: robot networking.
- Workloads that can exist only on cloud GPUs: GPU cloud,
then the relevant provider skill for provisioning.
- macOS, Apple Silicon, arm64, and cold-build evidence: platform notes.
- Use the bundled examples only as starting shapes; verify all tags and install
steps against current upstream documentation.
Cross into integration when multiple modules, containers, or transports must
be wired together. Cross into a deployment skill only after the image and
runtime contract work locally or in an equivalent target environment.
Done
- A fresh machine can reproduce the environment from committed inputs.
- The same documented command starts the workload locally and remotely, except
for named hardware flags.
- GPU, devices, network, files, and display behavior are verified on the target.
- Current details match official uv,
Docker, ROS image, and
NVIDIA Container Toolkit
documentation.
1---2name: environments3description: Set up reproducible robotics environments with uv, Docker, or GPU hosts.4metadata:5 source: https://skillmd.com/skills/robium-ai/environments6---78# Environments910Define the runtime contract before writing around machine-specific accidents.11Local and remote runs should differ only where the hardware genuinely differs.1213## Choose the smallest sufficient boundary1415- **uv:** pure-Python robotics, ML, data, and tooling without required system16 packages. Commit the lockfile and run project commands through `uv run`.17- **Docker:** ROS 2, native libraries, apt packages, an exact Linux userspace,18 or deployment as a container.19- **Docker plus uv:** use Docker for the system layer and a project environment20 for substantial Python dependencies; do not turn the image's system Python21 into an untracked package set.22- **Remote GPU host:** use when the workload has no viable local hardware path.23 Record this as a deliberate exception to local/remote symmetry.2425Preflight the actual machine before deciding. Confirm architecture, OS, Docker26daemon, accelerator, driver, disk, and available Python tooling. Use the Robium27doctor if present; fall back to direct probes when it is not.2829## Keep the contract reproducible3031- Pin Python and dependency resolution with a lockfile, or pin the container32 base and build inputs. Avoid `latest` for reproducible applications.33- Keep dependency declarations in one source of truth; do not preserve manual34 installation steps as hidden prerequisites.35- Match container CUDA/runtime requirements to the target host driver rather36 than the developer laptop.37- Design remote work as headless first. Use web visualization instead of making38 X forwarding part of the normal workflow.39- Test the same entry command in the target environment and prove important40 hardware, file, device, network, and display assumptions.41- Before claiming first-run reproducibility, run the complete setup from a42 clean project copy with the relevant package, model, and asset caches empty.43 A warm development checkout can hide broken fetch and bootstrap behavior.4445## Go deeper only when needed4647- Pure Python and lockfiles: [uv patterns](references/uv-patterns.md).48- ROS/system images, build layout, and parity: [Docker patterns](references/docker-patterns.md).49- NVIDIA passthrough and headless operation: [GPU and remote](references/gpu-and-remote.md).50- Real-robot LAN, Wi-Fi, DDS/NAT, and Mac host issues: [robot networking](references/robot-networking.md).51- Workloads that can exist only on cloud GPUs: [GPU cloud](references/gpu-cloud.md),52 then the relevant provider skill for provisioning.53- macOS, Apple Silicon, arm64, and cold-build evidence: [platform notes](PLATFORM-NOTES.md).54- Use the bundled examples only as starting shapes; verify all tags and install55 steps against current upstream documentation.5657Cross into `integration` when multiple modules, containers, or transports must58be wired together. Cross into a deployment skill only after the image and59runtime contract work locally or in an equivalent target environment.6061## Done6263- A fresh machine can reproduce the environment from committed inputs.64- The same documented command starts the workload locally and remotely, except65 for named hardware flags.66- GPU, devices, network, files, and display behavior are verified on the target.67- Current details match official [uv](https://docs.astral.sh/uv/),68 [Docker](https://docs.docker.com/), ROS image, and69 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/)70 documentation.