Skip to main content

Unattended Access

"Unattended access" means the host is reachable without anyone at the keyboard — it boots, logs in, and Waylo is running and able to capture the session even while it sits locked. Three pieces make that work: a service, auto-login, and locked-screen capture.

The fastest path is to tick Set up unattended access on the login screen (or run the installer), which configures all three. This page explains what each does.

The service​

Waylo installs as a systemd user service so it runs inside your graphical session, where Mutter's D-Bus APIs and PipeWire live.

The installer does this for you. To install, re-point, or remove the unit by hand, run the script out of the install prefix with the bundled Node:

cd ~/.local/share/waylo
runtime/node scripts/install-service.js                 # install & start
runtime/node scripts/install-service.js --port=8080     # match your setup
runtime/node scripts/install-service.js --uninstall     # remove it

The unit is bound to graphical-session.target, so it starts with your session and stops when it ends. Check it with:

systemctl --user status waylo
journalctl --user -u waylo -f

To keep the service running after you log out (needed for true from-boot access), enable linger:

loginctl enable-linger "$USER"

Auto-login​

For the host to reach the desktop after a reboot, GDM must log the user in automatically. Waylo's unattended setup writes the auto-login keys into the display manager's config (GDM or LightDM) and installs a startup entry that locks the screen immediately after login — so the machine boots straight to a locked, capturable session.

You can also configure this by hand; see Configuration.

Locked-screen capture​

By default GNOME's Mutter refuses to start a screen-capture session while the screen is locked — the D-Bus call fails with Session creation inhibited. Waylo handles this two ways:

Preferred: the extension​

The allow-locked-remote-desktop GNOME extension (UUID allowlockedremotedesktop@kamens.us) tells Mutter to permit capture while locked, so Waylo streams the session while it stays locked — the ideal security posture for an unattended box. Unattended setup installs and enables it automatically; it activates on the next login. To install it yourself:

bash ~/.local/share/waylo/scripts/install-extension.sh
# then log out and back in (on Xorg: Alt+F2 → r → Enter) so GNOME loads it
gnome-extensions info allowlockedremotedesktop@kamens.us   # should read State: ACTIVE

Fallback: automatic unlock​

When the extension isn't loaded yet, Waylo recovers automatically: on hitting Session creation inhibited it drops the lock (via the screensaver's SetActive(false)) and retries, so the connection still succeeds — the screen is briefly unlocked rather than streamed locked. This means a locked screen never wedges an otherwise-valid, authenticated connection.

Locking behavior​

  • Lock on disconnect — an optional login toggle re-locks the desktop when your session ends, so the box returns to a locked state behind you.
  • Lock button — the toolbar can lock the remote session at any time without disconnecting; because Waylo keeps capturing and injecting, you can type the password remotely to unlock.
tip

On a machine that captures an xrdp session, Waylo and xrdp share the same GNOME session — a single stale lock can block both. Waylo's auto-unlock clears that; see Troubleshooting.