waylo

v0.2.2

Published

18 days ago

Lightweight remote desktop for Wayland/GNOME - unattended access via GNOME Mutter APIs

0High
0Medium
0Low

remote-desktop wayland gnome screen-sharing screen-capture remote-access vnc-alternative pipewire gstreamer unattended-access linux

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

System Requirements

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)

Install GStreamer Dependencies

Ubuntu/Debian:

sudo apt install gstreamer1.0-tools gstreamer1.0-plugins-base \
  gstreamer1.0-plugins-good gstreamer1.0-pipewire

Fedora:

sudo dnf install gstreamer1 gstreamer1-plugins-base \
  gstreamer1-plugins-good pipewire-gstreamer

Install GNOME Extension (Required for Locked Screen Access)

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

Option 1: Using Waylo's helper script (Easiest)

npm run install-extension

Option 2: From GNOME Extensions Website

Visit: https://extensions.gnome.org/extension/4338/allow-locked-remote-desktop/
Click "Install" and follow the prompts

Option 3: Manual Installation

cd /tmp
git clone https://github.com/jikamens/allow-locked-remote-desktop.git
cd allow-locked-remote-desktop
make install
gnome-extensions enable [email protected]

Check status:

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

Install from npm

# Install globally
npm install -g waylo

# Run it
waylo

Usage

Quick Start

Start the server:

waylo
# or if installed from source:
npm start

Open browser: Navigate to http://localhost:8080
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
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

Development Mode

npm run dev

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

Configuration

Command Line Options

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.

Examples

Run on different port:

waylo --port=9000

Lower resolution (saves bandwidth):

waylo --width=1280 --height=720

Per-Session Settings (Login Screen)

Users can choose on login:

Frame Rate: 10 FPS (VPN) | 15 FPS (Balanced) | 20 FPS (LAN) | 30 FPS (Max)
Quality: Low (~1 Mbps) | Med (~2 Mbps) | High (~3 Mbps) | Max (~4 Mbps)

Architecture

Backend (Node.js)

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

Frontend (Svelte + Vite)

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

Data Flow

┌─────────────────────────────────────────────────┐
│              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

Why GNOME Mutter Instead of xdg-desktop-portal?

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

Manual Activation Required - PipeWire requires real user input to start
No Monitor Persistence - User must reselect monitors on each restart
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

MJPEG Streaming

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:

1. Create systemd User Service

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

Add the following content:

[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

2. Enable and Start Service

# Enable the service
systemctl --user enable waylo

# Start the service
systemctl --user start waylo

# Enable lingering (persist after logout)
loginctl enable-linger $USER

3. Install allow-locked-remote-desktop Extension

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

# 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 [email protected]

4. Enable Auto-Login (Optional but Recommended)

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:

[daemon]
AutomaticLoginEnable=true
AutomaticLogin=yourusername

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

5. Check Service Status

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

Login Screen

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

Remote Desktop Controls

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

Smart Features

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

Bandwidth Optimization

| 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 |

Network Recommendations

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

Security

Built-in Security Features

✅ 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

Current Limitations

⚠️ 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

Production Recommendations

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

Add TLS/WSS via Reverse Proxy

# nginx example
location / {
  proxy_pass http://localhost:8080;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
}

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

Troubleshooting

Server won't start

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

No video in browser

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

High CPU usage

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

Input not working

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

"Session creation inhibited" error

Error: "DBusError: Session creation inhibited"

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

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

Known Limitations

GNOME-Only - Requires GNOME desktop environment
Wayland - Designed for Wayland, may not work on X11
Session Requirement - User must be logged in
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