Installation

The runtime model

dockyard_rl does not use uv or virtualenvs at runtime. Every runtime dependency — PyTorch, vLLM, JAX, transformers, the task executor’s toolchain — is baked into the ubuntu-swe container image’s system Python. Ray actors and runtime_env use sys.executable directly, and RAY_ENABLE_UV_RUN_RUNTIME_ENV=0 disables Ray’s implicit uv integration.

This is a deliberate constraint: a Ray runtime_env={"pip": ...} would re-create a per-actor virtualenv at runtime, which is exactly what the image is meant to eliminate. Light, fast-changing dependencies belong in a thin image layer, not in a runtime pip install.

uv is used at build time (uv.lock + uv pip install --system) to resolve and install into the image’s system Python. Build-time uv is encouraged; runtime uv is forbidden.

Building the ubuntu-swe image

The image is the unit of deployment for all three fleets. Its sources live in ubuntu-base/:

Dockerfile	Purpose
ubuntu-swe-v2.dockerfile	Default image — CUDA base, PyTorch, vLLM, JAX, and the task executor.
ubuntu-swe-sglang.dockerfile	SGLang generation backend variant.
ubuntu-swe-gdpval.dockerfile	GDPval file-producing environment variant.

Build the default image:

cd ubuntu-base
docker build -f ubuntu-swe-v2.dockerfile -t ubuntu-swe:v2 .

The Dockerfile contains in-build import jax / import vllm smoke checks. A build that fails there has a broken dependency graph — that gate is the primary way to catch dependency breakage without a cluster.

Local development

For editing, type-checking, and the CPU parity tests you only need the package itself plus a CPU stack; the heavy GPU dependencies are not required to run the unit suite or the type checker.

# From the repository root.
pip install -e .

pyproject.toml pins only the lightweight local-dev/CI dependencies (ray[default], numpy, tqdm). The rest come from the image.

Type checking

The canonical type-check runs pyright from the parent of the package directory so imports resolve as dockyard_rl.*:

cd ..            # parent of the dockyard_rl/ package directory
pyright dockyard_rl/...

Running the unit tests

The unit suite is CPU-only and skips anything that requires a GPU or a live cluster:

pytest tests/unit -q

GPU- and cluster-only behaviour is not silently skipped — it is tracked in handoff/hardware-deferred-validation.md with the exact bring-up check for each item, so validating on hardware later is “run the harness,” not “re-derive what to test.”

Environment variables

All dockyard_rl environment variables use the DOCKYARD_ prefix.

Variable	Meaning
DOCKYARD_FLEET_ROLE	trainer, inference, or sandbox. Every container must set this before init_ray(); it selects the placement strategy, resource spec, and NCCL (NVIDIA Collective Communications Library) topology.
DOCKYARD_SANDBOX_URLS	Comma-separated task-executor endpoints (alternative to setting env.code.sandbox_urls in the config).
RAY_ENABLE_UV_RUN_RUNTIME_ENV	Set to 0 — disables Ray’s uv runtime integration (see the runtime model above).

The full process environment is forwarded to every Ray worker, so image-level settings (DOCKYARD_FLEET_ROLE, NCCL_SOCKET_IFNAME, CUDA_DEVICE_ORDER, …) are visible inside remote actors without extra wiring.