Skip to main content
Version: v4.2.0

Building Kairos images for NVIDIA Jetson

kairos-init supports three NVIDIA Jetson boards through the --model flag. Passing the right model is enough — you no longer need a hand-written Dockerfile.nvidia. This page walks through the build; the per-board flashing steps stay on the existing device pages linked below.

Where did Dockerfile.nvidia go?

Kairos used to ship images/Dockerfile.nvidia in the main repo. Everything it did — enabling the NVIDIA L4T apt repos, installing nvidia-l4t-* packages, wiring the Tegra kernel, disabling boot firmware updates in preinstall — is now applied automatically by kairos-init when you pass a Jetson --model. The Dockerfile.nvidia was removed once the logic moved into kairos-init; this page is its replacement.

Supported Jetson models​

--modelBoardL4T familyBase image
nvidia-jetson-agx-orinJetson AGX Orinr36.xubuntu:22.04
nvidia-jetson-orin-nxJetson Orin NXr36.xubuntu:22.04
nvidia-jetson-thorJetson AGX Thorr39.2ubuntu:24.04 or Hadron

For the full list of --model values (including generic, rpi3, rpi4) see The Kairos Factory.

Prerequisites​

  • Docker with buildx.
  • Build platform is linux/arm64 — either a native ARM host, cross-build via QEMU (--platform linux/arm64) or an ARM GitHub Actions runner.
  • kairos-init v0.9.0 or newer for AGX Orin / Orin NX; v0.9.0+ is also the minimum for Thor support. Check Kairos releases for the newest tag; this page uses {{< KairosInitVersion >}}.

Build the image​

The Dockerfile is the standard Kairos Factory shape — only --model changes per board.

AGX Orin (Ubuntu 22.04)​

FROM quay.io/kairos/kairos-init:v0.17.2 AS kairos-init

FROM ubuntu:22.04
ARG VERSION=1.0.0
RUN --mount=type=bind,from=kairos-init,src=/kairos-init,dst=/kairos-init \
    /kairos-init --version "${VERSION}" --model nvidia-jetson-agx-orin

Orin NX (Ubuntu 22.04)​

FROM quay.io/kairos/kairos-init:v0.17.2 AS kairos-init

FROM ubuntu:22.04
ARG VERSION=1.0.0
RUN --mount=type=bind,from=kairos-init,src=/kairos-init,dst=/kairos-init \
    /kairos-init --version "${VERSION}" --model nvidia-jetson-orin-nx

AGX Thor (Ubuntu 24.04 or Hadron)​

Thor has two supported base images. Ubuntu 24.04 is the drop-in equivalent to the flow above; Hadron is a musl-based from-scratch base that requires a pre-build step (see the Thor page for details). The --model flag is the same.

FROM quay.io/kairos/kairos-init:v0.17.2 AS kairos-init

FROM ubuntu:24.04
ARG VERSION=1.0.0
RUN --mount=type=bind,from=kairos-init,src=/kairos-init,dst=/kairos-init \
    /kairos-init --version "${VERSION}" --model nvidia-jetson-thor

For the Hadron variant, follow Nvidia AGX Thor — it builds a Thor-specific Hadron base first, then runs the same kairos-init step with --model nvidia-jetson-thor.

Build for linux/arm64​

If your workstation is not ARM, cross-build via QEMU:

docker buildx build --platform linux/arm64 \
  -t my-registry.example.com/kairos-agx-orin:v1.0.0 \
  --push .

On a native ARM host you can drop --platform and use plain docker build.

What --model does under the hood​

For any of the Jetson models, kairos-init:

  • Adds the appropriate NVIDIA L4T apt repos (https://repo.download.nvidia.com/jetson/common r<L4T> and the board-specific t234 / t264 repo).
  • Installs the nvidia-l4t-* package set (kernel, bootloader, firmware, CUDA runtime, multimedia, tools, etc.) matching the L4T family.
  • Wires up the Tegra kernel and initrd so /boot/vmlinuz and /boot/initrd point at the Tegra artifacts, not the generic Ubuntu ones.
  • Applies the 12_nvidia.yaml cloud-config (disables nv-l4t-boot-fw-update-in-preinstall, sets up the Tegra rootfs prep, etc.).
  • Enables the required systemd services for the board.

For Thor, the model also keeps QSPI boot firmware aligned with the image's L4T release:

  • The current Thor L4T pin and its matching UEFI capsule are installed together. Renovate tracks new Thor L4T releases in kairos-init so the pair is updated together.
  • The live initramfs omits the proprietary NVIDIA drivers. This lets the installer boot on boards with older, updatable QSPI firmware.
  • The same version check runs after installation and after every OCI upgrade. When the board firmware is older, Kairos stages the capsule on the EFI System Partition and UEFI applies it on the next boot. Matching versions are left unchanged.
  • A board with firmware newer than the image is rejected because UEFI capsules cannot downgrade firmware. Firmware older than L4T 38.0 requires a USB host flash.

See Nvidia AGX Thor for the full compatibility and lifecycle behavior.

None of this needs to be written by hand — the flag pulls in everything the old Dockerfile.nvidia used to do, and stays current with L4T releases as kairos-init is updated.

Add providers, FIPS, Trusted Boot, ...​

Everything the Kairos Factory supports composes with --model. To bundle a Kubernetes provider, pass it the same way as for a generic image:

RUN --mount=type=bind,from=kairos-init,src=/kairos-init,dst=/kairos-init \
    /kairos-init --version "${VERSION}" \
      --model nvidia-jetson-agx-orin \
      --provider k3s \
      --provider-k3s-version v1.35.1+k3s1

--fips, --trusted-boot, --skip-steps and stage extensions (-x) all work identically. See The Kairos Factory for the full flag reference.

Turn the OCI image into installable artifacts​

Once the image is built and pushed, feed it to AuroraBoot to produce partitions, ISOs or raw disk images. The generic AuroraBoot flow applies; Jetson-specific flashing steps (Linux_for_Tegra SDK, board configs, partition layouts) live on the per-board pages:

GPU workloads on the cluster​

Building the image only gets you a bootable node. To let Kubernetes pods request nvidia.com/gpu on Thor, see GPU Operator on Jetson AGX Thor. For discrete NVIDIA GPUs on x86_64 (not Jetson), see Discrete NVIDIA GPU on x86_64.