environments

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 uv vs venv vs Docker, and, once Docker is chosen, how to get GPU passthrough 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 yet; this is a required early step, not an optional one.
• The trigger phrases in the description: 'uv', 'venv', 'virtualenv', 'docker for this project', 'reproducible environment', 'GPU in container'.
• Debugging "works on my machine but not on the server": almost always an environment-parity bug, not an application bug.
• Cross-references: go to the sibling skill instead when the question is:
  • 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, alongside the GPU-cloud/RunPod one this skill owns): the build → deploy 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 flags) live in this skill and its references; this is a foundational, every-build concern, not a thin pointer to someone else's docs.
• Environment 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. Run npx robium-ai doctor --json (the robium CLI, npm package robium-ai) at the start of an environment decision and read the report (platform/Apple Silicon, Docker daemon state, GPU, free disk, python3/uv) instead of re-deriving those facts with ad-hoc 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. 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 disposable; see references/uv-patterns.md.
• Every project states its env strategy in the architecture 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 moving on; don't let it live only in your head or in a Dockerfile no one reads.
• Local == remote is the 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 you can't state that, the strategy isn't finished; see the parity checklist in references/docker-patterns.md.
• Never write image tags or version numbers from memory. Verify current uv usage against docs.astral.sh/uv, current ROS 2 image tags against hub.docker.com/_/ros, and NVIDIA Container Toolkit steps against docs.nvidia.com before committing them to a real project. Every example in this skill is marked status: unverified for exactly this reason; treat it as a starting shape to re-check, not a pinned truth.