dev-MCP Docker Container¶

The dev-MCP container runs the full VMAF fork inside Docker with all four GPU backends enabled (CUDA, SYCL, Vulkan, HIP) plus the embedded MCP stdio server. It is the standard environment for:

• Live probing of VMAF scores across all backends from a single shell.
• Running the continuous smoke-probe cron (smoke-probe-cron service).
• Reproducing build regressions on GPU paths other than the host's primary GPU (for example: catching HIP toolchain regressions on an NVIDIA-only host).

The design decision is recorded in ADR-0435.

Prerequisites¶

Required¶

Optional¶

How to build¶

Use the provided wrapper from the repository root:

./dev/scripts/dev-mcp-up.sh

Or, to build without starting:

docker compose --project-directory "$(pwd)" -f dev/docker-compose.yml build

Important — always pass --project-directory. Without it, Docker Compose v2 sets the project directory to the compose-file's parent (dev/), causing context: . to resolve to dev/ instead of the repo root. This bypasses the root .dockerignore and — on developer machines that hold .corpus/ (up to 781 GB) — sends the entire corpus into the build context, accumulating copies in /var/lib/docker/overlay2/ on every failed build. The dev-mcp-up.sh wrapper always passes --project-directory; the bare docker compose -f form is unsafe unless run from the repo root with the flag explicit.

The first build downloads all GPU SDK layers and compiles libvmaf from source. Expect 20–40 minutes on a typical workstation; subsequent builds use the layer cache and take 1–3 minutes when only Python packages change.

How to start¶

# CPU + Vulkan/lavapipe only (no GPU passthrough)
./dev/scripts/dev-mcp-up.sh

# With NVIDIA GPU passthrough
NVIDIA_VISIBLE_DEVICES=all CONTAINER_RUNTIME=nvidia \
    ./dev/scripts/dev-mcp-up.sh

To ensure the container joins the correct host video and render groups (GIDs differ across distributions), export HOST_GID_VIDEO and HOST_GID_RENDER before starting. The wrapper reads them automatically; you can also pass them inline:

HOST_GID_VIDEO=$(getent group video | cut -d: -f3) \
HOST_GID_RENDER=$(getent group render | cut -d: -f3) \
CONTAINER_RUNTIME=nvidia \
docker compose -f dev/docker-compose.yml --project-directory . up -d dev-mcp

The defaults baked into docker-compose.yml (44 for video, 109 for render) match common Ubuntu installations. Override whenever getent group video returns a different GID (for example, Arch Linux uses 985/986).

The dev-mcp-up.sh wrapper builds (if needed) then starts:

1. vmaf-dev-mcp — primary container; runs vmaf-mcp via docker exec -i stdio when requested. The service healthcheck is vmaf --version, not a socket check.
2. vmaf-smoke-probe-cron — waits for the primary to be healthy, then probes every 15 minutes.

Both services write probe files to .workingdir/dev-mcp-probes/ on the host.

How to attach¶

# Interactive bash shell inside the running dev-mcp container
./dev/scripts/dev-mcp-shell.sh

# Run a specific command
./dev/scripts/dev-mcp-shell.sh vmaf-dev-mcp vmaf --version
./dev/scripts/dev-mcp-shell.sh vmaf-dev-mcp vmaf --list-features

Inside the container the full environment is initialised:

• vmaf CLI — /usr/local/bin/vmaf
• vmaf-mcp-server — /opt/vmaf-venv/bin/vmaf-mcp-server
• GPU SDKs — nvcc, icpx, hipcc in PATH
• testdata — /workspace/testdata/ (read-only bind mount from host repo)
• models — /workspace/model/ (read-only)

How to manually probe¶

Run a single smoke probe outside the cron cycle:

./dev/scripts/dev-mcp-probe.sh

This executes smoke-probe-loop.sh --once inside the running container and writes probe-<timestamp>.json to .workingdir/dev-mcp-probes/. If jq is installed on the host the result is pretty-printed to stdout.

How to stop¶

# Stop, keep volumes (probe history preserved)
./dev/scripts/dev-mcp-down.sh

# Stop and remove volumes (clears socket volume; probe bind-mount preserved)
./dev/scripts/dev-mcp-down.sh --volumes

How to interpret probe outputs¶

Each probe file follows this schema:

{
  "ts": "2026-05-15T14:30:00Z",
  "host_id": "myhostname:abc123def456",
  "backend_results": {
    "cpu":    { "score": 76.45, "duration_ms": 3200, "error": null },
    "cuda":   { "score": 76.44, "duration_ms":  820, "error": null },
    "sycl":   { "score": null,  "duration_ms":    0, "error": "ENOSYS: no SYCL device" },
    "vulkan": { "score": 76.45, "duration_ms": 1100, "error": null }
  },
  "mcp_results": {
    "list_features": { "feature_count": 14, "duration_ms": 45, "error": null },
    "compute_vmaf":  { "score": 76.45, "duration_ms": 3250, "error": null }
  }
}

Expected values¶

• CPU score: ~76.45 (matches the Netflix golden pair; exact value varies by model version).
• CUDA / Vulkan scores: within ±0.01 of CPU (numeric parity is not bit-exact — see ADR-0214).
• SYCL: ENOSYS on hosts without Intel GPU or oneAPI runtime; normal.
• HIP: error on NVIDIA-only hosts; normal.

Common error patterns¶

Known limitations¶

Backend matrix (post-ADR-0514)¶

On a host with NVIDIA + Intel Arc + AMD silicon and the NVIDIA Container Toolkit installed, every libvmaf backend should run inside the container:

Reproducer:

docker exec vmaf-dev-mcp bash -c '
  for B in cpu cuda sycl vulkan hip; do
    vmaf --reference /workspace/python/test/resource/yuv/src01_hrc00_576x324.yuv \
         --distorted /workspace/python/test/resource/yuv/src01_hrc01_576x324.yuv \
         --width 576 --height 324 --pixel_format 420 --bitdepth 8 \
         --backend $B --json --output /tmp/probe_$B.json
    echo "rc=$? backend=$B"
  done
'

Environment-variable contract¶

The container pins one env-var family (HSA / ROCm) at compose-up time, rewrites one (VK_DRIVER_FILES) at entrypoint time based on what is visible on disk, and intentionally leaves everything else alone. Pinning the wrong subset silently hid one or more GPU backends in earlier image versions:

Operators that need to force a single Vulkan ICD per invocation can still docker exec vmaf-dev-mcp env VK_DRIVER_FILES=/path/to/icd.json vmaf … — the per-exec env var overrides the entrypoint-time pin. Operators on hosts with a ROCm-supported GPU on the allowlist (gfx1030 / gfx1100 / gfx1101 desktop / workstation parts) can override HSA_OVERRIDE_GFX_VERSION to the empty string at docker compose up time to remove the lie.

FFmpeg encoder matrix (post-ADR-0543)¶

The in-image FFmpeg is built with the fork's full encoder set so that vmaf-tune compare sweeps can address every codec the project supports without skipping rows with hardware encoder not available: ... not compiled into ffmpeg. The matrix:

To verify the in-image listing after a rebuild:

docker exec vmaf-dev-mcp ffmpeg -hide_banner -encoders 2>&1 \
    | grep -E "libsvtav1|libvvenc|libvpx-vp9|nvenc|qsv|amf|vpl" \
    | head -20

Expected (assuming the build-time encoder probe in stage 3.5 logged no WARN ... missing):

 V....D libsvtav1            SVT-AV1(Scalable Video Technology for AV1) encoder
 V..... libvvenc             libvvenc-based VVC encoder
 V....D libvpx-vp9           libvpx VP9
 V....D h264_nvenc           NVIDIA NVENC H.264 encoder
 V....D hevc_nvenc           NVIDIA NVENC hevc encoder
 V....D av1_nvenc            NVIDIA NVENC av1 encoder
 V....D h264_qsv             H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10 (Intel Quick Sync Video acceleration)
 V....D hevc_qsv             HEVC (Intel Quick Sync Video acceleration)
 V....D av1_qsv              AV1 (Intel Quick Sync Video acceleration)
 V....D h264_amf             AMD AMF H.264 Encoder
 V....D hevc_amf             AMD AMF HEVC encoder
 V....D av1_amf              AMD AMF AV1 encoder

Hardware-encoder runtime failure modes¶

The encoders above are split into "compile-in" (does the binary advertise the encoder?) and "runtime-ok" (does a 1-frame dummy encode succeed?). vmaf-tune compare's compare.py::probe_encoder_available runs both stages. The container locks down the compile-in promise; runtime failures produce stable row-level skip strings:

Reproducer — full cross-codec compare sweep¶

docker exec vmaf-dev-mcp bash -c '
  cd /workspace && PYTHONPATH=/workspace/tools/vmaf-tune/src:$PYTHONPATH \
  python -c "from vmaftune.cli import main; raise SystemExit(main())" compare \
    --src /workspace/.corpus/bbb_e2e/bbb_sunflower_1080p_60fps_normal.mp4 \
    --width 1920 --height 1080 --framerate 60 \
    --target-vmafs 85,90,92,95 \
    --encoders libx264,libx265,libsvtav1,libaom-av1,libvvenc,libvpx-vp9,h264_nvenc,hevc_nvenc,av1_nvenc,h264_qsv,hevc_qsv,av1_qsv,h264_amf,hevc_amf,av1_amf \
    --duration 5 --sample-clip-seconds 3 --max-iterations 3 \
    --score-backend cuda --format json --output /tmp/v11_1080p_cmp_full.json'

Encoders that are not runtime-available on the host produce per-row ok=false entries with the diagnostic strings above; the sweep does not abort.

Host-kernel ↔ container-userspace UAPI version pins (ADR-0543)¶

Intel NEO compute-runtime and ROCm KFD userspace are version-pinned via Containerfile ARGs to match the host kernel's i915 / xe / KFD ioctl ABI. A mismatch silently degrades vmaf --backend sycl|hip to CPU.

dev-mcp-entrypoint.sh emits a runtime visibility probe on container start (ADR-0543): WARN: SYCL level_zero:gpu NOT detected or WARN: HIP HSA agent NOT detected means the host kernel has revved past the pinned userspace ABI — bump the ARG and rebuild rather than working around the fallback (CLAUDE.md §12 r15 sub-rule 4). The latest NEO release tag is at https://github.com/intel/compute-runtime/releases/latest; the latest ROCm noble channel is listed under https://repo.radeon.com/rocm/apt/.