project-monitorize

https://github.com/user-attachments/assets/14a21a68-011b-43bf-9f26-fc9ea731d80b

Monitorize creates and manages virtual displays on Linux using compositor-native outputs or monitorize-vkms. Use virtual displays on their own, or stream them to another device through built-in Sunshine integration.

For streaming, connect with Moonlight on Android, Linux, Windows, macOS, iOS, or another supported device.

Installation prompt for AI agents

Copy this prompt into an AI assistant of your choice for help installing and configuring Monitorize on your Linux host.

Help me install and configure Project Monitorize on my Linux host.

Before taking any action on my host, read both READMEs and every page in
each repository's GitHub wiki, where available. If a repository has no wiki,
use its README and in-repo documentation for setup.

Project Monitorize
https://github.com/vinnavannewton/project-monitorize
https://github.com/vinnavannewton/project-monitorize/wiki

Monitorize VKMS
https://github.com/vinnavannewton/monitorize-vkms

1. Use what I have already told you. If my goal is unclear, ask whether I want
   a tablet or laptop as a second display, both as two additional displays
   alongside my existing monitor, or remote desktop access from the login
   screen. For remote desktop, find out whether the host has a usable physical
   display at sign-in or is headless. Identify the host's distro and release,
   running kernel, desktop environment, and Wayland or X11 session. For boot
   access, check the display manager separately. Inspect the host if you can
   and ask only for the missing details.

2. Check the current desktop support table and open the installation guide
   linked for my distro.
   https://github.com/vinnavannewton/project-monitorize#supported-desktops
   https://github.com/vinnavannewton/project-monitorize#installation

   Prefer compositor-native displays for a supported desktop extension setup.
   Use Monitorize VKMS where native creation is unavailable and VKMS is
   supported, or when I need login-screen hosting. Compositor-native capture
   can request screen-sharing permission. If I want to avoid recurring
   prompts, check whether my setup supports VKMS with direct capture. Help me
   enable Passwordless Display Creation if I want VKMS displays without
   recurring password prompts. Complete any first-run input, firewall, and
   capture authorization needed for the chosen setup.

3. If VKMS is needed, check Secure Boot and follow the current VKMS install
   instructions for my distro, including matching kernel development files.
   Verify the installed module with monitorize-vkms verify.
   https://github.com/vinnavannewton/monitorize-vkms#prerequisites

   Recommend disabling Secure Boot in BIOS/UEFI as the simpler VKMS setup
   path. Explain that this removes Secure Boot protection. If I choose it,
   guide me through my machine's firmware settings and verify after reboot.
   If I prefer to keep Secure Boot enabled, read and follow the current
   project wiki guide for signing-key enrollment.
   https://github.com/vinnavannewton/project-monitorize/wiki/Enroll-a-Secure-Boot-Key

4. For an extra screen, configure one Extend display. For a tablet and
   laptop together, configure two Extend displays and pair each Moonlight
   client with its own Monitorize listener.

   For login-screen access, install Monitorize VKMS and the matching
   remote-login components. Check display-manager support for the requested
   setup and select Monitorize Auto or KMS capture. Enable boot hosting with
   monitorize boot enable. In the GUI, this is Also start at boot (login
   screen) under Start Monitorize after login in Settings > General.
   Leave Create virtual display at login off when a usable physical display
   is attached, including when I use Extend or Virtual displays only after
   signing in. On a supported headless host, enable it with
   monitorize boot login-virtual-on. Explain any display-manager limitation
   before changing boot settings.

   For remote login or a headless display setup, recommend SSH as a recovery
   option. With my approval, restrict inbound SSH to my intended trusted LAN
   or VPN interfaces or source networks before enabling the SSH server on
   the streaming host at boot. Verify that I can connect from another device
   on the intended network and that SSH is unreachable from untrusted
   networks before relying on it for recovery.

   Explain that SSH gives me terminal access if a distro update, Monitorize
   crash, or configuration problem leaves the graphical session or stream
   unavailable. Show me how to check monitorize status and locate and edit
   monitorize.json with monitorize config path. Use monitorize reload to apply
   settings when the controller is available. For desktop-managed hosting,
   monitorize start requires an active local graphical session for my user.
   If I need streaming before desktop login, guide me through enabling and
   testing login-screen boot hosting on a supported setup using step 4.

5. Summarize the setup you chose for my goal. If you have terminal access to
   my host, use the Monitorize CLI and JSON to configure it for me. Follow the
   Terminal and SSH section for the right launcher. Run monitorize config path
   to generate or locate monitorize.json from my current settings. Edit the
   requested settings in that file, apply them with monitorize reload, and
   check the result. Use the setup and boot commands for system permissions
   and boot policy. Use monitorize start and monitorize status to check that
   the requested session is ready.

   Confirm with me before making privileged changes or rebooting. If a step
   needs me to approve a prompt, change firmware settings, or run a command,
   give me the exact step and wait for my result. Verify it and resume.
   If you have no host access, give me the CLI commands and guide me using
   the results I share.
   https://github.com/vinnavannewton/project-monitorize#terminal-and-ssh

6. Help me pair in Moonlight and check video and input on each requested
   display. For boot hosting, test the login screen and reconnect to the
   desktop after signing in. Ask me to confirm tests that require my
   Moonlight device. Finish by telling me how to connect and what you verified.

Features

• Create and manage up to two virtual displays.

• Support compositor-native virtual displays and monitorize-vkms.

• Stream virtual displays or mirror an existing monitor through Sunshine.

• Configure streaming encoders, codecs, audio, touch, and stylus options via the integrated sunshine.

• Keeps Monitorize's Sunshine instances separate from your existing Sunshine setup.

Supported desktops

This table shows whether each desktop environment supports via compositor-native virtual displays, monitorize-vkms, or both.

Desktop Environment	Compositor	monitorize-vkms
KDE Plasma 6.7+	✅	✅
GNOME 50+	✅	✅
Hyprland (Aquamarine 0.15.1+ for VKMS)	✅	✅
Niri	❌	✅
Cinnamon X11	❌	✅
COSMIC	❌	❌

Installation

• Fedora
• Arch Linux
• Ubuntu
• openSUSE Tumbleweed
• NixOS / Nix

Contributing

Want to contribute? See the Contributing guide.

Usage

For DEs with no compositor-native virtual display support, use via VKMS by installing monitorize-vkms.

Tip: If the stream is black or crashes, try changing the stream from auto to other options in monitorize based on what your hardware supports.

Star History