Skip to main content

Running GPU applications on Jetson Orin

Developer preview for Jetson AGX Orin, Orin NX, and Orin Nano. Admiral supplies the NVIDIA driver on the device and runs your CUDA application as the system userspace. The same driver path covers CUDA compute and GPU display output (EGL, OpenGL, Vulkan).

You do not install a desktop NVIDIA driver, Docker daemon, or NVIDIA Container Toolkit on the device.

How Admiral supplies the GPU driver​

Admiral runs your container image as the device's system userspace. The platform supplies the kernel, GPU firmware, and matching NVIDIA driver libraries. Your image supplies the Linux userspace, CUDA application runtime, and application.

The driver libraries are tied to the installed platform release and mounted read-only into your userspace when it starts.

Admiral suppliesYour image supplies
GPU kernel modules and firmwareARM64 glibc userspace and normal application dependencies
NVIDIA NVGPU libcuda.so.1 and companion driver librariesCompatible CUDA runtime and any required CUDA libraries
GPU device nodes and host permissionsApplication and optional frameworks such as TensorRT or PyTorch
GPU readiness checks and driver mountsService configuration and application user/group membership

Admiral injects kernel device nodes and host driver libraries. Frameworks, perception pipelines, and ROS packages live in your image. Use a CUDA runtime built for Jetson / L4T rather than an arbitrary desktop CUDA image.

Prepare your image​

Build a linux/arm64 image using glibc. The NVIDIA binaries in this platform are not native musl libraries.

Include your application and every runtime library it needs. Driver injection does not supply libcudart, cuBLAS, cuDNN, TensorRT, or PyTorch. A compiler may be used in a build stage and omitted from the final image.

Omit competing NVIDIA driver packages from the final image. Check framework base images for bundled drivers, and keep CUDA development stub libraries out of runtime search paths. Applications should load libcuda.so.1 normally and use the driver Admiral supplies.

Pin the image and package versions you deploy. Keep custom data mounts in application-specific locations such as /app/data. Custom mounts that cover driver locations or their protected parents, such as /run or /usr/lib, are rejected.

Deploy through Admiral​

Publish the image to a registry the device can reach, then deploy it through the normal userspace workflow in the Admiral portal.

Use the standard system-userspace hardware path. Device isolation must remain disabled (isolateDevices: false). There is no extra GPU capability flag.

NVIDIA_VISIBLE_DEVICES and NVIDIA_DRIVER_CAPABILITIES do not activate this integration. Do not add NVIDIA Container Toolkit hooks or a second driver injector inside the image.

What your application sees​

The driver is available through standard system library paths with zero configuration and zero rework. Off-the-shelf container images drop directly into Admiral: standard dynamic linkers (ld.so) and dlopen("libcuda.so.1") resolve driver libraries automatically.

Location in the userspaceContentsPurpose
/usr/lib/aarch64-linux-gnu/libcuda.so.1, libnvrm_gpu.so, etc.Standard multiarch path (Ubuntu / Debian drop-in)
/usr/lib/Symlinks / bindings for driver librariesStandard FHS path (Alpine / Arch / generic drop-in)
/run/admrl/nvidia/manifest.jsonPlatform profile, release, and driver metadataOptional build & driver verification
/run/admrl/nvidia/licenses/NVIDIA package license filesCompliance and attribution

Because driver libraries are bound directly into standard multiarch directories, your application does not need custom LD_LIBRARY_PATH overrides, special build flags, or container wrappers. Standard CUDA runtimes, TensorRT, PyTorch, and ROS 2 workloads run unmodified.

The system userspace sees host device paths, including /dev/nvmap and NVGPU interfaces under /dev/nvgpu/. Legacy /dev/nvhost-*-gpu paths also remain available. Display output uses the same /dev pass-through, including DRM/KMS nodes such as /dev/dri/card0. Do not create device nodes in the image or hard-code their device numbers.

Orin does not require /dev/nvidia0 or nvidia-smi. Those nodes belong to the x86 NVIDIA path; unified-memory devices used on desktop GPUs are not part of the Orin driver layout.

GPU display output​

CUDA compute and GPU-backed display share the injected NVIDIA driver. Your image supplies the graphics userspace (EGL, OpenGL, Vulkan, a compositor or kiosk shell) the same way it supplies libcudart.

  • Keep device isolation disabled so the workload sees host display and GPU nodes.
  • Graphical kiosks and operator HMIs typically also need interactive mode and a DRM/KMS or Wayland path. See Hardware Access for fullscreen display pipelines.
  • nvidia-smi is not required to confirm that a frame is on the panel. Render to the connected display and confirm the application’s own output.

Applications running without root​

Selected compute devices are owned by root and the host video group, with mode 0660. On this platform the video group has numeric GID 28. A non-root application must retain that numeric group in its supplementary groups. Creating a group named video with a different number does not grant access.

Configure the application's service or entrypoint to use the intended UID and supplementary groups, and check id in the actual application process. Dockerfile USER is not applied to the OCI entry process; drop privileges in the service or entrypoint while keeping GID 28.

This preview does not introduce per-application GPU isolation or a dedicated GPU-memory quota. Orin shares system RAM between CPU and GPU. Budget memory for both, and test allocation under load.

Verify your application​

Deploy a diagnostic image through the portal, then confirm the profile, manifest, driver load, CUDA initialization, and a real kernel.

A suitable smoke test allocates memory, copies input to the GPU, runs vector addition, synchronizes, copies the result back, and checks every value. Device discovery alone is not enough. Record driver and runtime versions plus the image digest, then repeat after userspace recreation and reboot.

For frameworks, confirm the intended operations run on the GPU rather than falling back to CPU. For display workloads, confirm a frame reaches the connected panel rather than relying on a compute-only smoke test.

Run this inside the deployed userspace:

uname -m
id
printf 'profile=%s\nLD_LIBRARY_PATH=%s\n' "$ADMRL_NVIDIA_PROFILE" "$LD_LIBRARY_PATH"
cat /run/admrl/nvidia/manifest.json
ls -l /dev/nvmap /dev/nvgpu/igpu0/ctrl /dev/nvhost-ctrl-gpu

Diagnose a failure​

SymptomWhat to check
Userspace is rejected before launchAdmiral logs for platform identity, readiness, or driver-integrity errors
libcuda.so.1 cannot loadDriver mount, image architecture/glibc, missing dependencies, and library search paths
CUDA finds no GPUExact CUDA error, visible NVGPU devices, and application credentials
Permission deniedNumeric supplementary GID, the affected device path, and platform denial logs
Kernel launch or JIT failsCUDA version, actual compute capability, and application build target
Application fails under loadShared system RAM use, application limits, allocation behavior, and kernel logs
Display fails while compute worksDRM/KMS or Wayland ownership, connected panel, graphics libraries in the image, and interactive-mode / console policy

When requesting help, include the Admiral platform version, driver profile, image digest, CUDA/framework versions, application UID/groups, exact error, and application logs. Do not replace driver libraries, make devices world-writable, or reload GPU modules as an application startup workaround.

Platform updates carry the matching driver payload. Validate your image against each platform update before rolling it out; matching CPU architecture alone is not a CUDA compatibility guarantee.