Holoscan CLI - Run Command

holoscan run - simplifies running a packaged Holoscan application by reducing the number of arguments required compared to docker run. In addition, it follows the guidelines of HAP specification when launching your packaged Holoscan application.

Warning

When running a packaged Holoscan application on Kubernetes or other service providers, running Docker with non root user, and running Holoscan CLI run command where the logged-on user’s ID is different, ensure to specify the USER ID that is used when building the application package.

For example, include the securityContext when running a Holoscan packaged application with UID=1000 using Argo:

Copy
Copied!

            
            spec:
  securityContext:
    runAsUser: 1000
    runAsNonRoot: true

Synopsis

holoscan run [--help|-h] [--log-level|-l {DEBUG,INFO,WARN,ERROR,CRITICAL}] [--address ADDRESS] [--driver] [--input|-i INPUT] [--output|-o OUTPUT] [--fragments|-f FRAGMENTS] [--worker] [--worker-address WORKER_ADDRESS] [--config CONFIG] [--network|-n NETWORK] [--nic NETWORK_INTERFACE] [--use-all-nics] [--render|-r] [--quiet|-q] [--shm-size][--terminal] [--device] [--gpu] [--uid UID] [--gid GID]image:[tag]

Examples

To run a packaged Holoscan application:

Copy
Copied!

            
            holoscan run -i /path/to/my/input -o /path/to/application/generated/output my-application:1.0.1

Positional Arguments

`image:[tag]`

Name and tag of the Docker container image to execute.

Flags

`[--address ADDRESS]`

Address ([<IP or hostname>][:<port>]) of the App Driver. If not specified, the App Driver uses the default host address (0.0.0.0) with the default port number (8765).

For example:

Copy
Copied!

            
            --address my_app_network
--address my_app_network:8765

Note

Ensure that the IP address is not blocked and the port is configured with the firewall accordingly.

`[--driver]`

Run the App Driver on the current machine. Can be used together with the [--worker] option to run both the App Driver and the App Worker on the same machine.

`[--input|-i INPUT]`

Specifies a directory path with input data for the application to process. When specified, a directory mount is set up to the value defined in the environment variable HOLOSCAN_INPUT_PATH.

Note

Ensure that the directory on the host is accessible by the current user or the user specified with –uid.

Note

Use the host system path when running applications inside Docker (DooD).

`[--output|-o OUTPUT]`

Specifies a directory path to store application-generated artifacts. When specified, a directory mount is set up to the value defined in the environment variable HOLOSCAN_OUTPUT_PATH.

Note

Ensure that the directory on the host is accessible by the current user or the user specified with –uid.

`[--fragments|-f FRAGMENTS]`

A Comma-separated names of the fragments to be executed by the App Worker. If not specified, only one fragment (selected by the App Driver) will be executed. all can be used to run all the fragments.

`[--worker]`

Run the App Worker.

`[--worker-address WORKER_ADDRESS]`

The address ([<IP or hostname>][:<port>]) of the App Worker. If not specified, the App Worker uses the default host address (0.0.0.0) with a randomly chosen port number between 10000 and 32767 that is not currently in use. This argument automatically sets the HOLOSCAN_UCX_SOURCE_ADDRESS environment variable if the worker address is a local IP address. Refer to Environment Variables for Distributed Applications for details.

For example:

Copy
Copied!

            
            --worker-address my_app_network
--worker-address my_app_network:10000

Note

Ensure that the IP address is not blocked and the port is configured with the firewall accordingly.

`[--config CONFIG]`

Path to the application configuration file. If specified, it overrides the embedded configuration file found in the environment variable HOLOSCAN_CONFIG_PATH.

`[--network|-n NETWORK]`

The Docker network that the application connects to for communicating with other containers. The Runner use the host network by default if not specified. Otherwise, the specified value is used to create a network with the bridge driver.

For advanced usages, first create a network using docker network create and pass the name of the network to the --network option. Refer to Docker Networking documentation for additional details.

`[--nic NETWORK_INTERFACE]`

Name of the network interface to use with a distributed multi-fragment application. This option sets UCX_NET_DEVICES environment variable with the value specified and is required when running a distributed multi-fragment application across multiple nodes. See UCX Network Interface Selection for details.

`[--use-all-nics]`

When set, this option allows UCX to control the selection of network interface cards for data transfer. Otherwise, the network interface card specified with ‘–nic’ is used. This option sets the environment variable UCX_CM_USE_ALL_DEVICES to y. (default: False)

When this option is not set, the CLI runner always sets UCX_CM_USE_ALL_DEVICES to n.

`[--render|-r]`

Enable graphic rendering from your application. Defaults to False.

`[--quiet|-q]`

Suppress the STDOUT and print only STDERR from the application. Defaults to False.

`[--shm-size]`

Sets the size of /dev/shm. The format is <number(int,float)>[MB|m|GB|g|Mi|MiB|Gi|GiB]. Use config to read the shared memory value defined in the app.json manifest. By default, the container is launched using --ipc=host with host system’s /dev/shm mounted.

`[--terminal]`

Enters terminal with all configured volume mappings and environment variables.

`[--device]`

Map host devices into the application container.

By default, the CLI searches the /dev/ path for devices unless the specified string starts with /.

For example:

Copy
Copied!

            
            # mount all AJA capture cards
--device ajantv*
# mount AJA capture card 0 and 1
--device ajantv0 ajantv1
# mount V4L2 video device 1 and AJAX capture card 2
--device video1 --device /dev/ajantv2

Warning

When using the --device option, append -- after the last item to avoid misinterpretation by the CLI. E.g.

Copy
Copied!

            
            holoscan run --render --device ajantv0 video1 -- my-application-image:1.0

`[--gpu]`

Override the value of the NVIDIA_VISIBLE_DEVICES environment variable with the default value set to the value defined in the package manifest file or all if undefined.

Refer to the GPU Enumeration page for all available options.

Note

The default value is nvidia.com/igpu=0 when running a HAP built for iGPU on a system with both iGPU and dGPU,

Note

A single integer value translates to the device index, not the number of GPUs.

`[--uid UID]`

Run the application with the specified user ID (UID). Defaults to the current user’s UID.

`[--gid GID]`

Run the application with the specified group ID (GID). Defaults to the current user’s GID.

Note

The Holoscan Application supports various environment variables for configuration. Refer to Environment Variables for Distributed Applications for details.