Isaac ROS Container¶

GPU-accelerated ROS 2 perception container for simulation mode. Built from a Dockerfile on top of NVIDIA's base image.

How It Works¶

The container is a self-contained ROS 2 environment with GPU access. It receives sensor data from Isaac Sim (running on the host) via DDS, runs GPU perception (SLAM, AprilTag, 3D mapping), and serves visualization over WebSocket.

flowchart LR
    subgraph HOST["Host — Workstation"]
        SIM["Isaac Sim<br/>(simulator)"]
    end
    subgraph CONTAINER["Container — isaac-ros-dev"]
        PERC["GPU Perception<br/>AprilTag, SLAM, nvblox"]
        FOX["Foxglove Bridge :8765<br/>H.264 NVENC republisher"]
    end
    BROWSER["Foxglove Studio<br/>(any browser)"]

    SIM -- "UDP DDS" --> PERC
    PERC -- "UDP DDS" --> SIM
    FOX -- "WebSocket :8765" --> BROWSER

The container uses --network host so it shares the host's network stack — DDS topics flow freely between Isaac Sim and the container without any port mapping.

Quick Start¶

The container is managed entirely with docker-compose — no special CLI tools required.

# Start container
docker compose -f ~/workspaces/isaac_ros-dev/docker-compose.yml up -d

# Attach a shell
docker exec -it -u admin isaac_ros_dev_container bash

# Stop
docker compose -f ~/workspaces/isaac_ros-dev/docker-compose.yml down

Tip: Add an alias for quick shell access:

alias iros='docker exec -it -u admin isaac_ros_dev_container bash'

What's in the Base Image¶

NVIDIA provides a ~38.8 GB base image from NGC:

nvcr.io/nvidia/isaac/ros:noble-ros2_jazzy_<hash>-amd64

This includes:

• ROS 2 Jazzy — full desktop install (50+ packages)
• TensorRT — GPU-accelerated inference
• PyTorch — deep learning framework
• nav2 — ROS 2 navigation stack
• rviz2 — 3D visualization
• foxglove-bridge — WebSocket bridge for Foxglove Studio
• slam_toolbox — SLAM algorithms
• OpenCV — computer vision (custom NVIDIA build with CUDA)
• CUDA 13.0 dev tools — compiler, libraries, headers
• VPI, CV-CUDA, Triton — NVIDIA perception and inference libraries

What's NOT in the base (we add these):

• Standard ROS 2 apt repository (NVIDIA base only has their own repos)
• Isaac ROS perception packages (apriltag, cuVSLAM, nvblox)
• H.264 NVENC video transport for Foxglove
• ffmpeg with NVENC support
• Teleop packages (keyboard and joystick control)
• FastDDS configuration for host/container communication

What the Dockerfile Adds¶

The Dockerfile (~/workspaces/isaac_ros-dev/Dockerfile) adds a thin layer on top of the base. The base image is never modified — Docker layers are immutable.

Packages¶

The NVIDIA base image only includes NVIDIA's own apt repos. The Dockerfile first adds the standard ROS 2 community repo (packages.ros.org) and removes a broken yarn repo from the base image, then installs packages from both sources:

After installing, rm -rf /var/lib/apt/lists/* deletes the apt package index cache (~50-100 MB) to keep the image smaller. Standard Docker practice.

FastDDS UDP-Only Transport¶

This env var is set in two places:

• /etc/profile.d/fastdds-fix.sh — picked up by login shells (when you docker exec bash)
• Explicitly in each entrypoint script — because the container's startup system sources scripts, not login shells, so profile.d doesn't apply

Sim vs real: This fix exists for simulation mode where Isaac Sim and the container share the same host. In real robot mode, the G1 uses CycloneDDS over Ethernet — a completely different DDS implementation on a different machine, so this config is irrelevant. However, forcing UDP is harmless in real mode too (UDP works fine over a network), so one image works for both scenarios without needing different configs.

Entrypoint Scripts¶

The NVIDIA base image has a startup system: when the container boots, it runs every .sh script in /usr/local/bin/scripts/entrypoint_additions/ in alphabetical order. The 50- and 60- prefixes control execution order.

All scripts must explicitly set FASTRTPS_DEFAULT_PROFILES_FILE because entrypoint scripts are sourced, not run as login shells.

Admin User¶

A non-root admin user with passwordless sudo. Used when attaching to the container (docker exec -it -u admin).

Running Services¶

Foxglove Bridge¶

Opens a WebSocket that Foxglove Studio connects to. Exposes all ROS 2 topics in real-time — camera feeds, SLAM maps, detections, joint states.

H.264 NVENC Republisher¶

Encodes raw camera images using the GPU's hardware H.264 encoder (NVENC). Without this, streaming raw images over the network to Foxglove is too slow.

Teleop Twist Joy¶

Converts joystick input to velocity commands. Axis 1 (vertical) maps to linear.x (forward/back), axis 0 (horizontal) maps to angular.z (turn). Deadman switch is disabled — input goes straight to /cmd_vel.

Used with the foxglove-joystick extension in Foxglove Studio. Set the extension to Keyboard mode and publish to /joy.

Files¶

All in ~/workspaces/isaac_ros-dev/:

Rebuilding the Image¶

cd ~/workspaces/isaac_ros-dev
docker build -t isaac-ros-dev:latest .

The base image (38.8 GB) is cached — only the custom layer (~0.8 GB) rebuilds. Takes ~30 seconds.

Host Wrapper¶

~/bin/ros2¶

Runs ros2 commands inside the container from the host terminal:

docker exec isaac_ros_dev_container bash -c \
  "export FASTRTPS_DEFAULT_PROFILES_FILE=/etc/fastdds_no_shm.xml && \
   source /opt/ros/jazzy/setup.bash && \
   ros2 $*"

Teleop (Keyboard Control)¶

Drive the robot from a terminal using teleop_twist_keyboard. It publishes geometry_msgs/Twist to /cmd_vel and sends zero velocity when you release keys.

# In a tmux session
docker exec -it isaac_ros_dev_container bash -c \
  "source /opt/ros/jazzy/setup.bash && \
   export RMW_IMPLEMENTATION=rmw_fastrtps_cpp && \
   export FASTRTPS_DEFAULT_PROFILES_FILE=/etc/fastdds_no_shm.xml && \
   ros2 run teleop_twist_keyboard teleop_twist_keyboard"

Controls:

   u    i    o        i = forward       k = stop
   j    k    l        , = backward      q/z = speed up/down
   m    ,    .        j/l = turn        w/x = turn speed up/down

What's NOT in the Container¶

Why Not isaac-ros-cli?¶

NVIDIA ships an apt package called isaac-ros-cli that provides isaac-ros activate and isaac-ros init commands for managing Isaac ROS containers. It was removed from this system (sudo apt remove isaac-ros-cli) and is not needed. Docker-compose replaces it entirely.

Problems with isaac-ros-cli:

• Raw docker run — it launches containers with docker run rather than compose, so there's no declarative config to version-control or reproduce.
• Undocumented image key system — it layers customizations using an internal "image key" mechanism that isn't well documented. Understanding what ends up in the final image requires reading the CLI's source.
• Destroys customizations — running isaac-ros activate without specifying the correct custom keys recreates the container from the stock NVIDIA base image, silently losing any packages or configs you added.
• Redundant configs — it ships its own Dockerfiles and FastDDS configs in /etc/isaac-ros-cli/, duplicating what's already managed in ~/workspaces/isaac_ros-dev/.

The docker-compose approach at ~/workspaces/isaac_ros-dev/ gives full control over the image, explicit configuration in version-controlled files, and predictable up/down lifecycle management.

Troubleshooting¶

docker exec isaac_ros_dev_container bash -c \
  "cat /etc/fastdds_no_shm.xml && echo '---' && echo \$FASTRTPS_DEFAULT_PROFILES_FILE"

docker exec isaac_ros_dev_container bash -c \
  "export FASTRTPS_DEFAULT_PROFILES_FILE=/etc/fastdds_no_shm.xml && \
   source /opt/ros/jazzy/setup.bash && \
   ros2 launch foxglove_bridge foxglove_bridge_launch.xml port:=8765 &"

ps aux | grep isaacsim