CloudXR Runtime Management API#
Your application uses this interface to control the NVIDIA CloudXR™ OpenXR runtime. It provides C APIs for managing the runtime lifecycle, configuring runtime behavior, and receiving status events.
Overview#
You can receive events about client and application connections by
polling with nv_cxr_service_poll_event. This function returns events such as
that a CloudXR client connects or disconnects, or that an OpenXR application
connects or disconnects.
Before you start the runtime, you can configure it using the property
functions (nv_cxr_service_set_string_property,
nv_cxr_service_set_boolean_property, nv_cxr_service_set_int64_property).
Once you have configured it, calling nv_cxr_service_start starts the
runtime, which begins accepting connections from both CloudXR clients and OpenXR
applications.
Configuration Properties#
Properties can be configured before starting the runtime using the property setter functions. The following properties are available for external developers to control runtime behavior.
Note
Some properties are marked as read-only, and are set during runtime initialization via environment variables only. You cannot modify these using the property setter functions after the service is created.
Device Configuration#
device-profile#
- Type:
String (enum)
- Default:
“auto-native”
Value |
Profile |
|---|---|
“auto-native” |
Auto mode for native clients (default), as explained below |
“auto-webrtc” |
Auto mode for web clients (using WebRTC) |
“apple-vision-pro” |
Apple Vision Pro |
“ipad-pro” |
Apple iPad Pro |
If you set the property device-profile to auto-native, the
runtime starts in auto mode for native clients. In this mode, the runtime waits until a
CloudXR native client has connected before filling in the system properties. This
means that the OpenXR function xrGetSystem returns
XR_ERROR_FORM_FACTOR_UNAVAILABLE until a client connects.
Once the client has connected, the application must check for both
XR_FORM_FACTOR_HEAD_MOUNTED_DISPLAY and XR_FORM_FACTOR_HANDHELD_DISPLAY
to handle both HMDs and tablets connecting to the runtime.
Device |
Form Factor |
|---|---|
Apple Vision Pro |
|
Apple iPad |
|
If you set the property device-profile to auto-webrtc, the
runtime will start in auto mode for web clients using WebRTC. In this mode, the
runtime waits until a CloudXR.js web client has connected before filling in the
system properties. Like auto-native, the OpenXR function xrGetSystem
returns XR_ERROR_FORM_FACTOR_UNAVAILABLE until a client connects.
When you use auto-webrtc, the runtime automatically configures the following
settings for WebRTC streaming unless you have already set a value:
server-port: 49100
Web clients only represent head-mounted displays, so the application should check
for XR_FORM_FACTOR_HEAD_MOUNTED_DISPLAY.
Network Configuration#
endpoint-ip#
- Type:
String
- Default:
empty (binds to all interfaces)
The IP address that the runtime binds to for accepting client connections. If left empty, the runtime binds to all available network interfaces.
Example: "192.168.1.100"
server-port#
- Type:
Int64
- Default:
48010
The TCP port number for the CloudXR signaling/control channel. Adjust this to avoid port conflicts with other services running on the same host. This port is used for WebSocket (WS) or secure WebSocket (WSS) connections.
Valid Range: 1024-65535
media-port#
- Type:
Int64
- Default:
0 (auto-assign)
The UDP port number for streaming media data. When set to 0 (default), the
media port is automatically assigned. When set to a specific value greater than
zero, that port is used as a fixed media port. Adjust this to avoid port
conflicts with other services.
Valid Range: 0, 1024-65535
Security Configuration#
client-token#
- Type:
String
- Default:
empty (authentication disabled)
A secret token shared in advance for authenticating client connections. When set, clients must provide the matching token to establish a connection, enabling secure authenticated streaming.
When used with certificate-pem and key-pem, provides both transport
security (TLS) and authentication.
Example: "my-secure-token-12345"
See also
Secure Connection Mode for complete security setup including certificate configuration and client authentication.
certificate-pem#
- Type:
String
- Default:
empty (no TLS)
Path to a PEM-encoded X.509 certificate file for TLS/SSL connections. When both
certificate-pem and key-pem are set, the signaling protocol upgrades
from WebSocket (WS) to secure WebSocket (WSS).
Example: "/path/to/certificate.pem" or "C:\\certs\\cert.pem"
key-pem#
- Type:
String
- Default:
empty (no TLS)
Path to a PEM-encoded private key file for TLS/SSL connections. Must be used in
conjunction with certificate-pem.
Example: "/path/to/private-key.pem" or "C:\\certs\\key.pem"
Logging Configuration#
file-logging#
- Type:
Boolean (read-only)
- Default:
true
- Environment Variable:
NV_CXR_FILE_LOGGING
Enable or disable file-based logging. When enabled, the runtime writes log
files to the directory specified by output-dir. This property is read-only,
and must be set via the NV_CXR_FILE_LOGGING environment variable before
creating the runtime service. Log files are named using the pattern:
cxr_server.<timestamp>.log
output-dir#
- Type:
String (read-only)
- Default:
not set / empty (temporary directory is created)
- Environment Variable:
NV_CXR_OUTPUT_DIR
Directory path where log files and other runtime output are written. This
property is read-only, and must be set via the NV_CXR_OUTPUT_DIR environment
variable before creating the runtime service. If not set, the runtime
automatically creates a temporary directory for output files.
Warning
This directory must only be used for non-secret files, as it may have relaxed permissions in some configurations.
startup-timestamp-string#
- Type:
String (read-only)
- Format:
ISO 8601 timestamp (
YYYY-MM-DDTHHMMSSZ)
A timestamp string used as part of log file names to identify and organize log files from different runtime sessions. This property is read-only, and is automatically set when the runtime service is created. The timestamp is generated in UTC.
Example: "2025-12-10T143042Z"
log-max-file-size#
- Type:
Int64
- Default:
33554432 (32 MB)
Maximum size in bytes of individual StreamSDK log files. When a log file reaches this size, the runtime rotates to a new file. This prevents log files from growing unbounded, and supports proper log rotation.
Valid Range: 1048576-1073741824 (1 MB - 1 GB)
Streaming Configuration#
audio-streaming#
- Type:
Boolean
- Default:
true
Enable or disable audio streaming from the server to the client. When disabled, only video is streamed. This can be useful for scenarios where audio is handled through a separate channel, or when audio streaming is not required.
disable-alpha#
- Type:
Boolean
- Default:
false
Disable alpha channel encoding in the video stream. When set to true, the
alpha view is not streamed to the client, regardless of whether the
renderer produces alpha channel data. For most applications that don’t use
transparency, disabling alpha can save encoding time and bandwidth.
runtime-foveation#
- Type:
Boolean
- Default:
false
Enable static center foveated streaming. When set to true, the OpenXR
Runtime applies foveation to the video stream, enhancing visual quality
and pixel density in the central region of the view where user attention
is typically focused, while reducing resolution in peripheral areas.
Warning
This feature is only supported on HMD devices. Do not enable it when
device-profile is set to ipad-pro, or when using auto-native
mode with an iPad device connected, as streaming may not work properly.
runtime-foveation-unwarped-width#
- Type:
Int64
- Default:
0 (use client-provided dimensions)
Width in pixels of the unwarped (pre-distortion) rendering region. This controls the resolution at which the application renders before any foveation or distortion is applied. You can adjust this value to tune the streaming resolution for performance optimization.
When set to 0 (default), the runtime uses the dimensions provided by the
client during the view configuration handshake. Setting a specific value
overrides the client’s request.
Warning
This feature is only supported on HMD devices. Leave this property at 0 when
device-profile is set to ipad-pro, or when using auto-native
mode with an iPad device connected, as streaming may not work properly.
Functions#
Version Functions#
nv_cxr_get_library_api_version#
Returns the version of the API. Useful for applications that dynamically load the library to verify compatibility. This version determines which functions are available to call.
nv_cxr_get_runtime_version#
Returns the version of the runtime itself. Useful for logging and debugging. The major version number is also the protocol version, which can be displayed in the application UI to inform users which clients are supported.
Service Lifecycle Functions#
nv_cxr_service_create#
Creates a service object. Only one service can be alive at a time. The runtime
is not started when this object is created; use nv_cxr_service_start to
begin accepting connections.
nv_cxr_service_start#
Starts the service. This function returns once the service is fully
started up and is ready to accept connections from both clients and
applications. Returns NV_CXR_SERVICE_ALREADY_STARTED if already running.
nv_cxr_service_stop#
Signals the service to stop and disconnects all applications and clients. This
function only signals shutdown; use nv_cxr_service_join to wait for the
service to come to a complete stop.
nv_cxr_service_join#
Blocks until the service has fully stopped. Useful when using built-in mechanisms to stop the service. When this function returns, the service has completely stopped.
nv_cxr_service_destroy#
Destroys a service object. The service must be in a fully stopped state, either because you never called start, or after successful calls to stop and join.
Property Functions#
Properties can only be set before nv_cxr_service_start is called or after
the runtime has been fully stopped. Refer to Configuration Properties
above for the complete list of available properties.
nv_cxr_service_set_string_property#
Sets a string property to the given value.
nv_cxr_service_set_boolean_property#
Sets a Boolean property to the given value.
nv_cxr_service_set_int64_property#
Sets an int64 property to the given value.
nv_cxr_service_get_string_property#
Gets a string property value. The value is copied to the provided buffer.
Returns NV_CXR_ERROR_BUFFER_SIZE_INSUFFICIENT if the buffer is too small.
nv_cxr_service_get_boolean_property#
Gets a Boolean property value.
nv_cxr_service_get_int64_property#
Gets an int64 property value.
Event Functions#
nv_cxr_service_poll_event#
Returns the oldest event in the internal event queue. The first call returns the oldest event that has occurred since the start of the service. Each
call returns one event and removes it from the internal event queue. Returns
NV_CXR_EVENT_NONE if no events are available.
Available event types:
NV_CXR_EVENT_CLOUDXR_CLIENT_CONNECTED- A CloudXR client has connectedNV_CXR_EVENT_CLOUDXR_CLIENT_DISCONNECTED- A CloudXR client has disconnectedNV_CXR_EVENT_OPENXR_APP_CONNECTED- An OpenXR application has connectedNV_CXR_EVENT_OPENXR_APP_DISCONNECTED- An OpenXR application has disconnected