Skip to navigation

Build and run

View as Markdown

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 info

If docker info reports permission denied for /var/run/docker.sock, your user probably isn’t in the docker group. Add it with:

sudo usermod -aG docker "$USER"

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:

docker info --format '{{json .Runtimes}}'

Only if this command succeeds and its output does not include nvidia, register the NVIDIA runtime and check again:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker info --format '{{json .Runtimes}}'

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Reopen your terminal and ensure uv is in your PATH:

uv --version

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:

./isaac_os run <app_name> <mode>

If restarting a simulation app reports that its TCP port is already in use, check whether another process is still listening on that port. If no listener remains, recently closed connections may still be in TCP TIME_WAIT, typically lasting about 60 seconds on Linux. Wait until the port becomes available, then retry. If the issue persists, inspect the remaining processes and TCP socket states.

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:

./isaac_os build-container
./isaac_os build <app_name> --no-docker-build
./isaac_os run <app_name> <mode> --no-docker-build --no-local-build

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:

./isaac_os run-container <app_name> <mode> -- nvidia-smi

For individual CMake targets, follow the component build instructions.

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:

docker buildx version
docker build --help

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:

./isaac_os test

Select one application’s tests:

./isaac_os test <app_name>

To separate building from running tests, use the same application selection for both commands, or omit it from both as shown here:

./isaac_os test --ctest-options='-DBUILD_ONLY=ON'
./isaac_os test --ctest-options='-DTEST_ONLY=ON'

Check CTest’s summary for failures.

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.