Configuration

Command-line options

waylo [options]

waylo above is the server as the service runs it. An installed WayLo takes its port and HTTPS setting from ~/.config/waylo/waylo.env, which the installer writes (--port, --no-https) and updates never touch:

WAYLO_PORT=8080
WAYLO_HTTPS=true

Edit it, then restart the service:

systemctl --user restart waylo

For anything else (another flag, an environment variable), add a drop-in rather than editing the unit, which every update rewrites:

systemctl --user edit waylo      # e.g. [Service] / Environment=WAYLO_VIRTUAL=true
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_PORT=N	--port=N	The service reads it from waylo.env.
WAYLO_HTTPS=false	--no-https	Turn TLS off. The service reads it from waylo.env.
WAYLO_CERT_DIR=DIR	—	Where the self-signed certificate lives (default ~/.config/waylo/certs).
WAYLO_TLS_CERT, WAYLO_TLS_KEY	—	Use your own certificate and key instead.
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 in ~/.config/waylo/certs/ if one isn't present; set WAYLO_TLS_CERT and WAYLO_TLS_KEY to point at your own instead. The certificate stays the same across updates, so clients that pinned it keep trusting it. To make a new one (after the machine's addresses change), delete the waylo.crt and waylo.key there and restart the service. 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, seamless mouse, 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.