Launcher

Launcher is a process management and configuration tool that lets you launch, monitor and shutdown hundreds of processes across several machines in a controlled manner, defined through launch configurations.

Most of the action happens behind the scene. Once configured, interaction with the application is mainly done via the RTI control panel.

voice-vcs Launcher control card in the RTI control panel

voice-vcs Launcher UI on Windows. On MacOS and Linux, the application has no graphical user interface.

In evaluation mode, the Launcher is limited to three launch configurations, each of which is limited to three launch items.

Installing

Download the package (Windows, MacOS or Linux). The install process is similar to that of the RTI.

Once installed, you’ve got Launcher in your start menu (Windows), and a launcher command to play with in your favorite command-line shell (Windows, MacOS, Linux).

Configuration

Launch configurations are YAML files that describe which processes belong to a runnable system and how the Launcher should manage them. A file can contain one configuration or several named configurations. Each configuration may define:

  • items — the processes to manage, with actions for setup, launch, shutdown, and cleanup
  • parameters — values selected by the operator when launching
  • variables and environment — values shared by actions and items
  • remote actions — scripts or programs an operator can run independently
  • checks and dependencies — conditions used to determine whether an item is ready and when another item may start

The smallest useful configuration names an item and says what to run:

Demo:
  description: Start the demo simulator
  parameters:
    station:
      label: Station name
      default_value: simulator-1
  items:
    Simulator:
      launch:
        run: simulator
        arguments: --station

Variables and parameter values can be substituted using `` in commands, arguments, scripts, and other supported fields. Configuration- and item-level directories and environment variables provide defaults that a specific action can override.

For larger systems, configurations and items can inherit shared definitions. Items can be assigned to a host or station, allowing Launcher instances on several computers to cooperate while each starts only the processes assigned to it. Health checks, wait_for dependencies, automatic restart, and resource locks can be added when startup order or process availability needs tighter control.

Run launcher --example to print a configuration containing the available fields and their default values:


# This is an example launch configuration file.
# It's not pretty but shows all available options and defaults.
#
# You can also have multiple named configurations in one file, e.g:
# configuration one:
#   items:
#     ...
# configuration numero dos:
#   items:
#     ...
#
# Launch actions: setup, launch, shutdown, cleanup

version: 
description: ''
inherit: []
abstract: false
directory: 
environment:
  ENV_VAR_A: Environment variable
variables:
  variable_a: Variable - can be accessed using  in e.g. 'run' and 'script' field of launch actions
parameters:
  parameter_a:
    label: Parameter A
    description: This shows up in the launcher UI
    type: ''
    default_value: ''
    required: false
items:
  My first launch item:
    inherit: 
    abstract: false
    directory: 
    environment:
      ENV_VAR_A: This overrides the configuration environment variable for this item
    variables:
      variable_a: This overrides the configuration variable for this item
    setup: 
    launch:
      directory: 
      run: myprocess.exe
      arguments: 
      script:
      - echo A
      - "echo B # note that 'run/arguments' and 'script' are mutually exclusive"
      interpreter: bash
      window: Normal
      console_window: false
      wait: false
      delay: 0
      timeout: 0
      output_channel: 
      output_file: 
      environment:
        ENV_VAR_A: This overrides the item environment variable for this launch action
      variable_substitution: true
      associate_process_time: 0
    shutdown: 
    cleanup: 
    host: 
    station: 
    link_url: ''
    link_title: ''
    link_description: ''
    abbreviation: ''
    check_http:
      url: 
      interval: 3000
      grace_period: 3000
      timeout: 0
    check_client:
      application: 
      client_id: 
      state: 
      interval: 1000
      grace_period: 3000
      timeout: 0
    check_script: 
    check_subscribe: 
    wait_for: []
    should_run: false
    auto_restart: 0
    min_lifetime: 0
    kill_delay: 0
    kill: false
    restart_delay: 0
    associate_process_name: 
    resources: 
remote:
  remote_action_a:
    title: Lamp on
    description: Turn on the lamp
    disabled_when_launched: false
    offset: false
    icon: 
    sort_weight: 0
    host: 
    station: 
    directory: 
    run: 
    arguments: 
    script:
    - lampctl on
    interpreter: bash
    window: Normal
    console_window: false
    wait: false
    delay: 0
    timeout: 0
    output_channel: 
    output_file: 
    environment: 
    variable_substitution: true
    associate_process_time: 0
settings: 
concurrent: false
lock: []
fast_time:
  enabled: false
  time_step: 1
  max_time: -1
  max_real_time: -1
  step_timeout: 10
setup:
  directory: 
  run: 
  arguments: 
  script:
  - echo Runs before the items are launched
  interpreter: bash
  window: Normal
  console_window: false
  wait: false
  delay: 0
  timeout: 60000
  output_channel: 
  output_file: 
  environment: 
  variable_substitution: true
  associate_process_time: 0
launch: 
shutdown: 
cleanup: 
postprocess:

Command Line 

launcher [options] [paths...] [launch [configuration [param=value...]]...] [run [run-options] scenario [param=value...]...]

Configuration files are named *.launch.yml. Paths to files or directories go before any subcommand. Without paths, the Launcher uses LAUNCHER_PATH if set, otherwise it searches the current directory up to three levels deep. Explicitly given directories are searched without a depth limit.

Started without a subcommand, the Launcher just advertises its configurations and waits for launch commands from the RTI. That’s how it normally runs as a background service:

launcher                            # configurations in the current directory
launcher ~/my-system                # configurations in a specific directory
launcher -r ws://rti-host:8000 -S station-2 /opt/my-system

Useful options: -r/--rti <url>, -H/--host, -S/--station, -f/--federation, -o/--offline (don’t connect to the RTI), -x/--exit (exit when all processes have exited), -l/--list, -q/--quiet, -v/--verbose. See launcher --help for the full list.

Launching on startup

The launch subcommand launches one or more configurations right away. Parameters follow the configuration they belong to. If there is only one configuration, its name can be left out.

launcher launch                                     # the only configuration there is
launcher launch Demo station=simulator-2
launcher launch Base Demo station=simulator-2      # several configurations, in turn
launcher -ox launch Demo                           # offline, exit when processes are done

Running scenarios

The run subcommand runs scenarios in sequence. For each one, it loads the scenario, starts it, waits for it to end and runs any postprocess actions. When all scenarios are done, it shuts down and exits. Put run after launch to start a system and run scenarios against it in one command, for example in CI or batch runs. Use run on its own to run scenarios against a system launched elsewhere.

launcher launch Demo run scenario1 speed=fast scenario2
launcher run --fast -m 3600 scenario1              # fast-time, max one hour of simulation time
launcher run ref:baseline scenario2 scenario3      # record baseline as reference log, compare the rest

If a fast-time controller is part of the configuration or connected to the federation, scenarios run in fast time. Otherwise they run in real time. --fast makes the Launcher host a controller itself when none is found. --real-time or --time-scale <scale> forces real time. Fast-time settings such as -t/--time-step, -m/--max-time and -T/--step-timeout override the controller’s configuration.

Use --error <mode> to choose what happens when a client reports an error: fail (default), retry (retry the scenario once), continue (keep going but fail at the end) or ignore. The exit code is non-zero if a launch or a run fails, so the command works well in scripts.

Usage Examples

Once a Launcher is running, launch configurations are normally selected from the RTI control panel. The same operations are available through the CLI, which is convenient for scripts and testing:

# List configurations advertised by connected Launchers
rti launch --list

# Launch a configuration with a parameter value
rti launch Demo --parameter station=simulator-2

# Stop the processes belonging to that configuration
rti shutdown Demo

# List remote actions, then run one by name
rti remote
rti remote reset_hardware

When several Launchers are connected, pass --client <client-id> to address a specific Launcher. Individual items can be controlled with rti launch item <name> and rti launch item <name> stop.

Copyright © Inhumate AB 2026