Guide: Enabling WayVNC Autostart

[MuNeNiCK]

Background

When running Omarchy on a remote server, it is often desirable to access a graphical desktop.
Omarchy is based on Hyprland, which allows creating a headless display that can be streamed over VNC.
By configuring autostart, WayVNC can be launched automatically whenever the Hyprland session starts.

How to Enable WayVNC Autostart

# Install WayVNC
sudo pacman -S wayvnc

# Edit autostart config
n ~/.config/hypr/autostart.conf

Add:

exec-once = bash -lc 'hyprctl output create headless VNC-1; \
  sleep 0.2; \
  hyprctl keyword monitor "VNC-1,1920x1080@60,auto,1"; \
  wayvnc -o VNC-1 0.0.0.0 5900'

After relaunching Hyprland, WayVNC will automatically start with the session,
exposing the VNC display on port 5900. Connect with:

{Omarchy server IP}:5900

Those who want to avoid entering the disk encryption password upon reboot can do so by following the steps below.
#1283

[MuNeNiCK]

By the way, when I operate Omarchy through WayVNC, sometimes workspace switching does not work as expected.
I suspect this happens because both a physical monitor and the headless Hyprland monitor exist at the same time,
but I’m not sure how to resolve it.

If anyone has a solution, please let me know.

[AlJohri]

Also running into the same issue using WayVNC with Jump Desktop (RDP, VNC, Fluid) on iPad.

[MSchmidt]

Seems like workspace 1 is stuck on the local monitor and somehow interferes with the other ones. Maybe it's possible to have the entire screen mirrored via VNC?

[ghzghz]

thanks for the info.
using this I was able to connect from my mac. I had to use VNCViewer, as the default mac VNC client would not connect without authentication.
Keyboard setting isn't correct yet, but I'll play around with that.

However one small niggle is that when changing themes, the resolution gets messed up.
Restarting Hyprland fixes the issue.

[MuNeNiCK]

I hope this was helpful.
Regarding the keyboard issue—are you copying and pasting the code below as is?

wayvnc -o VNC-1 -k jp 0.0.0.0 5900

If you specify a wayvnc option like -k jp, it will change the keyboard layout.
Setting it to your language might solve the problem.

https://man.archlinux.org/man/wayvnc.1

[ghzghz]

yes I had just cut paste with -k jp
that was the issue. Thanks.

still have the other issue now when 'hyprctl reload' messes up the resolution and input in the VNC session.
and I need to restart Hyprland.

but that's not a big thing.

[acrogenesis]

This helped me get started. In my use case when I need to connect through vnc I need to keep working on what was already on the screen so a virtual screen didn't apply. This is how I start wayvnc wayvnc -o DP-3 0.0.0.0 5900 then I also created this script to toggle my monitor resolution and the mac resolution.

toggle-resolution.sh

#!/bin/bash

MONITOR="DP-3"

# Grab the current resolution string (first field after the monitor header)
CURRENT=$(hyprctl monitors | awk -v mon="$MONITOR" '
    $2 == mon {getline; print $1}' )

if [[ "$CURRENT" == 5120x1440* ]]; then
    echo "Switching to MacBook-friendly resolution (2560x1600@60)..."
    hyprctl keyword monitor "$MONITOR,2560x1600@60,0x0,1"
elif [[ "$CURRENT" == 2560x1600* ]]; then
    echo "Switching back to Odyssey G9 native resolution (5120x1440@240)..."
    hyprctl keyword monitor "$MONITOR,5120x1440@240,0x0,1"
else
    echo "Current mode is $CURRENT — defaulting to Odyssey G9 native."
    hyprctl keyword monitor "$MONITOR,5120x1440@240,0x0,1"
fi

[acrogenesis]

I also added a binding bindd = SUPER SHIFT, R, Toggle Resolution, exec, /home/archogenesis/toggle-resolution.sh

[acrogenesis]

I created a small how-to https://acrogenesis.com/remote-access-to-omarchy-with-wayvnc-and-tailscale/

[arau-j]

How do you handle the disk encryption when using vnc? Is there a way to bypass need for physical usb keyboard on reboot?

[zigmoo]

Is there a way to use Apple's vanilla Screen Sharing app to connect to wayvnc?

[MuNeNiCK]

@arau-j
Actually, I’ve already resolved this issue.
The method uses software called Clevis along with TPM2 security, which automatically unlocks disk encryption during system startup.

The procedure is described below.
#1283

[MuNeNiCK]

This is a bit of an aside, but in environments without TPM2, the following approaches can also be considered:

• Using Clevis + Tang to automatically unlock disk encryption when accessing a specific network.
• Using Dropbear to SSH into the system during initramfs startup and manually enter the disk encryption password there.

[abdullahau]

• Using Dropbear to SSH into the system during initramfs startup and manually enter the disk encryption password there.

Hey, thanks for the really helpful guides! Can you tell me how I can set this method up given that my host machine running Omarchy runs only on WiFi? I'd like to remotely ssh into my host machine on reboot.

Thanks in advance.

[MSchmidt]

Mostly works but I cannot get SUPER SHIFT + <x> to pass. Only SUPER and only SHIFT works fine though. But for something like moving a tile into another workspace it would be useful to have this. Any idea?

[hieptuanle]

Heads-up for anyone on current Omarchy (3.8.0 / Hyprland 0.55): this recipe no longer auto-runs, because the Hyprland config moved from .conf to Lua. ~/.config/hypr/autostart.conf is not sourced by the new hyprland.lua; the entry point is now ~/.config/hypr/autostart.lua, which the main config loads via require("hypr.autostart").

Two adjustments:

1. Use autostart.lua, not autostart.conf. Register on the hyprland.start event:

   hl.on("hyprland.start", function()
     hl.exec_cmd([[bash -lc 'hyprctl output create headless VNC-1; sleep 0.2; wayvnc -o VNC-1 0.0.0.0 5900']])
   end)

2. Drop the hyprctl keyword monitor "VNC-1,…" line. Under the new (non-legacy) parser, hyprctl keyword errors with keyword can't work with non-legacy parsers. Use eval. It is also redundant — hyprctl output create headless VNC-1 already brings the output up at 1920x1080@60, which is what the keyword line was setting.

Validated on Omarchy 3.8.0 + Hyprland 0.55.0-4: wayvnc binds to 0.0.0.0:5900 on login, hyprctl configerrors is clean.