Omarchy

Install the host on Omarchy 4.x and wire it into the desktop with one command. Omarchy is Arch underneath, so the repo and packages are the Arch ones; only the install line and the desktop wiring differ.

One command instead? The guided installer (preview) runs every step below, punktfunk-omarchy setup included:

curl -fsSL https://punktfunk.unom.io/install.sh | sh

1. GPU driverCopy Anchor Link

Same as Arch: sudo pacman -S --needed nvidia-utils on NVIDIA; on AMD and Intel, the Mesa stack you already have.

2. Install and wire it inCopy Anchor Link

curl -fsS https://git.unom.io/api/packages/unom/arch/repository.key | sudo pacman-key --add -sudo pacman-key --lsign-key E0CA04465C99C936E0B0C6510A317015A34DDD69grep -q '^\[punktfunk\]' /etc/pacman.conf || printf '\n[punktfunk]\nServer = https://git.unom.io/api/packages/unom/arch/$repo/$arch\n' | sudo tee -a /etc/pacman.conf >/dev/nullsudo pacman -Sysudo pacman -S punktfunk-host punktfunk-web punktfunk-scripting punktfunk-clientpunktfunk-omarchy setup

The last line, punktfunk-omarchy setup, does the rest. Each step is safe to re-run:

To skip a part, pass --groups=0, --cert=0, --toasts=0, --idle-guard=0, --theme=0 or --menu=0. The guided installer asks about toasts, idle and theme on its own settings screen. punktfunk-omarchy status shows what is on.

3. PairCopy Anchor Link

Open Punktfunk Web Console from Apps and pair your first device. From a terminal instead:

punktfunk-host ctl pair arm      # opens a pairing window and prints the PIN
punktfunk-host ctl pending       # devices waiting, with name and fingerprint tail
punktfunk-host ctl approve 1

The Punktfunk Host submenu has the same actions. Every verb: ctl.

Dedicated display or This screenCopy Anchor Link

Pick one from Punktfunk Host in Apps, from the bar widget's Display tab, or with punktfunk-omarchy mode dedicated / mode mirror (mode --status shows the current one). Switching restarts a running host and ends its stream. This screen is the Streamed screen setting.

The bar widgetCopy Anchor Link

Click the Punktfunk mark for a panel with five tabs: Overview, Pair, Devices, Display and Stats. A waiting device opens Pair. Right-click the mark to stop a live session, or to open the web console when nothing is streaming.

Keys: 1–5 or h / l switch tabs, j / k move, Enter activates, Esc closes.

FirewallCopy Anchor Link

setup opens punktfunk-native and punktfunk-web to 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12 and tailscale0. The Tailscale rule waits dormant until the interface exists. punktfunk-gamestream opens only while GameStream is on, which GameStream in the menu sets. A management port moved off 47990 opens too. Video needs no rule; see Ports.

UpdatingCopy Anchor Link

omarchy update updates Punktfunk with the rest of the system, after its snapper snapshot. The console's Updates card shows that command instead of an Update now button. A rollback reverts the binaries only; your pairings and ~/.config/punktfunk stay.

Next to SunshineCopy Anchor Link

Omarchy can install Sunshine as a service. Both hosts want TCP 47990, and GameStream uses exactly Sunshine's ports.

• The guided installer moves Punktfunk's management API to 47991 when Sunshine, Apollo or Vibeshine is running or enabled, and setup opens that port. By hand: add PUNKTFUNK_MGMT_BIND=0.0.0.0:47991 to ~/.config/punktfunk/host.env, then re-run punktfunk-omarchy setup.
• Leave GameStream off while Sunshine runs; only one host can bind those ports.

To switch for good, run omarchy remove service sunshine. See Switching from Sunshine.

Moonlight (GameStream)Copy Anchor Link

Punktfunk's own clients don't need it. For stock Moonlight on a trusted LAN, choose Punktfunk Host → GameStream in Apps: it turns on the console's GameStream setting, restarts the host and opens the ufw profile. Enter the PIN a Moonlight client shows with Punktfunk Host → Moonlight PIN.

This box as a clientCopy Anchor Link

The install line includes punktfunk-client. It follows the Omarchy theme live; turn that off with Follow the Omarchy theme in its preferences, or Follow system theme in the game console's settings. Hosts in the Omarchy menu in preferences (or punktfunk-client --omarchy-menu on) adds a Punktfunk submenu with a connect row per saved host, a wake row where the MAC is known, and the game console. setup turns it on for you.

Good to knowCopy Anchor Link

• Sessions. The host starts at login on both Hyprland login sessions. Only Hyprland (uwsm-managed) also restarts it with the session; punktfunk-omarchy status says which one you run. It rarely matters: the host finds the live compositor on every connect.
• Keep-alive. A disconnect keeps the virtual display for the keep-alive window, then moves its workspace to a physical monitor. Release it early in the console (Displays → Release) or with punktfunk-host ctl display release.
• Screen sharing. During a stream the host borrows Omarchy's screen-share picker setting and hands it back when the last stream ends. Browser shares keep working.
• Your own hooks. If ~/.config/punktfunk/hooks.json already exists, setup prints the toast and idle entries for you to add instead of editing it.
• Snapshot mirror. Omarchy pins Arch packages to a snapshot. If pacman reports an unsatisfiable dependency, wait for the next omarchy update.
• Disk encryption. Omarchy encrypts the disk by default, so a Wake-on-LAN cold boot stops at the passphrase. Suspend the box instead.

TroubleshootingCopy Anchor Link

Run punktfunk-omarchy status first. It checks the units, ufw rules, groups, the portal and Hyprland's permission mode in one pass.

Black frames, or input does nothingCopy Anchor Link

Hyprland's permission enforcement is on and silently denies the host. Add to your Hyprland config:

o.permission("/usr/bin/punktfunk-host", "screencopy", "allow")
o.permission("/usr/bin/punktfunk-host", "plugin", "allow")

No picture at allCopy Anchor Link

Capture goes through xdg-desktop-portal-hyprland. Check it with systemctl --user status xdg-desktop-portal-hyprland.

The host isn't running after a rebootCopy Anchor Link

Autostart is off. Re-run punktfunk-omarchy setup.

Physical monitors stay dark after a disconnectCopy Anchor Link

The virtual display is still in its keep-alive window. Release it as above; see Virtual displays.

More in Troubleshooting and on the Hyprland page.

UninstallCopy Anchor Link

punktfunk-omarchy remove
sudo pacman -R punktfunk-host punktfunk-web punktfunk-scripting punktfunk-client   # the ones you have

remove undoes every setup step and restores the tray icon and the screen-share picker. Your groups, pairings and ~/.config/punktfunk stay; Uninstall clears them.