Skip to content
QuasarQuasar

Connecting and certificates

On a legacy Compose install, use docker compose -f deploy/docker-compose.yml exec or logs instead of docker exec or docker logs below.

The browser warns about the certificate

Section titled “The browser warns about the certificate”

Expected: Quasar makes its own certificate. On an untrusted network, check the fingerprint before the first visit (that’s when the first admin is claimed):

Terminal window
docker exec quasar-control-plane \
  sh -c 'openssl x509 -in /var/lib/quasar-control/tls/cert.pem -noout -fingerprint -sha256'

ERR_CERT_COMMON_NAME_INVALID

Section titled “ERR_CERT_COMMON_NAME_INVALID”

The certificate doesn’t name the address you’re using. Clicking through won’t fix it.

  • Owned install: browse to a name the certificate has, or change QUASAR_PUBLIC_HOST / QUASAR_TLS_HOSTS with reconfigure and re-issue the certificate.
  • Legacy Compose: add every address to QUASAR_TLS_HOSTS in deploy/.env, then delete the certificate so it regenerates.

See HTTPS and certificates.

Gamepad, Escape or microphone not working

Section titled “Gamepad, Escape or microphone not working”

All three need HTTPS (an accepted certificate exception counts). Escape also needs a Chromium browser in fullscreen. The session drawer says which condition is missing.

The session launches and video never arrives

Section titled “The session launches and video never arrives”

The session reaches running, the screen stays black, and about two minutes later the agent logs WebRTC transport never established.

Usually the host firewall. Docker-published control-plane ports bypass it, but the node agent’s WebRTC UDP doesn’t. Check Admin ▸ Fleet ▸ Hosts for a failed media_reachability, then open the ephemeral UDP range and UDP/5353 to your LAN or VPN subnet: Ports and endpoints.

A pass only proves one browser’s path. A rule scoped to another subnet still blocks other clients.

Login works, sessions never start

Section titled “Login works, sessions never start”

The control path works through a proxy; the media path doesn’t. Check in order:

  1. The client has a direct route to the host and its UDP ports are allowed. Ping can help check routing, but does not prove UDP media works. If needed, use a VPN. See Reaching Quasar remotely.
  2. Allowed origins (Admin ▸ Settings) list every browser origin. Follow the install-specific proxy settings for the public address.
  3. The proxy forwards WebSocket upgrades with a long read timeout.
  4. Admin ▸ Sessions: if the session is running but the user sees nothing, the problem is the connection, not the pipeline.

The connection sits at “checking”

Section titled “The connection sits at “checking””

No working ICE candidate pair. Chrome sends .local names; the agent image resolves them itself. Check:

Terminal window
docker exec quasar-node-agent avahi-daemon --check
docker exec quasar-node-agent getent hosts <name>.local

If those work, the problem is routing between client and host.

The session ends by itself

Section titled “The session ends by itself”

Check the session in Admin ▸ Sessions:

Reason Meaning
peer disconnected The browser went away (tab closed, sleep, WiFi). Not a fault.
Host lost The agent stopped heartbeating. Check it’s running.
App-related failure The app exited. See Launching a game.

Direct LAN access broke after adding a public name

Section titled “Direct LAN access broke after adding a public name”

You replaced the allowed-origins list instead of extending it. List every origin, LAN ones included. Wildcards (*) are rejected.

Terminal window
QUASAR_ALLOWED_ORIGINS=https://quasar.example.com,https://192.0.2.50:8443
Section titled “Invite links point at the wrong address”

On legacy Compose, set PUBLIC_BASE_URL to the address people use. On a Quasar-owned install, make sure the proxy preserves Host and sends X-Forwarded-Proto: see proxy settings.