Waylo

Lightweight Remote Desktop for Wayland/GNOME

Waylo provides true unattended remote desktop access for GNOME-based Linux systems by using GNOME Mutter APIs directly, bypassing xdg-desktop-portal restrictions.

Built with Node.js, Vite, and Svelte.

Features

- ✅ Unattended Access - No permission dialogs, works immediately
- ✅ Session Security - Only the desktop session owner can connect
- ✅ SSH Authentication - Secure local user verification
- ✅ Multi-Monitor Support - Switch between monitors seamlessly
- ✅ Configurable Quality - Choose FPS (10-30) and quality (Low-Max) per session
- ✅ Low Latency - Frame dropping ensures current desktop state, minimal lag
- ✅ Full Input Control - Mouse, keyboard, and scroll with accurate positioning
- ✅ Modern UI - Slide-down toolbar, clean interface
- ✅ Smart Session Management - Screen capture only runs when connected
- ✅ Auto-cleanup - Sessions stop when browser closes

Requirements

$3

- OS: Linux with GNOME desktop environment (Ubuntu, Fedora, etc.)
- Desktop: GNOME Shell / Mutter compositor
- Display Server: Wayland
- Node.js: >= 16.0.0
- GStreamer: 1.0 with plugins
- GNOME Extension: allow-locked-remote-desktop (for locked screen access)

$3

Ubuntu/Debian:
``bash sudo apt install gstreamer1.0-tools gstreamer1.0-plugins-base \ gstreamer1.0-plugins-good gstreamer1.0-pipewire`

Fedora:`bash sudo dnf install gstreamer1 gstreamer1-plugins-base \ gstreamer1-plugins-good pipewire-gstreamer`

`$3`

For remote desktop to work when the screen is locked, you must install this extension:

Option 1: Using Waylo's helper script (Easiest)`bash npm run install-extension`

Option 2: From GNOME Extensions Website 1. Visit: https://extensions.gnome.org/extension/4338/allow-locked-remote-desktop/ 2. Click "Install" and follow the prompts

Option 3: Manual Installation`bash cd /tmp git clone https://github.com/jikamens/allow-locked-remote-desktop.git cd allow-locked-remote-desktop make install gnome-extensions enable allow-locked-remote-desktop@jikamens.us`

Check status:`bash npm run check-extension`

Why this is needed: GNOME Mutter blocks ScreenCast sessions when the screen is locked for security. This extension removes that restriction by overriding inhibit_remote_access.

Note: Waylo automatically checks for this extension on startup and warns if it's missing.

`Installation`

`$3`

`bash

`Install globally`


npm install -g waylo
Run it

waylo


Usage
$3

1. Start the server:`bash waylo # or if installed from source: npm start`

2. Open browser: Navigate tohttp://localhost:8080

3. Login: - Enter your Linux username and password - Choose frame rate (10-30 FPS) based on your network - Choose quality (Low-Max) for bandwidth control - Click Login

4. Control the desktop: - Click on the video to capture mouse - Press ESC to release mouse - Use the toolbar (top center) to switch monitors or disconnect

`$3`

`bash npm run dev`

Opens on http://localhost:8080 with Vite HMR enabled.

`Configuration`

`$3`

`bash waylo [options]

Options: --port=8080 WebSocket server port (default: 8080) --width=1920 Video width (default: 1920) --height=1080 Video height (default: 1080) --help, -h Show help message`

Note: FPS and quality are now configured per-session on the login screen, not via CLI.

`$3`

Run on different port:`bash waylo --port=9000`

Lower resolution (saves bandwidth):`bash waylo --width=1280 --height=720`

`$3`

`Architecture`

`$3`

- gnomeBackend.js - D-Bus communication with GNOME Mutter - streamer.js - GStreamer MJPEG pipeline management - server.js - WebSocket server for client communication - inputHandler.js - Keyboard/mouse event mapping - index.js - Main entry point

`$3`

- App.svelte - Main application component - VideoStream.svelte - Video display and input capture - MonitorSwitcher.svelte - Monitor switching controls - Controls.svelte - Fullscreen and connection status - stores/websocket.js - WebSocket connection management

`$3`

`┌─────────────────────────────────────────────────┐ │ Node.js Backend │ ├──────────────────┬──────────────────────────────┤ │ GNOME D-Bus │ GStreamer Pipeline │ │ - ScreenCast │ - PipeWire capture │ │ - RemoteDesktop │ - MJPEG encoding │ │ - Input control │ - Binary stdout │ ├──────────────────┴──────────────────────────────┤ │ WebSocket Server (port 8080) │ │ - Stream JPEG frames to browser │ │ - Receive input events from browser │ └─────────────────────────────────────────────────┘ ↕ ┌─────────────────────────────────────────────────┐ │ Svelte Frontend (Vite) │ │ - Display MJPEG frames │ │ - Capture mouse/keyboard input │ │ - Monitor switching UI │ └─────────────────────────────────────────────────┘`

`How It Works`

`$3`

The standard xdg-desktop-portal approach has critical limitations for unattended access:

1. Manual Activation Required - PipeWire requires real user input to start 2. No Monitor Persistence - User must reselect monitors on each restart 3. Permission Dialogs - Shows dialogs on every session

GNOME Mutter Solution:

- Direct compositor APIs (org.gnome.Mutter.ScreenCast, org.gnome.Mutter.RemoteDesktop) - No permission dialogs - No manual activation required - Works immediately across restarts - Designed for remote desktop scenarios

`$3`

Waylo uses MJPEG (Motion JPEG) instead of H.264 because:

- Each frame is a complete JPEG image - No complex codec state or muxing issues - Works perfectly with browser WebSocket - Simple to implement and debug - Acceptable bandwidth for LAN usage (2-4 Mbps @ 1080p/15fps)

`Unattended Access Setup`

For complete unattended access that survives reboots:

`$3`

`bash

`Create service file`


mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/waylo.service


Add the following content:

`ini [Unit] Description=Waylo Remote Desktop After=graphical-session.target

[Service] Type=simple ExecStart=/usr/bin/node /path/to/waylo/server/index.js Restart=always RestartSec=5

[Install] WantedBy=default.target`

`$3`

`bash

`Enable the service`


systemctl --user enable waylo
Start the service

systemctl --user start waylo
Enable lingering (persist after logout)

loginctl enable-linger $USER


$3
Required for unattended access! Install the GNOME extension to allow remote desktop when screen is locked:

`bash

`Install from GNOME Extensions website (easiest):`


https://extensions.gnome.org/extension/4338/allow-locked-remote-desktop/
OR install manually:

cd /tmp
git clone https://github.com/jikamens/allow-locked-remote-desktop.git
cd allow-locked-remote-desktop
make install
gnome-extensions enable allow-locked-remote-desktop@jikamens.us


$3
For complete unattended access after reboot, enable auto-login:
Method 1: Use Waylo's built-in setup
- Check "Configure system for unattended access" on the login screen
- Waylo will automatically configure GDM auto-login and screen lock
Method 2: Manual configuration

Ubuntu/Debian: Edit/etc/gdm3/custom.conf:

`ini [daemon] AutomaticLoginEnable=true AutomaticLogin=yourusername`

Fedora: Edit/etc/gdm/custom.conf with the same settings.

`$3`

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

Important: With auto-login enabled and the allow-locked-remote-desktop extension installed, your system will: - Auto-login on boot - Lock the screen immediately (if using Waylo's setup) - Allow remote desktop access even when locked - Provide true unattended access

`Browser Usage`

`$3`

- Server Status - Auto-detects if server is online (polls every 3 seconds) - Frame Rate - Choose 10-30 FPS based on network speed - Quality - Choose Low-Max based on bandwidth availability - Auto-login Setup - Optional checkbox to configure system for unattended access

`$3`

- Click on video - Capture mouse (pointer lock, auto-positions cursor) - Ctrl+M - Release mouse control - Ctrl+Right Arrow - Cycle to next monitor - ESC - Exit fullscreen (browser default) - Mouse/Keyboard - Full control when captured - Toolbar - Click the nub at top center to slide down toolbar - Monitor numbers (1, 2, 3...) - Switch between displays - Fullscreen button - Toggle fullscreen mode - Disconnect button - End session and cleanup

`$3`

- Accurate mouse positioning - Remote cursor moves to where you click before capturing - Frame dropping - Always shows current desktop state, no lag from buffering - Auto-disconnect - Closing browser tab stops screen capture session - Connection monitoring - Login screen shows server status in real-time

`Performance Tuning`

`$3`

| Profile | Resolution | FPS | Quality | Bandwidth | |---------|-----------|-----|---------|-----------| | Low | 1280x720 | 10 | 60 | ~1 Mbps | | Balanced | 1920x1080 | 15 | 75 | ~2-4 Mbps | | High | 1920x1080 | 30 | 85 | ~6-8 Mbps |

`$3`

- LAN: Use Balanced or High profile - Remote: Use Low profile or set up VPN tunnel - WiFi: Balanced profile recommended

`Security`

`$3`

- ✅ SSH-based authentication - Validates against system users - ✅ Session owner verification - Only the desktop session owner can connect - ✅ Sudo requirement - Users must have sudo access - ✅ No username enumeration - Error messages don't leak usernames - ✅ Session isolation - Screen capture only runs when authenticated - ✅ Auto-disconnect - Sessions cleanup when browser closes

`$3`

- ⚠️ Unencrypted WebSocket (WS) - Passwords sent in plaintext over network - ⚠️ No rate limiting - Susceptible to brute force attacks - ⚠️ LAN/VPN only - Not recommended for internet exposure

`$3`

1. Use VPN Tunnel (Recommended) - Tailscale, Netbird, or WireGuard - Encrypted transport layer - Simplest and most secure solution

2. Add TLS/WSS via Reverse Proxy`nginx # nginx example location / { proxy_pass http://localhost:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; }`

3. Firewall Rules - Only allow connections from trusted networks - Use UFW or iptables to restrict access

`Troubleshooting`

`$3`

Error: "No monitors found" - Ensure you're running GNOME desktop environment - Check:echo $XDG_CURRENT_DESKTOP should show GNOME

Error: "Could not connect to GNOME Mutter" - Verify GNOME session is running - Check D-Bus session:dbus-send --session --print-reply --dest=org.gnome.Mutter.ScreenCast /org/gnome/Mutter/ScreenCast org.freedesktop.DBus.Introspectable.Introspect

`$3`

- Check GStreamer is installed: gst-launch-1.0 --version- Verify PipeWire is running:systemctl --user status pipewire- Check server logs for GStreamer errors

`$3`

- Reduce FPS: --fps=10- Lower quality:--quality=60- Reduce resolution:--width=1280 --height=720

`$3`

- Click on the video to capture pointer - Ensure pointer lock is active (ESC to release) - Check browser console for errors

`$3`

Error: "DBusError: Session creation inhibited"

This happens when trying to connect while the screen is locked. Solutions:

1. Install the allow-locked-remote-desktop extension (see Requirements section) 2. Unlock the screen manually and try again 3. Restart GNOME Shell to clear any stuck sessions:killall -HUP gnome-shell or Alt+F2 → type 'r' → Enter

`Known Limitations`

1. GNOME-Only - Requires GNOME desktop environment 2. Wayland - Designed for Wayland, may not work on X11 3. Session Requirement - User must be logged in 4. Bandwidth - MJPEG uses more bandwidth than H.264

`Future Enhancements`

- [ ] Audio streaming via PipeWire - [ ] Clipboard synchronization - [ ] File transfer support - [ ] H.264 encoding option - [ ] Adaptive quality based on bandwidth - [ ] Access code authentication - [ ] Multiple simultaneous users - [ ] Recording functionality

`Project Structure`

`waylo/ ├── server/ # Backend Node.js code │ ├── index.js # Main entry point │ ├── gnomeBackend.js # D-Bus GNOME Mutter interface │ ├── streamer.js # GStreamer pipeline manager │ ├── server.js # WebSocket server │ └── inputHandler.js # Input event mapping ├── src/ # Frontend Svelte code │ ├── main.js # App entry point │ ├── App.svelte # Main component │ ├── app.css # Global styles │ ├── lib/ # Svelte components │ │ ├── VideoStream.svelte │ │ ├── MonitorSwitcher.svelte │ │ └── Controls.svelte │ └── stores/ # Svelte stores │ └── websocket.js ├── public/ # Static assets ├── package.json # Dependencies ├── vite.config.js # Vite configuration └── README.md # This file``

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License - See LICENSE file for details

Acknowledgments

Based on research into GNOME Mutter APIs for unattended Wayland remote desktop access. This project demonstrates that proper remote desktop functionality IS possible on Wayland using compositor-level APIs.

Support

For issues, questions, or feature requests, please open an issue on GitHub.

---

Made with ❤️ for the GNOME community

Waylo

Lightweight Remote Desktop for Wayland/GNOME

Waylo provides true unattended remote desktop access for GNOME-based Linux systems by using GNOME Mutter APIs directly, bypassing xdg-desktop-portal restrictions.

Built with Node.js, Vite, and Svelte.

Features

Requirements

$3

Ubuntu/Debian:
``bash sudo apt install gstreamer1.0-tools gstreamer1.0-plugins-base \ gstreamer1.0-plugins-good gstreamer1.0-pipewire`

Fedora:`bash sudo dnf install gstreamer1 gstreamer1-plugins-base \ gstreamer1-plugins-good pipewire-gstreamer`

`$3`

For remote desktop to work when the screen is locked, you must install this extension:

Option 1: Using Waylo's helper script (Easiest)`bash npm run install-extension`

Option 2: From GNOME Extensions Website 1. Visit: https://extensions.gnome.org/extension/4338/allow-locked-remote-desktop/ 2. Click "Install" and follow the prompts

Check status:`bash npm run check-extension`

Why this is needed: GNOME Mutter blocks ScreenCast sessions when the screen is locked for security. This extension removes that restriction by overriding inhibit_remote_access.

Note: Waylo automatically checks for this extension on startup and warns if it's missing.

`Installation`

`$3`

`bash

`Install globally`


npm install -g waylo
Run it

waylo


Usage
$3

1. Start the server:`bash waylo # or if installed from source: npm start`

2. Open browser: Navigate tohttp://localhost:8080

3. Login: - Enter your Linux username and password - Choose frame rate (10-30 FPS) based on your network - Choose quality (Low-Max) for bandwidth control - Click Login

4. Control the desktop: - Click on the video to capture mouse - Press ESC to release mouse - Use the toolbar (top center) to switch monitors or disconnect

`$3`

`bash npm run dev`

Opens on http://localhost:8080 with Vite HMR enabled.

`Configuration`

`$3`

`bash waylo [options]

Options: --port=8080 WebSocket server port (default: 8080) --width=1920 Video width (default: 1920) --height=1080 Video height (default: 1080) --help, -h Show help message`

Note: FPS and quality are now configured per-session on the login screen, not via CLI.

`$3`

Run on different port:`bash waylo --port=9000`

Lower resolution (saves bandwidth):`bash waylo --width=1280 --height=720`

`$3`

`Architecture`

`$3`

`How It Works`

`$3`

The standard xdg-desktop-portal approach has critical limitations for unattended access:

GNOME Mutter Solution:

`$3`

Waylo uses MJPEG (Motion JPEG) instead of H.264 because:

`Unattended Access Setup`

For complete unattended access that survives reboots:

`$3`

`bash

`Create service file`


mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/waylo.service


Add the following content:

`ini [Unit] Description=Waylo Remote Desktop After=graphical-session.target

[Service] Type=simple ExecStart=/usr/bin/node /path/to/waylo/server/index.js Restart=always RestartSec=5

[Install] WantedBy=default.target`

`$3`

`bash

`Enable the service`


systemctl --user enable waylo
Start the service

systemctl --user start waylo
Enable lingering (persist after logout)

loginctl enable-linger $USER


$3
Required for unattended access! Install the GNOME extension to allow remote desktop when screen is locked:

`bash

`Install from GNOME Extensions website (easiest):`


https://extensions.gnome.org/extension/4338/allow-locked-remote-desktop/
OR install manually:

cd /tmp
git clone https://github.com/jikamens/allow-locked-remote-desktop.git
cd allow-locked-remote-desktop
make install
gnome-extensions enable allow-locked-remote-desktop@jikamens.us


$3
For complete unattended access after reboot, enable auto-login:
Method 1: Use Waylo's built-in setup
- Check "Configure system for unattended access" on the login screen
- Waylo will automatically configure GDM auto-login and screen lock
Method 2: Manual configuration

Ubuntu/Debian: Edit/etc/gdm3/custom.conf:

`ini [daemon] AutomaticLoginEnable=true AutomaticLogin=yourusername`

Fedora: Edit/etc/gdm/custom.conf with the same settings.

`$3`

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

`Browser Usage`

`$3`

`Performance Tuning`

`$3`

- LAN: Use Balanced or High profile - Remote: Use Low profile or set up VPN tunnel - WiFi: Balanced profile recommended

`Security`

`$3`

1. Use VPN Tunnel (Recommended) - Tailscale, Netbird, or WireGuard - Encrypted transport layer - Simplest and most secure solution

3. Firewall Rules - Only allow connections from trusted networks - Use UFW or iptables to restrict access

`Troubleshooting`

`$3`

Error: "No monitors found" - Ensure you're running GNOME desktop environment - Check:echo $XDG_CURRENT_DESKTOP should show GNOME

`$3`

- Check GStreamer is installed: gst-launch-1.0 --version- Verify PipeWire is running:systemctl --user status pipewire- Check server logs for GStreamer errors

`$3`

- Reduce FPS: --fps=10- Lower quality:--quality=60- Reduce resolution:--width=1280 --height=720

`$3`

- Click on the video to capture pointer - Ensure pointer lock is active (ESC to release) - Check browser console for errors

`$3`

Error: "DBusError: Session creation inhibited"

This happens when trying to connect while the screen is locked. Solutions:

`Known Limitations`

`Future Enhancements`

`Project Structure`

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License - See LICENSE file for details

Acknowledgments

Support

For issues, questions, or feature requests, please open an issue on GitHub.

---

Made with ❤️ for the GNOME community