Setting Up TLS for WebXR

Why TLS is Required

Vuer is built on the WebXR protocol, which requires a secure (TLS/HTTPS) connection for security reasons. This means:

• Web client must be loaded via https:// (e.g., https://vuer.ai or https://<your-server>)
• WebSocket connection must use wss:// (e.g., wss://<your-server>:8012)

Without TLS, WebXR features will not work, and your VR/AR device won't be able to connect to Vuer.

Setup Options

Choose the approach that best fits your needs:

Important Configuration Notes

When using any TLS setup (proxy or certificate), you need to configure two things correctly:

0. Client Certificate Configuration

By default, Vuer's HTTPS server does not require client certificates. If you see your browser asking for a client certificate when connecting:

This means your server is configured for mutual TLS (mTLS). To fix this:

1. Remove client certificate requirement - Don't set VUER_SSL_CA_CERT
2. Use standard HTTPS - Just provide server cert and key:
   pythonCopy

   app = Vuer(
       cert='/path/to/server.pem',
       key='/path/to/server-key.pem'
   )

Mutual TLS is only activated when you provide a CA certificate for client verification:

# This requires client certificates
app = Vuer(
    cert='/path/to/server.pem',
    key='/path/to/server-key.pem',
    ca_cert='/path/to/ca.pem'  # Only set this if you want mTLS
)

For standard WebXR and local development, just use the first approach (no ca_cert).

1. Setting the WebSocket Endpoint

Pass the secure WebSocket endpoint to the Vuer web client using the ?ws= query parameter:

https://vuer.ai?ws=wss://your-secure-endpoint

Examples:

# Using ngrok
https://vuer.ai?ws=wss://abc123.ngrok.io

# Using self-signed cert with local IP
https://vuer.ai?ws=wss://192.168.1.100:8012

2. Handling Static Files

When loading assets (URDF models, textures, etc.), the URL behavior depends on how you load the web client:

Scenario A: Using https://vuer.ai web client

You must use absolute URLs pointing to your secure server:

# ✅ Correct - absolute URL with https
sess.upsert @ URDF(
    src='https://your-secure-endpoint/static/urdf/robot.urdf',
    key='robot',
)

# ❌ Wrong - relative path won't work
sess.upsert @ URDF(
    src='static/urdf/robot.urdf',
    key='robot',
)

Scenario B: Self-hosting web client from your server

Relative paths work fine:

# ✅ Both work when using https://your-server
sess.upsert @ URDF(
    src='static/urdf/robot.urdf',  # Relative path
    key='robot',
)

sess.upsert @ URDF(
    src='https://your-server/static/urdf/robot.urdf',  # Absolute path
    key='robot',
)

Setup Methods

Self-Signed Certificates (Local Development)

Best for connecting your VR headset when it's on the same WiFi network as your development machine.

See the self-signed certificate setup guide for complete instructions.

ngrok (Internet Access)

Best for connecting your VR headset from anywhere or sharing your Vuer session with remote users. Requires a free account.

See the ngrok setup guide for complete instructions.

localtunnel (Free Alternative)

Best for connecting your VR headset from anywhere without creating an account. Completely free and open-source.

See the localtunnel setup guide for complete instructions.

nginx Reverse Proxy