// Build and dependency management for NeMo-RL. Covers Docker image building and running, uv usage, venv setup, and adding dependencies.
Autonomous NeMo-RL research agent workflow for directed hypothesis testing and open-ended discovery. Guides agents through the full experiment lifecycle: understanding recipes and environments, wiring RL or NeMo-gym runs, launching reproducible baselines and iterations, analyzing results, preserving human oversight, and using git plus TSV logs as the research ledger.
Brev instance operating guidance for NeMo-RL agents working in /home/ubuntu/RL with limited workspace disk, a larger /ephemeral volume, and optional /home/ubuntu/RL/.env secrets. Use when running auto-research campaigns, experiments, training jobs, model or dataset downloads, shared cache-heavy commands, log-producing runs, checkpoint generation, W&B or Hugging Face authenticated workflows, or any workflow that may create large files on Brev.
Manage durable working-session memory for coding agents. Use when a user asks to preserve or recover agent context across disconnects, VS Code restarts, long-running work, handoffs, or any session where important state should be written periodically under the repo's session directory.
Configuration conventions for NeMo-RL. YAML is the single source of truth for defaults. Covers TypedDict usage, exemplar YAML updates, and forbidden default patterns.
CI/CD reference for NeMo-RL. Covers GitHub Actions pipeline structure, CI triggering via /ok to test, and CI failure investigation.
Contribution conventions for NeMo-RL. Covers PR title format, commit sign-off, and CI triggering.
| name | build-and-dependency |
| description | Build and dependency management for NeMo-RL. Covers Docker image building and running, uv usage, venv setup, and adding dependencies. |
| when_to_use | Setting up a dev environment; building or running the Docker container; adding or removing a dependency; uv errors; 'how do I install', 'ModuleNotFoundError', 'build the image', 'run in Docker', 'uv sync fails'. |
Build the release image (includes all dependencies and pre-fetched venvs):
# Build from local source
docker buildx build -f docker/Dockerfile --tag nemo-rl:latest .
# Build from a specific git ref (no local clone needed)
docker buildx build -f docker/Dockerfile \
--build-arg NRL_GIT_REF=main \
--tag nemo-rl:latest \
https://github.com/NVIDIA-NeMo/RL.git
Skip optional backends to reduce build time:
# Skip vLLM and SGLang
docker buildx build -f docker/Dockerfile \
--build-arg SKIP_VLLM_BUILD=1 \
--build-arg SKIP_SGLANG_BUILD=1 \
--tag nemo-rl:latest .
See @docs/docker.md for full options.
Never use pip install directly — always go through uv.
# Run a script
uv run examples/run_grpo.py
# Run tests
uv run --group test bash tests/run_unit.sh
# Install all deps from lockfile
uv sync --locked
Exception: Dockerfile.ngc_pytorch is exempt from this rule.
# Add a runtime dependency
uv add <package>
# Add an optional dependency
uv add --optional --extra <group> <package>
# Regenerate the lockfile after changes
uv lock
Commit both pyproject.toml and uv.lock together:
git add pyproject.toml uv.lock
git commit -s -m "build: add <package> dependency"
| Problem | Cause | Fix |
|---|---|---|
uv sync --locked fails | Dependency conflict or stale lockfile | Re-run uv lock and commit updated lock |
ModuleNotFoundError after pip install | pip installed outside uv-managed venv | Use uv add + uv sync, never bare pip install |
| Docker build fails at vLLM | vLLM build time overhead | Pass --build-arg SKIP_VLLM_BUILD=1 |