# status: unverified
# source: https://docs.isaacsim.omniverse.nvidia.com/latest/installation/install_container.html
#         (Container Installation page, fetched directly on 2026-07-10) and
#         https://catalog.ngc.nvidia.com/orgs/nvidia/containers/isaac-sim
#         (NGC catalog, confirming the `6.0.1` tag is current as of this
#         session). Re-verify the tag against the NGC catalog before using
#         this command in a real project; Isaac Sim ships new container
#         tags with each release.

# Prerequisites: Docker, the NVIDIA Container Toolkit installed on the host
# (Linux only; see the environments skill's GPU-and-remote reference for
# that generic setup), and a working `nvidia-smi` inside a test container
# to confirm GPU passthrough before running Isaac Sim itself.

# Create the cache/config/data directories once, before the first run, and
# make sure they're owned by the UID the container runs as (1234 below,
# the value the docs use for a non-root container user):
mkdir -p ~/docker/isaac-sim/{cache/main,cache/computecache,logs,config,data,pkg}
mkdir -p ~/.cache/ov/hub
sudo chown -R 1234:1234 ~/docker/isaac-sim ~/.cache/ov/hub

docker run --name isaac-sim --entrypoint bash -it --gpus all \
    -e "ACCEPT_EULA=Y" \
    -e "PRIVACY_CONSENT=Y" \
    --rm --network=host \
    -v ~/docker/isaac-sim/cache/main:/isaac-sim/.cache:rw \
    -v ~/docker/isaac-sim/cache/computecache:/isaac-sim/.nv/ComputeCache:rw \
    -v ~/docker/isaac-sim/logs:/isaac-sim/.nvidia-omniverse/logs:rw \
    -v ~/docker/isaac-sim/config:/isaac-sim/.nvidia-omniverse/config:rw \
    -v ~/docker/isaac-sim/data:/isaac-sim/.local/share/ov/data:rw \
    -v ~/docker/isaac-sim/pkg:/isaac-sim/.local/share/ov/pkg:rw \
    -v ~/.cache/ov/hub:/var/cache/hub:rw \
    -u 1234:1234 \
    nvcr.io/nvidia/isaac-sim:6.0.1

# Inside the container, launch headless (see the ros2-integration and
# setup-and-requirements references for the ROS 2 bridge and the WebRTC
# livestream ports needed to view the result remotely):
#
#   ./runheadless.sh -v

# Flag notes:
# - `--gpus all`            required GPU passthrough (NVIDIA Container Toolkit).
# - `--network=host`        required for WebRTC livestreaming to work, not
#                            just a convenience; the signaling/media ports
#                            below need to be reachable directly.
# - `-e "ACCEPT_EULA=Y"`    required; the container will not start without it.
# - `-e "PRIVACY_CONSENT=Y"` optional telemetry opt-in, included here for
#                            parity with the upstream example command.
# - the `-v` cache/config/data mounts persist Omniverse's shader and asset
#   cache across container restarts, so a second run isn't a cold start
#   that re-downloads/re-compiles everything from scratch.
# - `-u 1234:1234`          runs as a non-root UID matching the directories
#                            created above; a mismatched UID/ownership here
#                            is a common source of permission errors.

# ROS 2 integration

The `isaacsim.ros2.bridge` extension, which ROS 2 distros it officially
supports per platform, the OmniGraph node pattern used to publish/subscribe
topics, and a worked clock-publisher example. Source:
`docs.isaacsim.omniverse.nvidia.com`'s ROS 2 installation and tutorial pages:
the distro-support table is a direct fetch on 2026-07-10; the extension
name and OmniGraph node identifiers are drawn from OmniGraph node
references visible in a fetched tutorial page (search-synthesis level
confidence); re-verify the exact extension id and node names against the
live docs or the running Extensions window before depending on them in a
real project.

## Officially supported ROS 2 distros (direct fetch on 2026-07-10)

| Platform | Supported distros | Recommended |
|---|---|---|
| Ubuntu 24.04 | Jazzy | Jazzy |
| Ubuntu 22.04 | Humble, Jazzy | Jazzy |
| Windows 11 | Humble | Humble |

**This may be narrower than the ROS 2 release used by the application.** The
table records what NVIDIA documented on 2026-07-10, not a permanent support
matrix. Detect the project's actual distro and re-check the current bridge
documentation before choosing a mixed stack. A distro absent from the official
matrix is unverified until the bridge is exercised against it.

**Experimental: any natively-installed distro.** The docs note Isaac Sim
"experimentally supports loading any ROS 2 distro that is natively
installed on your platform" (Ubuntu 22.04 or 24.04 only) by sourcing the
host's own ROS 2 install before Isaac Sim launches, rather than using the
bridge's bundled internal ROS 2 libraries. Only Humble and Jazzy were
officially tested and recommended in that fetch; treat any other distro run
this way as unverified for a given project until the bridge actually works
against it.

Additional notes from the same fetch:

- The bridge ships internal ROS 2 libraries for both Humble and Jazzy,
  including Cyclone DDS compiled against Python 3.12, so it does not
  strictly require a host ROS 2 install for those two distros.
- Zenoh middleware support is currently available only for ROS 2 Jazzy on
  Linux.

## The bridge extension

The ROS 2 bridge is the extension `isaacsim.ros2.bridge`. It exposes a set
of OmniGraph nodes (building blocks wired together in an Action Graph,
either through the GUI or programmatically via `omni.graph.core`'s
`Controller.edit()` in a standalone Python script) that publish or
subscribe ROS 2 messages from the running simulation. Confirmed node names
from a fetched tutorial: `isaacsim.ros2.bridge.ROS2Context` (the shared ROS 2
context every publisher/subscriber node references) and
`isaacsim.ros2.bridge.ROS2PublishClock` (publishes `/clock` from the
simulation's own time). The bridge also ships publish/subscribe node
variants per ROS 2 message type (image, twist, joint state, TF, and
others); check the Extensions window's node browser or the live tutorial
pages for the exact node name before wiring one into a real graph rather
than guessing the naming pattern.

## Worked example: publishing `/clock`

From a fetched standalone-Python ROS 2 tutorial page on 2026-07-10: creates
an Action Graph that reads the simulation's own time and publishes it as
`/clock`:

```python
import omni.graph.core as og

og.Controller.edit(
    {"graph_path": "/ActionGraph", "evaluator_name": "execution"},
    {
        og.Controller.Keys.CREATE_NODES: [
            ("ReadSimTime", "isaacsim.core.nodes.IsaacReadSimulationTime"),
            ("Context", "isaacsim.ros2.bridge.ROS2Context"),
            ("PublishClock", "isaacsim.ros2.bridge.ROS2PublishClock"),
        ],
        og.Controller.Keys.CONNECT: [
            ("ReadSimTime.outputs:simulationTime",
             "PublishClock.inputs:timeStamp"),
            ("Context.outputs:context", "PublishClock.inputs:context"),
        ],
        og.Controller.Keys.SET_VALUES: [
            ("PublishClock.inputs:topicName", "/clock"),
        ],
    },
)
```

Every publisher/subscriber node in a graph shares one `ROS2Context` node
(the `Context.outputs:context` → `<node>.inputs:context` connection above);
don't create a separate context per node, it's meant to be shared across
the whole graph the same way a single ROS 2 node handle is shared across a
process elsewhere.

Subscribing follows the same graph-node pattern in reverse (a subscribe
node's output feeds application logic instead of a publish node consuming
simulation state); the docs illustrate this with an example where an
incoming empty ROS 2 message teleports a cube to a random location; the
exact subscribe node name for a given message type should be checked the
same way as any other node in this extension.

## Generic ROS 2 mechanics

Workspaces, colcon, launch files, TF2 concepts, and QoS are the `ros2`
skill's territory, not re-taught here; this reference stops at what the
bridge extension itself publishes and subscribes.

# Scenes, robots, sensors, and synthetic data

USD stage/scene basics, the standalone `SimulationApp` Python workflow,
importing robots, attaching sensors, and the Replicator synthetic-data
pipeline. Source: `docs.isaacsim.omniverse.nvidia.com`'s quickstart, robot
setup, and Replicator tutorial index pages, mostly search-synthesis level
(page-navigation-hub content rather than a single copy-pasteable snippet);
re-verify exact API calls against the live tutorials before depending on
them in a real project. The clock-publisher pattern in
`references/ros2-integration.md` is the one piece of code on this topic
confirmed by direct fetch on 2026-07-10.

## USD stage and scene basics

Isaac Sim scenes are USD (Universal Scene Description) stages. Everything
doable through the GUI can also be done through Python: the standard
workflow is to author or assemble a scene interactively, export it as a
`.usd`/`.usda` file, then drive it from a standalone Python script for
repeatable runs (batch synthetic-data generation, headless regression
testing, and so on).

**Standalone Python workflow.** A standalone script must construct
`SimulationApp` *before* importing anything else from Isaac Sim: the app
object owns the render/physics context that later imports depend on:

```python
from isaacsim import SimulationApp

simulation_app = SimulationApp({"headless": True})  # or False for a local display

# Isaac Sim imports must come after SimulationApp is constructed.
import omni.usd
# ... build or load a stage, add robots/sensors, step the sim ...

simulation_app.close()
```

This import-order requirement (`SimulationApp` first, everything else
after) is a common source of confusing import errors if violated; treat
it as a hard rule, not a style preference. Re-verify the exact
`isaacsim.SimulationApp` import path against the current tutorials before
depending on it verbatim; older Isaac Sim releases used
`omni.isaac.kit.SimulationApp` instead, and the module path has moved
across major versions.

**Loading an existing scene.** Open a `.usd` file directly from the GUI's
Asset Browser, which is backed by NVIDIA's Nucleus asset library (hosted
robot and environment assets ready to drop into a stage), or point a
standalone script's stage-open call at a local or Nucleus-hosted USD path.

## Adding a robot

Isaac Sim ships several importers rather than one universal path:

- **URDF Importer**: the most common path for a ROS-ecosystem robot that
  already has a URDF.
- **MJCF Importer**: for robots described in MuJoCo's MJCF format.
- **USD to URDF Exporter**: the reverse direction, useful for round-
  tripping a hand-authored USD robot back into a ROS-facing URDF.
- **Nucleus-hosted assets**: pre-built robot USDs available directly from
  the Asset Browser, skipping import entirely.

Once a robot is in the stage, Robot Setup tooling covers the rest:

- **Robot Inspector**: examine a robot's structure/properties.
- **Robot Assembler**: compose a robot from separate component assets
  (e.g. an arm plus a gripper).
- **Joint Inspector**: examine and tune articulation joints.
- **Robot Poser**: position a robot and save named poses.

Real hardware fit matters here the same way it does for `gazebo`'s sensors:
an imported robot's joint limits, masses, and articulation setup should
match the physical unit's datasheet before results are trusted, not just
whatever the importer's defaults produce.

## Adding sensors

Three sensor families, per the Robot Setup documentation:

- **Camera sensors**: standard RGB/depth rendering through Isaac Sim's RTX
  renderer.
- **RTX sensors**: lidar and radar simulated via the same RTX ray-tracing
  pipeline as camera rendering, rather than a separate physics-only model.
- **Physics-based sensors**: IMU and contact sensors, driven by the physics
  simulation rather than rendering.

As with Gazebo guidance, pull real rate/FOV/range/noise numbers from the target
sensor's datasheet rather than leaving
importer or tutorial defaults in place; a sensor that "looks right" in a
demo scene but doesn't match the real unit's characteristics produces a
perception stack that quietly breaks the moment it meets real data.

## Generating synthetic data (Replicator)

`omni.replicator.core` (Replicator) is Isaac Sim's synthetic-data-
generation toolkit. This skill owns the *mechanics* of running it inside
Isaac Sim; deciding how much synthetic data a project needs, and how it
combines with real or teleop-collected data, is the `data` umbrella
skill's call.

The pipeline has three parts:

1. **Randomization**: systematically varying scene parameters (object
   poses, lighting, materials/textures, physics properties) across
   generated frames so a downstream perception model doesn't overfit to one
   fixed scene layout.
2. **Annotators**: capture ground-truth semantic information alongside
   each rendered frame (bounding boxes, segmentation, depth, and other
   modalities) as the scene is randomized.
3. **Writers**: export the annotated frames to a standardized on-disk
   format; COCO is one supported output format among others.

Typical use cases called out in the docs: domain randomization for
training robustness, sensor/perception dataset generation, and
robotics-specific scenarios (navigation, manipulation, grasping). Treat any
specific Replicator API call (writer names, randomizer function
signatures) as something to look up against the live Replicator tutorials
per scene rather than assumed stable across releases; this reference
intentionally stops at the conceptual pipeline rather than inventing exact
function signatures that weren't directly confirmed on 2026-07-10.

# Setup and requirements

GPU/driver/CPU/RAM/OS/storage requirements, the three install paths
(container, pip, workstation), and headless/livestream networking for Isaac
Sim. Source: `docs.isaacsim.omniverse.nvidia.com`'s System Requirements,
Container Installation, Python (pip) Installation, and livestream-client
pages, fetched directly on 2026-07-10 (method noted per section below).
**Requirements change per release**; re-verify against the live
requirements page before trusting a number here in a real project.

## GPU, driver, CPU, RAM, storage

The table below is a snapshot of the Isaac Sim 6.0.1 requirements fetched on
2026-07-10. It is evidence for that release, not a floor to copy into a new
project without checking the current requirements page.

| Requirement | Minimum | Recommended | Ideal |
|---|---|---|---|
| GPU | GeForce RTX 4080, 16 GB VRAM | GeForce RTX 5080, 16 GB VRAM | RTX PRO 6000 Blackwell, 48 GB VRAM |
| GPU driver (Linux) | 595.58.03+ | – | – |
| GPU driver (Windows) | 595.97+ | – | – |
| CPU | Intel Core i7 (7th gen) / AMD Ryzen 5, 4 cores | Intel Core i7 (9th gen) / AMD Ryzen 7, 8 cores | Intel Core i9 X-series / AMD Ryzen 9 or Threadripper, 16 cores |
| System RAM | 32 GB | 64 GB | 64 GB |
| Storage | 50 GB SSD | 500 GB – 1 TB NVMe | 500 GB – 1 TB NVMe |

Notes:

- **GPUs without RT cores are unsupported regardless of VRAM**: the docs
  call out A100 and H100 explicitly as not supported, since Isaac Sim's
  RTX renderer needs hardware ray-tracing cores that data-center compute
  GPUs lack.
- A GPU with less than 16 GB VRAM may struggle rendering scenes exceeding
  ~16 megapixels per frame, a soft ceiling on top of the hard minimum
  above, worth knowing before sizing a multi-camera synthetic-data scene.
- `aarch64` support is limited to the NVIDIA DGX Spark running DGX OS 7,
  not a general ARM/Jetson path.

**Reconciliation note:** this GPU/RAM floor matches the figures already
recorded in this repo's architect skill (RTX 4080 min / 16 GB VRAM, RTX
5080 recommended, 32 GB RAM min / 64 GB recommended); no discrepancy found
between architect's recorded requirements and the live requirements page as of
the 2026-07-10 session's fetch.

## Supported operating systems

These operating-system rows are from the same Isaac Sim 6.0.1 snapshot.

- **Linux:** Ubuntu 22.04 or 24.04.
- **Windows:** Windows 11 only; **Windows 10 is no longer supported.**
- **macOS:** not supported, on any hardware (this is a hard stop, not a
  workaround-able gap).

## Three install paths

**1. Container (recommended for reproducibility).** `nvcr.io/nvidia/
isaac-sim:6.0.1` on NGC: the pinned, versioned path that reproduces
identically between a dev machine and a remote GPU server, echoing the
`environments` skill's general local/remote parity goal. Requires Docker
plus the NVIDIA Container Toolkit on the host (Linux only; see
`environments`' GPU-and-remote reference for that generic setup). See
`examples/docker-run-command.md` for the full invocation.

**2. Pip package.** Python 3.12 is required. The `isaacsim` metapackage
provides optional extras for installing components individually or in
bundles (`isaacsim-kernel`, `isaacsim-app`, `isaacsim-core`, and others).
Install with:

```bash
pip install isaacsim[all,extscache]==6.0.1.0 --extra-index-url https://pypi.nvidia.com
```

(`isaacsim[all,extscache]` pulls every component with extension caching for
faster startup; `isaacsim[BUNDLE]` is a smaller bundled alternative without
that cache.) PyTorch with CUDA should be installed first, into an
activated virtual environment. This is the lighter-weight path for an
already-provisioned Linux/Windows workstation; it still needs the same
GPU/driver floor above, but skips the container layer. Prefer the
container path when this machine must reproduce elsewhere. Source: direct
fetch of the pip
installation page on 2026-07-10.

**3. Workstation / Omniverse Launcher.** A full local GUI install for
interactive scene authoring on a single machine; same GPU/driver/OS floor
applies. Use this only for local authoring; it is not the reproducible path
for a project that also needs to run headless on a remote server.

## Headless + livestream networking

The port and client shape below was re-checked against NVIDIA's current
livestream-client guide on 2026-09-07. Provider-specific exposure and remapping
still belong to that provider's skill.

Running headless: launch with `./runheadless.sh -v` (Linux/container) or
the equivalent Windows batch file; no display is required, which is the
default posture for a remote/cloud GPU box.

Livestreaming the viewport uses WebRTC. The host GPU must support NVENC
(hardware video encoding) to stream at all. Two ports must both be
reachable; opening only one is a common half-working setup:

| Port | Protocol | Purpose |
|---|---|---|
| 49100 | TCP | WebRTC signaling |
| 47998 | UDP | WebRTC media stream |

Two client options connect to a running headless instance:

- **Native desktop client**: the Isaac Sim WebRTC Streaming Client,
  available for Windows, macOS, and Linux (the client itself runs
  cross-platform even though Isaac Sim's server side does not run on
  macOS).
- **Browser client**: a Docker Compose deployment serving a browser-based
  interface, reachable from any Chromium-based browser with no local
  install.

For a remote/cloud target reachable over the public internet (not just a
LAN), set the public IP and ports explicitly at launch so the stream
announces the correct endpoint to remote clients:

```
--/exts/omni.kit.livestream.app/primaryStream/publicIp=<PUBLIC_IP>
--/exts/omni.kit.livestream.app/primaryStream/signalPort=49100
--/exts/omni.kit.livestream.app/primaryStream/streamPort=47998
```

# Remote viewport over WebRTC

Use this card when a headless Isaac Sim instance needs an interactive or
view-only viewport. The observations were measured on a RunPod pod running Go2
on Isaac Lab image 3.0.0-beta2-post1 (driver 580.159.04, Python 3.12.13) on
2026-07-27/28. Isaac Sim owns the streaming protocol; `runpod` owns provider
port exposure, mapping, and proxy mechanics.

## Use a supported client

NVIDIA's current remote-viewport path is WebRTC. In the tested pod,
VNC/VirtualGL connected but could not carry Kit's Vulkan RTX viewport and
showed black or software output. Preserve that as a failure signature for that
stack, not a claim that every remote-desktop product or future renderer fails.

- The native **Isaac Sim WebRTC Streaming Client** is available for supported
  Windows, macOS, and Linux client platforms and suits local or trusted
  networks.
- NVIDIA also documents a separate Docker Compose web client for Chromium-based
  browsers and recommends it for cloud or remote deployments. It runs beside
  Isaac Sim; it is not bundled into the Isaac Sim NGC container.
- The streaming endpoints provide neither authentication nor encryption. Keep
  them on a trusted network or add an authenticated TLS boundary.

Use the current [NVIDIA livestream client guide](https://docs.isaacsim.omniverse.nvidia.com/latest/installation/manual_livestream_clients.html)
for the native and browser deployments.

## Start the stream and prove both paths

- Use the launch command for the installed distribution. Current documented
  forms include `isaac-sim.streaming.sh`, container `runheadless.sh`, and the
  full-streaming pip application; re-check before scripting one.
- WebRTC needs signaling and media. In the current NVIDIA guide these are TCP
  49100 and UDP 47998. Re-check them for the selected release and open both.
- For a public endpoint, pass the public IP and advertised ports through the
  current Kit settings. Do not expose the unauthenticated service directly.
- In the tested RunPod setup, the client used the pod public IP and externally
  mapped ports. Verify current provider behavior with `runpod`; do not copy that
  mapping to another provider.
- A reachable TCP port proves signaling only. Confirm media, a loaded stage,
  and a changing frame before debugging the application.

The current container guide requires host networking for the native WebRTC
path; Docker port publishing is not equivalent. The official web-client Compose
deployment owns its own networking shape.

## Black, grainy, or slow output

- Compare the server render size with the client's selected resolution. The
  native client tested in 2026-07 offered 720p, 1080p, 1440p, and 4K choices; a
  mismatch produced a black screen and a resolution-difference error.
- Pass renderer dimensions through current Kit settings. In the tested Isaac
  Lab launcher, generic `--width` and `--height` flags were not accepted.
- In that client, grainy output tracked render resolution rather than an
  exposed bitrate control. Slow output tracked pod distance. Recheck the
  current client before carrying either diagnosis to another release.

## Separate viewing from control

- Bare Isaac Lab scripts with livestreaming produced video but did not load the
  full editor's input extensions in the tested image, so the stream was
  view-only.
- The full editor was interactive, but its timeline fought the running Isaac
  Lab policy's `env.step()` and invalidated the physics tensor view in that
  image.
- The reliable choices in that trial were headless policy execution with a
  view-only stream, or editor control without policy stepping. Retest this
  limitation on the selected Isaac Sim/Lab pair; do not state it as a permanent
  product constraint.