Configuration

Command-line options

waylo [options]

waylo above is the server as the service runs it. In practice you set these at install time — ./waylo-<version>-linux-x64.run -- --port 9000 — or afterwards by editing ExecStart in ~/.config/systemd/user/waylo.service and reloading:

systemctl --user daemon-reload && systemctl --user restart waylo

Option	Default	Description
--port=N	8080	HTTP/WebSocket server port.
--width=N	1920	Capture width.
--height=N	1080	Capture height.
--no-https	off	Serve plain HTTP/WS instead of HTTPS/WSS.
--virtual	off	Always stream a virtual monitor, even when physical monitors are attached (headless mode).
--fps=N	15	Default frame rate (clients override per session).
--quality=N	75	Default JPEG quality (clients override per session).
--help, -h	—	Show help.

Frame rate and quality are normally chosen per session on the login screen and from the toolbar, so --fps / --quality only set the starting defaults. See Performance.

Examples

waylo --port=9000                 # different port
waylo --width=1280 --height=720   # lower resolution to save bandwidth
waylo --no-https                  # plain HTTP (TLS is the default)
waylo --virtual                   # headless / virtual display

Environment variables

Variable	Equivalent	Notes
WAYLO_HTTPS=false	--no-https	Turn TLS off.
WAYLO_VIRTUAL=true	--virtual	Headless/virtual monitor.
NODE_ENV=production	—	Set by the service unit.

TLS (HTTPS)

TLS is on by default. Waylo serves HTTPS and wss://, generating a self-signed certificate under certs/ if one isn't present; set WAYLO_TLS_CERT and WAYLO_TLS_KEY to point at your own instead. Browsers warn once about a self-signed certificate — accept it to continue, or use the desktop client, which shows the fingerprint and pins it.

The default is worth keeping: besides encrypting the login and the stream, a secure context is what lets the browser expose WebCodecs, and without it the session falls back to MJPEG at a higher bandwidth cost.

--no-https (or WAYLO_HTTPS=false) serves plain HTTP instead. That is the right choice when Waylo sits behind a TLS-terminating reverse proxy — the client detects the page scheme and uses wss:// automatically when the page was loaded over HTTPS.

For most deployments, reaching Waylo over an SSH tunnel or VPN is simpler and safer than exposing it publicly; see Security.

Per-session settings

Set on the login screen and changeable mid-session from the toolbar's ⚙️ row: frame rate, quality, fullscreen-on-connect, auto-capture pointer, multi-monitor, reduced effects, and lock-on-disconnect. Changes apply to all connected clients immediately and are remembered in the browser for next time.

Auto-login

Unattended setup writes auto-login into your display manager and installs a lock-on-login startup entry. To configure it by hand instead:

GDM (/etc/gdm3/custom.conf on Debian/Ubuntu, /etc/gdm/custom.conf on Fedora):

[daemon]
AutomaticLoginEnable=true
AutomaticLogin=yourusername

LightDM (/etc/lightdm/lightdm.conf):

[Seat:*]
autologin-user=yourusername
autologin-user-timeout=0

See Unattended Access for the service and locked-screen pieces that go with auto-login.