Skip to main content

Security

Waylo grants full control of a desktop, so its access model is deliberately narrow: only the machine's own desktop user can connect, proven against the system's real login.

Authentication​

  • SSH-verified credentials. A login is checked by opening an SSH connection to localhost with the supplied username and password. There's no separate Waylo password store — if the OS accepts the login, so does Waylo. This is why an OpenSSH server must be running on the host (see System Requirements).
  • Session-owner only. The username must match the user who owns the running desktop session (the account the Waylo process runs as). A different user's valid credentials are still rejected — you can only reach your own session.
  • Sudo required. The account must have sudo access; this is verified as part of login (and is needed for unattended-access setup).

Abuse resistance​

  • Rate limiting. After 5 failed attempts within 15 minutes, the source address is temporarily locked out and further attempts are refused until the window passes.
  • Credentials never hit the process list. Passwords are passed to sudo and to privileged copies over stdin, never as command-line arguments, so they don't appear in ps or shell history.

Pop-out windows​

A popped-out monitor window joins the running session with a short-lived attach token handed to it by the already-authenticated main window over a same-origin BroadcastChannel — not with a password. Possessing the token proves an authenticated primary window shared it; the session must already be running, and no rate-limited credential path is involved.

Locked screens​

Waylo can capture a locked session (with the extension), which keeps an unattended box locked while still reachable. When the extension isn't active, Waylo's fallback briefly unlocks the screen to start capture — a deliberate trade-off so a connection succeeds, made only after the SSH login and sudo/owner checks have passed. If keeping the screen locked matters, install the extension.

Transport and network exposure​

  • TLS by default. Waylo serves HTTPS/WSS out of the box with a self-signed certificate, so the password and the stream are encrypted with no setup. Nothing vouches for that certificate, though, so the first visit has to be trusted deliberately: browsers warn, and the desktop client shows the fingerprint and pins it. Point WAYLO_TLS_CERT/WAYLO_TLS_KEY at a real certificate, or use --no-https behind a TLS-terminating proxy. See Configuration.
  • Don't expose the port directly. Prefer reaching Waylo over an SSH tunnel or a VPN rather than publishing port 8080 to the internet. The server is optimized for loopback/VPN reach; when it sits behind a TLS reverse proxy, the client automatically uses wss://.
warning

Anyone who can both reach the port and authenticate as the desktop user gets full control of the desktop. Keep the listener on a trusted network path (SSH tunnel or VPN), and don't turn TLS off with --no-https unless something in front of Waylo is already terminating it.