Client Setup Guide#

Note

Additional configuration examples and troubleshooting guides are provided as part of the CloudXR.js Early Access Program artifacts on NGC. Refer to the CloudXR.js User Guide to join the program.

This guide provides configuration for CloudXR.js client devices, including browser setup, web server hosting options, and connection modes.

Before proceeding, review the CloudXR.js Requirements for supported devices and requirements.

Web Application Hosting#

CloudXR.js client applications can be hosted using either HTTP or HTTPS protocols. We provide examples for both modes to help you choose the right approach for your deployment.

HTTP Mode (Development)#

This example demonstrates the simplest configuration for local development and testing.

Example command:

npm run dev-server

Access URLs:

  • Local: http://localhost:8080/

  • Network: http://<server-ip>:8080/

Characteristics:

  • Recommended for: Local development, trusted network environments

  • Simplified setup with minimal configuration

  • Supports connections to both ws:// (direct) and wss:// (proxied) server endpoints

  • Requires browser security flags for immersive web functionality (see Meta Quest 3 or Pico 4 Ultra configuration below)

HTTPS Mode (Development and Production)#

This example demonstrates HTTPS hosting, which is used for both development with WebXR devices and production deployments. It provides encrypted client connections and is required for secure WebSocket connections.

Example command:

npm run dev-server:https

Access URLs:

  • Local: https://localhost:8080/

  • Network: https://<server-ip>:8080/

Characteristics:

  • Recommended for: XR device testing, production deployments, remote access, security-sensitive environments

  • Automatically generates self-signed SSL certificates (for development) or custom certificates (for production).

  • Requires a wss:// (secure WebSocket) connection to server application.

  • Browsers enforce mixed content policy, blocking ws:// connections from HTTPS pages.

  • Requires certificate trust configuration in client browser.

Connection Mode Examples#

The following table shows example connection configurations between the web application server and the CloudXR server application (built with CloudXR Runtime):

Client Web Server

Runtime Connection

Status

Use Case

HTTP

ws://server-ip:49100

✅ Supported

Local development (simplest path)

HTTP

wss://proxy-ip:48322

✅ Supported

Testing proxy configuration

HTTPS

ws://server-ip:49100

❌ Blocked

Mixed content security policy violation

HTTPS

wss://proxy-ip:48322

✅ Supported

XR device testing, production deployment

Important

When using HTTPS mode for your web application, you must configure a WebSocket proxy with TLS support. Refer to WebSocket Proxy Setup for detailed proxy configuration.

Headset Configuration#

This section provides configurations for supported XR headsets to enable immersive web functionality with CloudXR.js applications.

Tip

For rapid development and debugging, we recommend testing your CloudXR.js application on a desktop browser with IWER before deploying to XR headsets.

Pico 4 Ultra Configuration#

Pico 4 Ultra has the following requirements:

Important

  • Requires Pico OS 15.4.4U or later.

  • HTTP mode is not supported—HTTPS mode is required for immersive web applications.

Browser Configuration#

See Trust SSL Certificates (HTTPS Mode) for browser configuration instructions.

Additional Configuration#

Enable hand tracking:

  1. Open Settings on your Pico 4 Ultra.

  2. Navigate to Interaction.

  3. Select Auto Switch between Hands & Controllers for Interaction Controls.

Disable system gestures (optional):

  1. Open Settings on your Pico 4 Ultra/

  2. Navigate to Developer → Business Settings → System.

  3. Disable Handtracking system gesture.

Meta Quest 3 Configuration#

The Meta Quest 3 (OS version 79 or later) browser works with both HTTP and HTTPS modes. Choose the configuration that matches your hosting mode.

Option 1: Configure Insecure Origins (HTTP Mode)#

When using HTTP mode (npm run dev-server), the Meta Quest 3 browser needs explicit permission to access WebXR APIs from non-HTTPS origins. This is how to configure it:

  1. Access browser flags:

    1. Open the Meta Quest 3 Browser.

    2. Navigate to chrome://flags.

  2. Enable insecure origins:

    1. Search for “insecure” in the search field.

    2. Locate the flag: unsafely-treat-insecure-origin-as-secure.

    3. Set the flag to Enabled.

  3. Add your development server:

    In the text field below the flag, enter your web server URL in the format http://<server-ip>:8080. Be sure to include the protocol (http://) and port number (:8080).

    You can enter multiple URLs, separated by commas, if needed.

  4. Apply configuration:

    1. Click or tap outside the text field to defocus.

    2. A Relaunch button appears at the bottom of the screen.

    3. Click Relaunch to apply changes.

  5. Verify configuration:

    1. Return to chrome://flags after relaunch.

    2. Confirm that the flag remains enabled and your URL is saved.

Option 2: Trust SSL Certificates (HTTPS Mode)#

When using HTTPS mode (npm run dev-server:https), refer to Trust SSL Certificates (HTTPS Mode) for configuration instructions.

Verify WebXR Permissions#

When you connect to a CloudXR.js application:

  1. The browser prompts for WebXR permissions the first time you use it.

  2. Select Allow when prompted.

  3. The immersive session begins after permission is granted.

Trust SSL Certificates (HTTPS Mode)#

When using HTTPS mode with self-signed certificates (for the web server and the WebSocket proxy), you need to configure the browser to trust these certificates.

Note

Certificate trust settings persist across browser sessions. You only need to perform this configuration once per certificate.

Trust WebSocket Proxy Certificate#

  1. Access the proxy endpoint:

    • In your headset browser, navigate to the sample client page and fill in the proxy IP as server IP and corresponding port, then click click xxx to accept cert as shown below.

    • Alternatively, you can navigate directly to https://<proxy-ip>:48322/.

    Accept proxy certificate button

    Accept proxy certificate button#

  2. Accept certificate warning:

    • Click Advanced

    • Click Proceed to <proxy-ip> (unsafe) or similar option

    Accept certificate warning

    Accept certificate warning#

  3. Expected behavior:

    1. The page may display a “501 Not Implemented” error. This is expected—the proxy only handles WebSocket connections, not HTTP requests.

    2. The certificate is now trusted for WebSocket connections.

Note

If you restart or recreate the proxy container (using the Docker HAProxy example with auto-generated certificates), a new self-signed certificate is generated. You must repeat the certificate trust process by visiting https://<proxy-ip>:48322/ again and accepting the new certificate warning.

If you mount your own certificate (see WebSocket Proxy Setup), the same certificate persists across restarts and you only need to trust it once.

Trust Web Application Certificate#

  1. Access the web application:

    1. Open your XR headset browser.

    2. Navigate to https://<server-ip>:8080/.

  2. Accept certificate warning:

    1. Click Advanced.

    2. Click Proceed to <server-ip> (unsafe) or similar option.

    Accept certificate warning

    Accept certificate warning#

  3. Verify access:

    The web application should load successfully.

Network Configuration#

For network and firewall configuration requirements, including port setup and bandwidth recommendations, refer to Ports and Firewalls and Network Setup.

Common Issues and Solutions#

WebXR API Not Available#

Symptoms:

  • Application displays “WebXR not supported” or similar error.

  • Connect button is disabled or missing.

Solutions:

  • Verify that browser flags are configured correctly (see Option 1: Configure Insecure Origins (HTTP Mode)).

  • Ensure that you’re accessing the application via the configured URL, exactly as specified.

  • Confirm that the browser has been relaunched after changing flags.

  • Try accessing the application via incognito/private browsing mode.

Certificate Trust Issues#

Symptoms:

  • Connection fails with security warnings.

  • WebSocket connection shows “SSL certificate error.”

Solutions:

  • Complete the certificate trust process for both web server and proxy.

  • Verify that you clicked Proceed on the certificate warning pages.

  • Clear the browser cache and retry the trust process.

  • For persistent issues, regenerate the certificates.

Mixed Content Errors#

Symptoms:

  • Console shows “blocked by mixed content policy” errors.

  • WebSocket connection fails from an HTTPS page.

Solutions:

  • When using npm run dev-server:https, ensure that the runtime connection uses wss:// not ws://.

  • Verify that a WebSocket proxy is configured and running (see WebSocket Proxy Setup).

  • Check that the proxy URL is accessible and trusted.

Connection Drops or Instability#

Symptoms:

  • Frequent disconnections during streaming.

  • Poor video quality or high latency.

Solutions:

  • Review Network Setup for bandwidth and latency requirements.

  • Verify that the firewall allows traffic on required ports.

  • Ensure that the Wi-Fi connection is on the 5 GHz or 6 GHz band.

  • Check for network congestion from other devices.

Next Steps#

On this page