Omniverse Client Library#

This is the library that all Omniverse clients should use to communicate with Omniverse servers.

Documentation#

The latest documentation can be found here

Samples#

The Omniverse Connect sample is available through GitHub.

Documentation for the samples can be found here

Getting#

You can get the latest build from Packman. There are seperate packages for each platform.

They are all named: omni_client_library.{platform}

platform is one of:

  • windows-x86_64

  • manylinux_2_35_x86_64

  • manylinux_2_35_aarch64

All packages use the same versioning scheme: {major}.{minor}.{patch}

For example:

<project toolsVersion="5.0">
  <dependency name="omni_client_library" linkPath="_deps/omni_client_library">
    <package name="omni_client_library.windows-x86_64" version="2.10.0" />
  </dependency>
</project>

Hub#

If Hub is installed via Launcher, it will be used by default. If Hub is not installed, we will fall back to the previous behavior. This will change at some point and Hub will be required.

There are some environment variables to control this:

  • OMNICLIENT_HUB_MODE: Either “disabled” (don’t use Hub), “exclusive” (launch Hub at library initialization & shut down Hub at library shutdown or process termination), or “shared” (use Hub if it’s running, launch if it’s not, never shut it down).

  • OMNICLIENT_HUB_EXE: This is the Hub executable to launch. Defaults to Hub next to your application for exclusive mode or the global Hub from launcher for shared mode.

  • OMNICLIENT_HUB_CACHE_DIR: Use Hub with this cache directory. This is required for exclusive mode, optional for shared mode (defaults to the cache path from omniverse.toml)

Newer Hub versions are backwards compatible to older client-library versions, but older Hub versions are not compatible with newer client-library versions. If you install Hub via Launcher, Hub is guaranteed to be compatible with all applications available on Launcher.

To make it easier to install a compatible Hub executable version if Launcher is not available, client-library packages v2.30.0 and higher are shipped with an additional file deps/public-redist.packman.xml which specifies a compatible Hub version. You can use that file to make the Hub executable available by adding a few lines to your projects packman dependencies. For example:

  <!-- Existing dependency to the client-library -->
  <dependency name="omni_client_library" linkPath="../_build/target-deps/omni_client_library">
    <package name="omni_client_library.${platform}" version="2.28.1" />
  </dependency>
  <!-- Add these lines to make the correct version of Hub available -->
  <import path="../_build/target-deps/omni_client_library/deps/public-redist.packman.xml"/>
  <dependency name="omni-hub" linkPath="../_build/target-deps/omni-hub"/>
  <!-- The Hub executable is now available in ../_build/target-deps/omni-hub/target/release/hub resp. hub.exe -->

Once the Hub executable is available in a known location, you can use that location for OMNICLIENT_HUB_EXE.

Using#

URLs#

Almost all the functions take a URL as the parameter. Currently the library supports a few URLs types:

  1. omniverse://server:port/path

  2. omni://server:port/path

  3. http://website/stuff/?omniverse://server:port/path

  4. file:///c:/local%20path

  5. c:\local path

  6. https://www.nvidia.com

The port is optional.

For the 3rd case, we ignore everything before “omniverse:”

file: URLs must be in the correct file URI format as described here: https://en.wikipedia.org/wiki/File_URI_scheme

Notably this means special characters must be percent-encoded (and there should be either one or three slashes, not two!)

The 5th type is not a URL at all, but the library understands certain “raw” local file paths. Note that although this is mostly reliable on Windows (because drive letters make it pretty obvious), is is very unreliable on Linux because a path which starts with “/” could be a reference to another path on the same server. For this reason, always prefer using “file:” URLs over raw file paths.

Aliases#

You can set aliases for URLs by adding a section to the global omniverse.toml file. For example:

[aliases]
"nvidia:"="http://www.nvidia.com/"

The above alias would turn “nvidia:omniverse” into “http://www.nvidia.com/omniverse”

You can also set aliases at runtime with the “set_alias” function in Python or “omniClientSetAlias” in C.

Basics#

Include “OmniClient.h” and you can the basic functions like omniClientList, omniClientRead, etc. without any extra work. Even calling omniClientInitialize and omniClientShutdown is not strictly required (though encouraged, because it enables extra checks).

Providers#

File#

File provider implements the “file:” scheme and support for “raw” paths like “C:\file”

Nucleus#

Nucleus provider implements the “omniverse:” scheme for loading files from an Omniverse Nucleus server. This is the only provider which supports “live mode”

Nucleus Configuration#

The Nucleus provider can be configured using the following environment variables:

  • OMNI_MULTIPART_CHUNK_SIZE_MB: Sets the chunk size in megabytes for multipart uploads.

  • OMNI_DEPLOYMENT: Specifies the deployment type for Nucleus connections. Defaults to “external”.

Nucleus Authentication#

The Nucleus provider supports multiple authentication methods in the following priority order:

  1. Application Authentication Callbacks - Applications can register callbacks using omniClientRegisterAuthCallback() to provide custom authentication credentials (tokens, username/password, or abort)

  2. Environment Variables - Override authentication using OMNI_USER/OMNI_USERNAME and OMNI_PASS/OMNI_PASSWORD to force specific credentials

  3. Cached Tokens - Previously stored authentication tokens from successful logins (used unless overridden by environment variables)

  4. Device Flow - Interactive sign-in without opening a local browser when omniClientRegisterAuthDeviceFlowCallback() is registered, or when OMNICLIENT_NO_BROWSER is set to 1. If no device-flow callback is registered, the library logs the verification URL and user code at info level.

  5. Browser Authentication - Interactive sign-in by launching a web browser when device flow is not used. On Linux, the browser launch is skipped when no display server is detected (DISPLAY/WAYLAND_DISPLAY unset). On all platforms, if the browser command fails the library automatically falls back to device flow.

HTTP(S)#

HTTP provider supports a variety of HTTP/HTTPS based URLs.

The HTTP provider is intended for read-only access to static content. Results from list() and stat() operations are cached on the client side. Changes to remote objects after they have been fetched, or new objects added while the application is running, will not be reflected until the cache is cleared or the application is restarted.

Note: This caching behavior applies to all HTTP-based providers, including Azure and S3/CloudFront configurations. Because these providers are built on top of the HTTP provider, they inherit the same client-side caching semantics for list() and stat() results.

Clearing the list/stat cache: Call omniClientClearListCache (C) or clear_list_cache (Python) with any URL served by the provider whose cache you want to clear. Subsequent list/stat calls will then see updated results. The function returns true if the cache was cleared, false if the URL is invalid or the provider has no list cache.

// C: clear cache for this provider so next list/stat sees fresh data
omniClientClearListCache("https://example.com/container");

# Python
omni.client.clear_list_cache("https://example.com/container")

HTTP#

Plain old HTTP/HTTPS URLs support stat() via HTTP HEAD verb and readFile() via HTTP GET verb.

Configuration#

HTTP providers can be configured using the following environment variables:

  • OMNICLIENT_HTTP_VERBOSE: Set to “1” to enable verbose logging, displaying additional HTTP information in the logs.

  • OMNICLIENT_HTTP_TIMEOUT: Specifies the number of seconds the transfer speed must remain below 1 byte per second before the operation is considered too slow and aborted. Defaults to 60.

  • OMNICLIENT_HTTP_RETRIES: Defines the number of times a failed operation will be retried before being aborted. Defaults to 8.

  • OMNICLIENT_HTTP_PROXY_SSL_VERIFYHOST: Controls SSL host verification for HTTP proxy connections. Defaults to 1 (enabled).

  • OMNICLIENT_HTTP_PROXY_SSL_VERIFYPEER: Controls SSL peer verification for HTTP proxy connections. Defaults to 1 (enabled).

  • OMNICLIENT_HTTP_CONCURRENT_OPS: Limits the number of concurrent HTTP operations. Defaults to 20.

These configuration options apply to all HTTP and HTTP-based providers like HTTP, HTTPS, Azure, S3, CloudFront, etc.

Azure#

Azure URLs are identified by the host ending in “.blob.core.windows.net”

“Container Public” containers support stat, list, and readFile operations. “Blob Public” containers support stat and readFile operations (but not list, unless you specified a SAS token). “Private” containers support stat, list, and readFile operations if you specified a SAS token.

A SAS token can be specified in omniverse.toml like this:

[azure."{account}.blob.core.windows.net/{container}"]
sasToken="{sas-token}"

S3#

S3 URLs currently support stat(), list(), and readFile() operations. S3 URLs can be identified in one of three ways:

  • The URL ends in .amazonaws.com

  • The URL ends in .cloudfront.net

  • The URL has a S3 configuration in the TOML config file. Useful for S3 buckets with custom domain name.

If the bucket requires access tokens or has a CloudFront distribution, omniverse.toml can be used to configure per bucket.

Example S3 section in omniverse.toml:

[s3]
[s3."{hostname}"]
bucket = "{bucket}"
region = "{region}"
accessKeyId = "{access-key-id}"
secretAccessKey = "{secret-access-key}"
cloudfront = "http(s)://{cloudfront-distribution-id}.cloudfront.net" # optional
cloudfrontList=false # optional

Hostname must be the full host, such as “bucket.s3.region.amazonaws.com”. If you have a custom DNS entry for you bucket, you can use that instead. Note we do not support the older “path style” of S3 URLs such as “s3.region.amazonaws.com/bucket”.

Note on using CloudFront#

The preferred way to use CloudFront is to use CloudFront URLs directly in your application. This requires additional CloudFront configuration as outlined below. When using CloudFront URLs directly, the cloudfront and cloudfrontList options are ignored. These are only used if you are using S3 URLs and want use CloudFront implicitly (which can be slightly more confusing to the end user as they may not know that CloudFront is being used).

Server-Side CloudFront Configuration#

CloudFront configuration can also be specified via a .cloudfront.toml file in the root of the S3 bucket.

Example CloudFront configuration in .cloudfront.toml:

cloudfront="http://dcb18d6mfegct.cloudfront.net"
cloudfrontList=false

This configuration is also optional. It is parsed before any configuration in omniverse.toml, so one can always override this server-side configuration with their local configuration.

API Operations when using CloudFront#

If cloudfrontList is set to true or you are using CloudFront URLs, list() and stat() operations will also go though cloudfront, but requires further AWS CloudFront configuration. By default CloudFront does not pass any query strings. The following HTTP query parameters have to be forwarded from CloudFront to S3 on the backend:

  1. list-type

  2. delimiter

  3. prefix

  4. continuation-token

See https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/QueryStringParameters.html for information on how to do this.

OmniStorage#

The OmniStorage provider is the new, in progress, provider for connecting to the new Omniverse Storage Services.

Authentication#

With discovery-based configuration (OMNI_STORAGE_DISCOVERY), interactive authentication defaults to an authorization-code flow in a local browser (redirect to the identity provider, then back to the app).

Device flow (RFC 8628) is used instead when either:

  • An application registers omniClientRegisterAuthDeviceFlowCallback(), or

  • OMNICLIENT_NO_BROWSER is set to 1.

The identity provider’s OpenID configuration must include device_authorization_endpoint for device flow to succeed (whether selected directly or via fallback). If it is missing, interactive authentication fails with a clear warning.

If neither condition is met, browser-based authentication is attempted first. On Linux, the browser launch is skipped when no display server is detected (DISPLAY/WAYLAND_DISPLAY unset). On all platforms, if the browser command fails the library automatically falls back to device flow.

If no device-flow callback is registered, the library logs the verification URL and user code at info level so an operator can complete sign-in on another machine.

Environment Variables#

Discovery Mode Configuration#

  • OMNI_STORAGE_DISCOVERY: Set to a storage service discovery URL to enable OpenID Connect authentication flow.

  • OMNI_STORAGE_CLIENT_NAME: Sets the client name for retrieving the OpenID Connect configuraton from discovery. Defaults to “client_library”.

Manual Configuration (used when OMNI_STORAGE_DISCOVERY is not set)#

  • OMNI_STORAGE_HOST: Storage server hostname. Must be explicitly set - no default value.

  • OMNI_STORAGE_PORT: Storage server port. Defaults to “50051”.

  • OMNI_STORAGE_SECURE: Set to “1” to enable secure connections. Defaults to true when port is 443, false otherwise.

  • OMNI_STORAGE_AUTHORIZATION: Sets the Authorization header (e.g., “Bearer {token}”).

  • OMNI_STORAGE_FUNCTION_ID: Sets the Function-ID header for NVCF.

  • OMNI_STORAGE_FUNCTION_VERSION_ID: Sets the Function-Version-ID header for NVCF.

Timeout & Retry Configuration#

  • OMNI_STORAGE_DEADLINE: Sets the deadline in seconds for OmniStorage operations. Defaults to 0 (no deadline).

  • OMNI_STORAGE_RETRY_MAX: Maximum number of retry attempts. Defaults to 10.

  • OMNI_STORAGE_RETRY_MAX_DELAY_MS: Maximum delay between retries in milliseconds. Defaults to 5000.

  • OMNI_STORAGE_RETRY_BASE_MS: Base delay between retries in milliseconds. Defaults to 10.

  • OMNI_STORAGE_RETRY_FORMULA: Retry formula algorithm (defaults to 2):

    • 0: Constant delay (delay = retryBaseMs)

    • 1: Linear delay (delay = retryBaseMs × retryCount)

    • 2: Exponential delay (delay = retryBaseMs × 2^retryCount)

  • OMNI_STORAGE_RETRY_JITTER: Jitter method for retry delays (defaults to 2):

    • 0: No jitter (delay = calculated delay)

    • 1: Full jitter (delay = random(0, calculated delay))

    • 2: Equal jitter (delay = random(calculated delay/2, calculated delay))

General Configuration#

The following environment variables control general library behavior:

  • OMNICLIENT_NO_BROWSER: Set to 1 to skip browser-based authentication and use device flow directly (Nucleus and OmniStorage discovery auth). Without this variable, the library attempts to launch a browser first and falls back to device flow automatically if the launch fails. Optional UI: register omniClientRegisterAuthDeviceFlowCallback(); otherwise the verification URL and user code are logged at info level.

  • OMNICLIENT_PROVIDERS: Comma-separated list of provider names to register. When set, only these providers are registered (plus anon, which is always registered last as a fallback no-op). When unset, all providers are registered. Provider names: file, http, nucleus, storage.

  • OMNICLIENT_ALLOW_VERBOSE_LIVE: Set to “1” to allow verbose logging for live updates.

  • OMNI_CONFIG_PATH: Specifies the path to the configuration directory.

Testing#

The following environment variables are used for testing purposes:

  • OMNI_TEST_NO_BROWSER: Set to “1” to disable browser authentication during testing.

  • OMNI_TEST_BYPASS_LISTCACHE: Set to “1” to bypass list cache during testing.

  • OMNI_TEST_USER: Test username for authentication testing.

  • OMNI_TEST_PASS: Test password for authentication testing.

  • OMNI_TEST_HOST: Test host for connection testing.

Platform#

NVCF#

When running in NVCF with a bridge to a storage service in another network the bridge will require the NVCF JWT to be passed on in a header to ensure only the correct NGC Org can pass through the bridge to the storage service. These are the parameters that affect this choice:

  1. NVCF_JWT_ENABLED - Non 0 value will ensure that the headers are added to all requests that are sent to Storage API

  2. NVCF_JWT_FILE_PATH - The default NVCF JWT file path is /var/run/nvcf/info/self, otherwise this parameter can override the location of the file

  3. NVCF_JWT_HEADER - The Sevan Connection expects a header named “Omni-Tenant-Token”, however the header can be renamed with this parameter

The NVCF JWT gets rotated beteen 2.5-3 hours after creation and again afterwards. The bridge has a 3 hour expiry on the JWT validity.

Contents#