Build and run
This guide provides instructions for running reference applications from the Isaac OS
source repository. The steps below help you set up your environment and use the
./isaac_os convenience utility to manage container builds, application builds and
tests. See the
CLI reference for options and alternatives to the container workflow.
For source locations, see the repository map.
✨ Agent prompt: Build and run an application
Prerequisites
For the container workflow, install:
- Git and curl using your host’s package manager.
- Docker and NVIDIA Container Toolkit for GPU access.
- uv to launch the pinned CLI.
Check platform support. On x86_64, use an NVIDIA GPU with compute capability >= 7.5 for Video Codec SDK 13.0 and driver 595 or newer for the default CUDA 13.2 container. Jetson drivers come with JetPack; follow the AGX Thor Docker setup if your Jetson installation does not include the container toolkit.
First, verify that your login user can access Docker without sudo:
⚠️ Docker socket permission denied
If docker info reports permission denied for /var/run/docker.sock, your user
probably isn’t in the docker group. Add it with:
Log out and back in (or reconnect over SSH), then retry docker info.
See Docker’s post-installation guidance
for details.
Once docker info succeeds, check the registered runtimes:
Only if this command succeeds and its output does not include nvidia, register
the NVIDIA runtime and check again:
Install uv:
Reopen your terminal and ensure uv is in your PATH:
⚠️ The CLI reports that uv is required
Check the uv installer’s reported location and add it to your PATH. Alternatively, use a pre-installed CLI matching the repository’s pin; see CLI requirements.
Network access is needed for the first CLI, image and dependency downloads. Inference applications also download models. For a guided checkout and first run, follow Getting started.
Build and run an application
Run these commands from the repository root. run builds the development container
and application, fetches dependencies and starts the selected mode:
❓ Why does the first run take longer?
The first run downloads images and dependencies, then compiles the application. Inference applications may also build TensorRT engines. Later runs reuse these caches. Isaac Sim has a separate shader cache; see simulator setup.
To build and run separately:
Omit the skip flags when the image or application inputs have changed.
Use run-container for custom checks in an application’s development environment. For
example, check GPU access with:
For individual CMake targets, follow the component build instructions.
Buildx resource-limit warning
If the build prints Docker Buildx does not support build resource limits; the job CPU limit will not be forwarded to build steps, the CLI could not confirm support for
Docker’s --resource build option. It continues without forwarding the launching
process’s allowed CPU set to the image-build steps. Those steps may use CPUs outside
that set, subject to the builder’s own configuration.
This warning alone does not mean the build failed, and it does not report the application container’s runtime CPU affinity. You can continue the build if you do not require that build CPU restriction. Complete builds before collecting latency measurements.
If build CPU restrictions are required, check the Docker installation used by the CLI:
Look for --resource in the help output. The warning can also occur if the CLI’s
help query fails or times out. If the option is listed but the warning persists,
retain the build log and these command outputs for diagnosis; do not assume the
requested CPU restriction was applied.
To reduce latency and jitter in the applications that you run, see Optimize your host.
Test
test configures and builds the repository test graph, then runs CTest:
Select one application’s tests:
To separate building from running tests, use the same application selection for both commands, or omit it from both as shown here:
Check CTest’s summary for failures.
⚠️ TEST_ONLY needs an existing test build
test uses cmake/isaac_os.container.ctest and build/all by default. Without an
application argument, it batches targets and shares dependency builds. Selecting
an application reconfigures that directory for its tests. TEST_ONLY requires this
test build; it does not reuse the individual application build made by build or run.
For linting and code style, see CONTRIBUTING.md.