Deep-dive into AppLauncher

Deep-dive into AppLauncher#

In this tutorial, we will dive into the app.AppLauncher class to configure the simulator using CLI arguments and environment variables (envars). Particularly, we will demonstrate how to use AppLauncher to enable livestreaming and configure the isaacsim.simulation_app.SimulationApp instance it wraps, while also allowing user-provided options.

The AppLauncher is a wrapper for SimulationApp to simplify its configuration. The SimulationApp has many extensions that must be loaded to enable different capabilities, and some of these extensions are order- and inter-dependent. Additionally, there are startup options such as headless which must be set at instantiation time, and which have an implied relationship with some extensions, e.g. the livestreaming extensions. The AppLauncher presents an interface that can handle these extensions and startup options in a portable manner across a variety of use cases. To achieve this, we offer CLI and envar flags which can be merged with user-defined CLI args, while passing forward arguments intended for SimulationApp.

The Code#

The tutorial corresponds to the launch_app.py script in the scripts/tutorials/00_sim directory.

Code for launch_app.py
  1# Copyright (c) 2022-2025, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md).
  2# All rights reserved.
  3#
  4# SPDX-License-Identifier: BSD-3-Clause
  5
  6# Copyright (c) 2022-2025, The Isaac Lab Project Developers.
  7# All rights reserved.
  8#
  9# SPDX-License-Identifier: BSD-3-Clause
 10
 11"""
 12This script demonstrates how to run IsaacSim via the AppLauncher
 13
 14.. code-block:: bash
 15
 16    # Usage
 17    ./isaaclab.sh -p scripts/tutorials/00_sim/launch_app.py
 18
 19"""
 20
 21"""Launch Isaac Sim Simulator first."""
 22
 23
 24import argparse
 25
 26from isaaclab.app import AppLauncher
 27
 28# create argparser
 29parser = argparse.ArgumentParser(description="Tutorial on running IsaacSim via the AppLauncher.")
 30parser.add_argument("--size", type=float, default=1.0, help="Side-length of cuboid")
 31# SimulationApp arguments https://docs.omniverse.nvidia.com/py/isaacsim/source/isaacsim.simulation_app/docs/index.html?highlight=simulationapp#isaacsim.simulation_app.SimulationApp
 32parser.add_argument(
 33    "--width", type=int, default=1280, help="Width of the viewport and generated images. Defaults to 1280"
 34)
 35parser.add_argument(
 36    "--height", type=int, default=720, help="Height of the viewport and generated images. Defaults to 720"
 37)
 38
 39# append AppLauncher cli args
 40AppLauncher.add_app_launcher_args(parser)
 41# parse the arguments
 42args_cli = parser.parse_args()
 43# launch omniverse app
 44app_launcher = AppLauncher(args_cli)
 45simulation_app = app_launcher.app
 46
 47"""Rest everything follows."""
 48
 49import isaaclab.sim as sim_utils
 50
 51
 52def design_scene():
 53    """Designs the scene by spawning ground plane, light, objects and meshes from usd files."""
 54    # Ground-plane
 55    cfg_ground = sim_utils.GroundPlaneCfg()
 56    cfg_ground.func("/World/defaultGroundPlane", cfg_ground)
 57
 58    # spawn distant light
 59    cfg_light_distant = sim_utils.DistantLightCfg(
 60        intensity=3000.0,
 61        color=(0.75, 0.75, 0.75),
 62    )
 63    cfg_light_distant.func("/World/lightDistant", cfg_light_distant, translation=(1, 0, 10))
 64
 65    # spawn a cuboid
 66    cfg_cuboid = sim_utils.CuboidCfg(
 67        size=[args_cli.size] * 3,
 68        visual_material=sim_utils.PreviewSurfaceCfg(diffuse_color=(1.0, 1.0, 1.0)),
 69    )
 70    # Spawn cuboid, altering translation on the z-axis to scale to its size
 71    cfg_cuboid.func("/World/Object", cfg_cuboid, translation=(0.0, 0.0, args_cli.size / 2))
 72
 73
 74def main():
 75    """Main function."""
 76
 77    # Initialize the simulation context
 78    sim_cfg = sim_utils.SimulationCfg(dt=0.01, device=args_cli.device)
 79    sim = sim_utils.SimulationContext(sim_cfg)
 80    # Set main camera
 81    sim.set_camera_view([2.0, 0.0, 2.5], [-0.5, 0.0, 0.5])
 82
 83    # Design scene by adding assets to it
 84    design_scene()
 85
 86    # Play the simulator
 87    sim.reset()
 88    # Now we are ready!
 89    print("[INFO]: Setup complete...")
 90
 91    # Simulate physics
 92    while simulation_app.is_running():
 93        # perform step
 94        sim.step()
 95
 96
 97if __name__ == "__main__":
 98    # run the main function
 99    main()
100    # close sim app
101    simulation_app.close()

The Code Explained#

Adding arguments to the argparser#

AppLauncher is designed to be compatible with custom CLI args that users need for their own scripts, while still providing a portable CLI interface.

In this tutorial, a standard argparse.ArgumentParser is instantiated and given the script-specific --size argument, as well as the arguments --height and --width. The latter are ingested by SimulationApp.

The argument --size is not used by AppLauncher, but will merge seamlessly with the AppLauncher interface. In-script arguments can be merged with the AppLauncher interface via the add_app_launcher_args() method, which will return a modified ArgumentParser with the AppLauncher arguments appended. This can then be processed into an argparse.Namespace using the standard argparse.ArgumentParser.parse_args() method and passed directly to AppLauncher for instantiation.

import argparse

from isaaclab.app import AppLauncher

# create argparser
parser = argparse.ArgumentParser(description="Tutorial on running IsaacSim via the AppLauncher.")
parser.add_argument("--size", type=float, default=1.0, help="Side-length of cuboid")
# SimulationApp arguments https://docs.omniverse.nvidia.com/py/isaacsim/source/isaacsim.simulation_app/docs/index.html?highlight=simulationapp#isaacsim.simulation_app.SimulationApp
parser.add_argument(
    "--width", type=int, default=1280, help="Width of the viewport and generated images. Defaults to 1280"
)
parser.add_argument(
    "--height", type=int, default=720, help="Height of the viewport and generated images. Defaults to 720"
)

# append AppLauncher cli args
AppLauncher.add_app_launcher_args(parser)
# parse the arguments
args_cli = parser.parse_args()
# launch omniverse app
app_launcher = AppLauncher(args_cli)
simulation_app = app_launcher.app

The above only illustrates only one of several ways of passing arguments to AppLauncher. Please consult its documentation page to see further options.

Understanding the output of –help#

While executing the script, we can pass the --help argument and see the combined outputs of the custom arguments and those from AppLauncher.

./isaaclab.sh -p scripts/tutorials/00_sim/launch_app.py --help

[INFO] Using python from: /isaac-sim/python.sh
[INFO][AppLauncher]: The argument 'width' will be used to configure the SimulationApp.
[INFO][AppLauncher]: The argument 'height' will be used to configure the SimulationApp.
usage: launch_app.py [-h] [--size SIZE] [--width WIDTH] [--height HEIGHT] [--headless] [--livestream {0,1,2}]
                     [--enable_cameras] [--verbose] [--experience EXPERIENCE]

Tutorial on running IsaacSim via the AppLauncher.

options:
-h, --help            show this help message and exit
--size SIZE           Side-length of cuboid
--width WIDTH         Width of the viewport and generated images. Defaults to 1280
--height HEIGHT       Height of the viewport and generated images. Defaults to 720

app_launcher arguments:
--headless            Force display off at all times.
--livestream {0,1,2}
                      Force enable livestreaming. Mapping corresponds to that for the "LIVESTREAM" environment variable.
--enable_cameras      Enable cameras when running without a GUI.
--verbose             Enable verbose terminal logging from the SimulationApp.
--experience EXPERIENCE
                      The experience file to load when launching the SimulationApp.

                      * If an empty string is provided, the experience file is determined based on the headless flag.
                      * If a relative path is provided, it is resolved relative to the `apps` folder in Isaac Sim and
                        Isaac Lab (in that order).

This readout details the --size, --height, and --width arguments defined in the script directly, as well as the AppLauncher arguments.

The [INFO] messages preceding the help output also reads out which of these arguments are going to be interpreted as arguments to the SimulationApp instance which the AppLauncher class wraps. In this case, it is --height and --width. These are classified as such because they match the name and type of an argument which can be processed by SimulationApp. Please refer to the specification for such arguments for more examples.

Using environment variables#

As noted in the help message, the AppLauncher arguments (--livestream, --headless) have corresponding environment variables (envar) as well. These are detailed in isaaclab.app documentation. Providing any of these arguments through CLI is equivalent to running the script in a shell environment where the corresponding envar is set.

The support for AppLauncher envars are simply a convenience to provide session-persistent configurations, and can be set in the user’s ${HOME}/.bashrc for persistent settings between sessions. In the case where these arguments are provided from the CLI, they will override their corresponding envar, as we will demonstrate later in this tutorial.

These arguments can be used with any script that starts the simulation using AppLauncher, with one exception, --enable_cameras. This setting sets the rendering pipeline to use the offscreen renderer. However, this setting is only compatible with the isaaclab.sim.SimulationContext. It will not work with Isaac Sim’s isaacsim.core.api.simulation_context.SimulationContext class. For more information on this flag, please see the AppLauncher API documentation.

The Code Execution#

We will now run the example script:

LIVESTREAM=2 ./isaaclab.sh -p scripts/tutorials/00_sim/launch_app.py --size 0.5

This will spawn a 0.5m3 volume cuboid in the simulation. No GUI will appear, equivalent to if we had passed the --headless flag because headlessness is implied by our LIVESTREAM envar. If a visualization is desired, we could get one via Isaac’s WebRTC Livestreaming. Streaming is currently the only supported method of visualization from within the container. The process can be killed by pressing Ctrl+C in the launching terminal.

result of launch_app.py

Now, let’s look at how AppLauncher handles conflicting commands:

LIVESTREAM=0 ./isaaclab.sh -p scripts/tutorials/00_sim/launch_app.py --size 0.5 --livestream 2

This will cause the same behavior as in the previous run, because although we have set LIVESTREAM=0 in our envars, CLI args such as --livestream take precedence in determining behavior. The process can be killed by pressing Ctrl+C in the launching terminal.

Finally, we will examine passing arguments to SimulationApp through AppLauncher:

LIVESTREAM=2 ./isaaclab.sh -p scripts/tutorials/00_sim/launch_app.py --size 0.5 --width 1920 --height 1080

This will cause the same behavior as before, but now the viewport will be rendered at 1920x1080p resolution. This can be useful when we want to gather high-resolution video, or we can specify a lower resolution if we want our simulation to be more performant. The process can be killed by pressing Ctrl+C in the launching terminal.