ANTfrastructure documentation

Multi-stage Linux container images for GPU development stacks, a slim nginx webserver, and a Windows build image.

• Multi-stage Linux images for reproducible caching

• Windows toolchain container for CI and local builds

• Optional media and Android layers for specialized workloads

Choose the guide that matches the task you want to do — or start from the documentation index, which maps every topic to the page that owns it.

Documentation Index

Topic to owning document, for this repo and every project that consumes it. Start here.

Documentation index — who owns which topic

Common Failure Modes

Symptom, cause and fix for every failure hit live on the Linux and Windows lanes.

Common failure modes — symptom lookup

Adopting In A New Project

Wiring a new project to this repo: submodule, module resolver, container builds, CI actions.

Adopting ANTfrastructure in a New Project

Project Overview

Published images, repository image chain, and a feature snapshot.

Project Overview

Linux Build Basics

Local runs, multi-arch builds, and sequential nerdctl builds.

Linux Build Basics

Linux Cross Builds

Additive cross-compiler lane, SDK rootfs artifacts, runtime artifacts, and manifest publishing.

Linux Cross Builds

Linux Accelerator Images

NVIDIA, AMD, and Torch variants on top of the standard Linux image chain.

Linux Accelerator Images

Hailo Support

Plan for bringing the Hailo runtime, Python bindings, and GStreamer element into the Linux image chain.

Hailo support — image-chain integration plan

Linux Host Setup

GPU drivers, CUDA, container runtime config, performance mode, and boot recovery on the host.

Linux Host Setup (GPU, drivers, runtime, boot)

Windows Build Image

What is installed, the build commands, the patch policy, and the smoke gate.

Windows Build Image

Windows Build Lanes

BuildKit and nerdctl: which to use, isolation policy, preflight gates, and the removed classic docker lane.

Windows build lanes — BuildKit, nerdctl and classic docker

Windows Build Invariants

48 load-bearing rules, each with the incident that produced it. Read before editing windows/.

Windows build invariants (do not regress)

Windows Host Setup

Ordered bring-up for a brand-new Windows host, host gates included.

Fresh Windows Host Bring-Up (BK lane + repo gates)

Runtime Services and Streaming

Webserver, display forwarding, Raspberry Pi camera notes, and WebRTC signalling and streaming.

Runtime Services and Streaming

Project Information

Prerequisites, installation, tests, roadmap, troubleshooting, contribution, contact, and references.

Project Information

Third-Party Licences

Every bundled component, what its licence obliges this project to do, and the corresponding source for the copyleft ones.

Third-Party Software & Licenses

Linux image flow

The Linux container stack is intentionally split into reusable stages so BuildKit can cache stable layers and rebuild only the slice you changed.

For the full image chain, see Project Overview. For local and multi-arch build commands, see Linux Build Basics.

Common development targets:

nerdctl build -f linux/Dockerfile.base -t local/kataglyphis:base .
nerdctl build -f linux/Dockerfile.toolchain -t local/kataglyphis:compiler .
nerdctl build -f linux/Dockerfile.sdk -t local/kataglyphis:sdk .
nerdctl build -f linux/Dockerfile.media -t local/kataglyphis:media .
nerdctl build -f linux/Dockerfile.android -t local/kataglyphis:android .
nerdctl build -f linux/Dockerfile.torch -t local/kataglyphis:latest .

Start here:

• Documentation index — who owns which topic
• Common failure modes — symptom lookup
• Adopting ANTfrastructure in a New Project
• Project Overview
• ONNX Runtime has one source: the chain

Linux:

• Linux Build Basics
  • Image Hierarchy
  • Build Flow
  • Rootless Build Networking (host tuning)
  • Caching Layers (what is cached where)
  • Build
  • Optional Ubuntu Apt Mirror Workaround
  • Multi-Arch Build
  • Consumer bash libraries (linux/scripts/lib/)
• Linux Cross Builds
  • Cross-Compiler builder (nerdctl, amd64 host; amd64/arm64/riscv64 targets)
  • Recommended: digest-pinned orchestrator (build-cross-chain.sh)
  • The command reference AGENTS.md used to carry
  • Manual staged build (low-level reference)
  • SDK rootfs artifacts (first host-side build step)
  • Cross packaging to multi-arch manifest
  • Centralized Version Management
  • Five Critical Fixes To Maintain
  • Cross env contract
  • Runtime lane helper commands
  • The app the wrapper builds
  • Orchestrator stage selection
  • The Android ABI is a target, not the build host
• Artifact-copy completeness
  • The failure class
  • The gate
  • Adding a component that ships in the runtime image
  • Per-arch empty artifacts
  • Scope: the COPY boundary only
  • Bootstrapping Flutter in the package stage
  • The shipped trees must carry the image’s own arch
  • The end-to-end backstop
  • Guards
  • The membership test must not shell out
• The foreign-arch Vulkan SDK is built, not downloaded
  • What the target build produces, and why it used to produce almost nothing
  • Failures here are non-fatal on purpose
  • The host build must not inherit the cross pkg-config path
  • The target needs its own dev packages
  • The loader carries the window systems
  • Building on a native arm64 host
  • amd64 is the reference: all three arches build the same set
  • VK4: the components the vendor builds and we did not
  • The DXC prune mirrors the vendor’s own
  • Upstream patches: recheck on every SDK bump
  • Components that need a host tool
  • VK_LAYER_PATH pointed at a directory that has never existed
  • The toolset floor only ratchets up
  • The source tree does not ship
• What :latest promises its consumers
  • The contract
  • How the gate proves it
  • Per-arch exemptions
  • The Android SDK roots are advertised
  • Two things worth knowing before you configure a lane
  • What changes with the image after CON11
  • The Android SDK roots are advertised
  • Every LLVM tool is the pinned release
  • What the image stages so a run does not
  • The Windows image ships lavapipe
  • The ort crate links the chain ONNX Runtime
  • Browser tests run in Chrome for Testing
  • The Android emulator runs on amd64 with KVM
  • DeepStream in :latest-nvidia
• Image decisions and closed checks
  • Checked 2026-09-25 and closed — the consumer notes are stale
  • Checked 2026-10-01 and closed — CON45’s claims hold in the published :winamd64
  • Deliberate — not gaps
• GEN1 — onnxruntime-genai on riscv64
  • Status: VALIDATED (2026-09-03)
  • The lane at a glance
  • Why the rest of the cross path needed no change
  • The upstream patch: cmake/target_platform.cmake
  • --use_guidance on riscv64
  • The cross-wheel gate in the producer
  • The escape hatch: GENAI_ALLOW_RISCV64
  • The smoke: smoke_genai_py
  • Two adjacent defects fixed in the same window
  • What to watch on the first real riscv64 build
  • Why ARCH-PARITY is deliberately red for existing riscv64 images
  • Backing the lane out
  • MEASURED vs REASONED
• QNN on Linux (QAIRT)
  • Staging
  • QAIRT_HEADERS_DIR — the trap that cost a build
  • No staged SDK: upstream’s unhashed 1.5 GB download
  • What is real, and what was invented
  • Validation, 2026-09-03 (media-arm64, real v2.49.0.260730 staged)
• riscv64 venv parity (/opt/venv package set)
  • Mechanism
  • What is closed
  • optuna
  • What stays absent, and why
  • The gate
• riscv64: build at Ubuntu’s own baseline (RVA23, with vector)
  • Why this costs no compatibility
  • Why rva23u64_zifencei and not rv64gcv
  • Where it is set
  • The gate
  • Cost
  • libyuv RVV
• riscv64 cross lanes: build on amd64, test under QEMU
  • The pieces
  • The building blocks, measured (2026-10-01)
  • The sysroot from the registry (skopeo)
  • Traps, each found by a failing run
  • What the lanes do not run, and why
  • Status
• Local patches: what to send upstream, and in what shape
  • How to read this
  • Overview
  • 1. libstdc++: -nostdinc++ for src/c++23
  • 2. OpenCV: FFmpeg 8 removed AVCodec.pix_fmts and supported_framerates
  • 3. onnxruntime-genai: riscv64 is not a known target platform
  • 4. libcamera: apps_lib uses libtiff but does not depend on it
  • 5. GStreamer: the lame probe checks the header and ignores the library
  • 6. MLAS: MlasHGemmSupported is declared but never defined in GEMM-only builds
  • 7. onnxruntime: Android Gradle Plugin 7.4.2 is too old for current tooling
  • 8. gst-plugins-rs: the cargo wrapper clobbers RUSTFLAGS — WITHDRAWN
  • 9. gst-plugins-rs: CARGO_BUILD_TARGET never reaches cargo — WITHDRAWN
  • 10. GStreamer: OpenCV 5 moved symbols into new headers — ALREADY FIXED UPSTREAM
  • 11. GStreamer: OpenCV 5 dropped the cascade-classifier elements
  • 12. gst-libav: codec IDs removed from FFmpeg 8 — ALREADY FIXED UPSTREAM
  • 13. LiteRT: the pip build script hardcodes what a cross build must override
  • 14. torchvision: setup.py cannot be pointed at a staged torch
  • 15. cerbero: dropping the m4 build-tool dependency
  • 16. libyuv: the RVV rows are clang-gated
  • 17. cerbero: glib does not declare its libiconv dependency on Android
  • 18. cerbero: the soundtouch tarball checksum is stale
  • 19. cerbero: the pkg-config fallback mirror is gone
  • 20. OpenCV: hal_internal.cpp trusts the include path for <complex.h>
  • 21. slang: riscv64 pointer size and byte order
  • 22. gst-devtools: the SSIM validate plugin fails init outside gst-validate
  • 23. onnxruntime-genai: ORT v1.31.0 moved the model-package entries out of the experimental API
  • Warning waivers — candidates for a report, not patches
  • Not a patch file
  • What is left to prepare
  • Regenerating a patch against a newer upstream
• Prepared upstream submissions
  • Contents
  • Reproducing that check
• IREE: the two-stage cross build
  • Stage 1 — the native amd64 host tools
  • Stage 2 — cross the runtime and the Python bindings
  • Why this page exists
• Linux Accelerator Images
  • Optional NVIDIA GPU image chain
  • NVIDIA GPU Build (Linux)
  • NVIDIA on arm64 (SBSA): one image for servers and Jetson
  • DeepStream (nvidia variant)
  • The media fan-out strategy, as AGENTS.md carried it
  • Torch Add-on (Linux)
  • AMD GPU Build (Linux)
  • ROCm: what the first :latest-rocm run must carry (planned, 2026-09-22)
  • Hailo (in the standard image)
  • Edge accelerators
• Hailo support — image-chain integration plan
  • What exists (2026-09-20)
  • Phase 3: Windows HailoRT (LANDED 2026-09-21)
  • The nested build cache and pyhailort: two switches
  • Why an image chain
  • Upstream facts (2026-09-19)
  • Compatibility findings (resolved 2026-09-20)
  • Integration design (Linux lane)
  • Phased rollout
  • Open questions
• Linux Host Setup (GPU, drivers, runtime, boot)
  • Phase A — GPU drivers
  • The prerequisites list AGENTS.md carried
  • Phase B — Container runtime host config
  • Phase C — Performance mode
  • On laptop-class hardware also check that TLP is not overriding the governor set in C1: systemctl status tlp.
  • Phase D — Host toolchain
  • Phase E — Package sources and automatic updates
  • Troubleshooting
• Runtime Services and Streaming
  • Webserver (Linux)
  • Run with frontend display support
  • Raspberry Pi Camera
  • WebRTC Streaming
  • Raw gst-launch-1.0 pipelines (debugging below the app)
  • Building GStreamer from source on a device
• Rancher Desktop: the supported way to run Linux containers on Windows
  • Install
  • Use nerdctl, not docker
  • The image: always :latest
  • Reproducing a CI step locally
  • The orientation AGENTS.md carried
  • When to reach for this
  • WSL containers (wslc) are not a replacement yet
  • Persisting the cargo cache
  • -v name:/path is a bind under Windows nerdctl
  • Registering arm64 emulation in Rancher’s VM (per VM boot)
  • Emulated arm64 cannot run bubblewrap or static-PIE
  • Long-running work: detached containers + tmux
  • Fixing file ownership after a container writes to a bind mount
  • Setting up WSL2 itself
• Linux Reference (general)
  • Disk and files
  • Text and logs
  • Processes and services
  • Users and permissions
  • Networking
  • SSH
  • Packages, firmware, kernel
  • Disks, mounts and swap
  • Boot
  • Keyboard layout on a headless box
  • Media and document conversion
  • Remote desktop on a headless box
  • Git
  • Odds and ends

Windows:

• Windows Build Image
  • Source Patch Policy
  • The Windows lane as AGENTS.md carried it
  • The build notes AGENTS.md carried
  • Component Build Matrix
  • Prerequisites
  • Build Commands
  • Running the Image
  • Smoke Testing
  • Windows Script Reference
  • Why the pin suite runs on a Windows runner, under Pester 3.4.0
  • Reusable module: WindowsContainerBuild.Reuse
• ROCm on the Windows lane (-Variant rocm)
  • What the rocm lane enables
  • The ROCm layer (Dockerfile.rocm)
  • ONNX Runtime WebGPU EP (rocm lane, spike)
  • GStreamer on the rocm lane
  • FFmpeg on the rocm lane: AMD AMF and Vulkan
  • OpenCV on the rocm lane
  • IREE and TVM on the rocm lane
  • LiteRT-LM GPU backend (rocm lane only)
  • PyTorch on the rocm lane (torch stage)
  • llama.cpp HIP and Vulkan (Dockerfile.rocm-llama, rocm lane only)
  • MIGraphX and the ORT plugin EP (rocm lane, spike)
  • Redistribution
  • Open points
• Windows build lanes — BuildKit, nerdctl and classic docker
  • The classic lane was retired on 2026-08-26
  • Build isolation and CPU parallelism
  • BuildKit/containerd lane (PREFERRED, windows/Build-Buildkit.ps1)
  • nerdctl lane (admin): run, inspect, build
  • The 125-layer budget (classic lane)
  • Re-testing process isolation on new versions (is the bug gone yet?)
  • Run-side wcifs symptoms (process isolation)
  • Driver preflight gates and isolation policy
• Windows build invariants (do not regress)
  • Contents
  • Shell and PowerShell discipline
  • Gates that must stay armed
  • Diagnosing: probes and evidence
  • Logs
  • Layers, scratch and image size
  • Lanes, isolation and CPU
  • Container networking (CNI)
  • Build inputs and toolchain
• Windows build resources — CPU, memory, cache and GPU
  • GPU acceleration in containers (DirectML on the host GPU)
  • Media fan-out and memory budgeting
  • Building a project inside the image, as AGENTS.md carried it
  • Maximum resource envelope (verified 2026-07-12)
  • The Windows cache, tier by tier
  • Persistent compile cache (sccache)
• clang-cl sanitizers on Windows — the runtime choices behind Sanitizers.cmake
  • Dynamic ASan runtime: /clang:-shared-libsan
  • UBSan: trap mode when ASan is absent
  • Microsoft’s ASan runtime, not LLVM’s
• Windows cross builds (arm64)
  • The constraint everything follows from
  • Why clang-cl makes this cheap
  • Vulkan needs an optional component
  • Cache discipline: the base image is shared
  • Where arch facts live
  • SIMD: the failure that hides inside a green build
  • Vulkan on lavapipe
  • The Vulkan validation layer
  • Verification
  • Consumer cross lanes (container-ci-windows.yml)
  • Sequencing: rebuild base twice, on purpose
  • Upstream portability fixes this lane carries
  • The meson cross file: --target belongs in [binaries]
  • The target CPython is built from source (#120 step 1)
  • The Python consumers are built for the target (#120 step 2)
  • Cross machinery the LiteRT branch added
  • The merge stage on arm64
  • TVM and IREE cross-build runtime-only (#116, 2026-08-24)
  • QNN execution provider (#121, 2026-08-24; SDK staged + multi-framework 2026-08-29)
  • aarch64 compiler-rt is a base prerequisite
  • WebRTC on the cross lane (CON28, 2026-10-05)
  • aarch64 OpenSSL is a base prerequisite too
  • Three resilience fixes the merge stage needed
  • TensorRT staging, as AGENTS.md carried it
  • QNN staging on Windows, as AGENTS.md carried it
  • What this lane cannot produce
• Fresh Windows Host Bring-Up (BK lane + repo gates)
  • Phase A — One-time host provisioning [admin]
  • Phase B — Repo checkout + gate tooling [non-admin]
  • Phase C — Build-service tuning [admin]
  • Phase D — Per-boot / per-run checks
  • Phase E — First build + verification
  • Classic-lane fallback — there is none any more
  • Phase R — Recovering after a Stevedore reinstall / repair [admin]
  • Appendix — host odds and ends
• Stevedore and docker on Windows — setup fixes and service recovery
  • Stevedore Setup Fixes
  • Docker on Windows: registry auth, networking, service recovery
• Windows Container Build Performance
  • Result
  • Transports: how to set up both
  • What works: reuse one container
  • What does not work
  • The image does not fit on C:, and that is the default
  • The prologue on hosted runners
  • Gotchas that cost real time
  • Reusable implementation
  • Applying this elsewhere
• Windows Reference (general)
  • Disk and files
  • Running things and reading the result
  • Services and updates
  • Restart, shutdown, recovery
  • PATH
  • SSH into a Windows host
  • Wake-on-LAN
  • Certificates and MSIX
  • Toolchain odds and ends
  • Phantom programs and drivers
  • Removable media
  • Media capture
• Windows lane: what to send upstream, and in what shape
  • Prepared and ready to send (12)
  • Superseded before filing — someone else got there first
  • Already filed
  • ✔ Upstream already fixed it — retire on a version bump
  • B — genuine, but not ready to send
  • Not graded yet — local changes added after 2026-09-02
  • C — never file these
  • Before filing anything

Build, CI and tooling:

• Build cache tiers (Linux cross lane)
• Build parallelism & per-job memory calibration
• Build resource monitoring
• Build secrets (BuildKit --secret)
• Cross-build verification & failure-class catalog
• Code Quality Tooling
• Code quality gate registry
• Consumer inventory — proving who calls this hub
• Dependency updates — Renovate, run locally
• Shared script libraries (linux/scripts/lib/)
• Slang shader compilation (SPIR-V + WGSL)
• Python CI: the drivers, and the three traps in uv
• Python app bundles — a consumer’s app as a relocatable folder
• Branches, CI rounds and releases
• CI Build Triggers: which lanes run when
• Publishing over FTP
• GitHub CLI: Reading and Fixing Pipeline Status
• Mistral Vibe + GLM-5.2 Setup
• GenieX on Snapdragon — on-device OpenAI-compatible server
• Agentic Loop Build Matrix
• Agentic Loop Module (WindowsAgenticLoop.Common.psm1)

Project:

• Project Information
• Third-Party Software & Licenses
• SBOM — generating it, and what it is actually for
• Vulnerability scanning — running it, and reading the result
• Upstreaming: add -nostdinc++ to libstdc++ src/c++23 (Canadian-cross std module)
• Upstream issue draft — file at microsoft/hcsshim (cross-reference moby/buildkit)
• Upstream issue draft — file at microsoft/Windows-Containers

Backlogs and archives:

• Refactoring backlog — OPEN items only, grouped by EXECUTION CONTEXT
• Build watch list — the 2026-09-05 wave, read against a running chain
• Windows container chain — refactor backlog
• Changelog archive — 2026-08-29 through 2026-09-07
• Changelog archive — 2026-08-14 through 2026-08-28
• Changelog archive — through 2026-08-13
• Refactoring backlog
• Refactoring backlog — CLOSED items, archived 2026-08-27
• Refactoring backlog — CLOSED 2026-08-30
• Refactoring backlog — CLOSED 2026-08-31 (A1 closure window + GEN1)
• Refactoring backlog — CLOSED 2026-09-02 (RVA23 rebuild window)
• Refactoring backlog archive — 2026-09-03
• Refactoring backlog archive — 2026-09-07
• Refactoring backlog archive — 2026-09-09
• Refactoring backlog archive — 2026-09-17
• Windows backlog archive — closed items and history (archived 2026-08-11)
• Windows backlog archive — 2026-08-17
• Windows backlog archive — 2026-08-21
• Windows backlog archive — 2026-08-26
• Windows backlog archive — 2026-08-31
• Windows backlog archive — 2026-09-17