Complete Setup Guide

August 19, 2026 · View on GitHub

Installation

Package and direct release installs

If you installed wayscriber via a package (deb/rpm/aur) or the direct Arch release installer, enable the user service:

systemctl --user enable --now wayscriber.service

The service keeps the daemon running in the background; you only need a keybind to toggle the overlay.

Configurator setup (no CLI)

If you installed wayscriber-configurator, you can set this up entirely in GUI:

  1. Open wayscriber-configurator.
  2. Go to the Daemon tab.
  3. Click Install/Update Service.
  4. Click Enable + Start.
  5. Set your shortcut and click Apply Shortcut.

Desktop-specific shortcut handling:

  • GNOME: creates/updates a GNOME custom shortcut that runs wayscriber --daemon-toggle.
  • GNOME migrations: Install/Update Service and Apply Shortcut remove stale ~/.config/systemd/user/wayscriber.service.d/shortcut.conf files so old portal settings do not override GNOME behavior.
  • KDE/Plasma: writes a systemd user drop-in with WAYSCRIBER_ENABLE_PORTAL_SHORTCUTS=1 and WAYSCRIBER_PORTAL_SHORTCUT for portal global shortcut handling.
  • Hyprland: light passthrough controls use native Hyprland bindings, not the portal shortcut path.

Quick Install

Run the install script:

./tools/install.sh

This will:

  1. Build the release binary
  2. Copy it to /usr/bin/wayscriber (or $WAYSCRIBER_INSTALL_DIR)
  3. Refuse a second copy under /usr/local/bin or ~/.local/bin unless you pass --replace-other or confirm
  4. Optionally set up the systemd user service or a Hyprland keybind

If /usr/local/bin/wayscriber already exists from the direct Arch installer, keep only one prefix. Overlay spawn follows the running daemon file, not whichever path you passed to --version or --about.

Manual Install

If you prefer manual installation:

# Build
cargo build --release

# Copy to user bin
mkdir -p ~/.local/bin
cp target/release/wayscriber ~/.local/bin/
chmod +x ~/.local/bin/wayscriber

# Make sure ~/.local/bin is in your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Hyprland Keybind Setup

Method 1: Systemd user service + toggle (preferred when available)

systemctl --user enable --now wayscriber.service

For Hyprland Lua, add the toggle to ~/.config/hypr/bindings.lua:

o.bind("SUPER + D", "Toggle Wayscriber", "wayscriber --daemon-toggle")

For a traditional Hyprland config, add it to ~/.config/hypr/hyprland.conf:

# wayscriber - Screen annotation daemon (Super+D to toggle)
bind = SUPER, D, exec, wayscriber --daemon-toggle

Use only one toggle binding. Duplicate SUPER+D entries can fire twice and immediately undo the toggle. If your shortcut environment does not resolve wayscriber from PATH, use the absolute path from command -v wayscriber.

Method 2: Daemon autostart via compositor (no systemd)

For Hyprland Lua, add these to the matching files:

-- ~/.config/hypr/autostart.lua
o.launch_on_start("wayscriber --daemon")

-- ~/.config/hypr/bindings.lua
o.bind("SUPER + D", "Toggle Wayscriber", "wayscriber --daemon-toggle")

For a traditional Hyprland config, add this to ~/.config/hypr/hyprland.conf:

# wayscriber - Screen annotation daemon (Super+D to toggle)
exec-once = wayscriber --daemon
bind = SUPER, D, exec, wayscriber --daemon-toggle

Then reload:

hyprctl reload

Now press Super+D to toggle the overlay on/off!

Light passthrough controls on Hyprland

Light passthrough needs compositor/global shortcuts because Wayscriber deliberately passes keyboard and pointer input to the app below while passthrough is active. The default F6 binding is a Wayscriber in-overlay shortcut, not an OS-level shortcut; do not rely on it to exit after passthrough starts. Use the bindings below for reliable control.

For Hyprland Lua, add the manual bindings to ~/.config/hypr/bindings.lua:

local wayscriber = "wayscriber"

o.bind("F6", "Toggle Wayscriber light passthrough", wayscriber .. " --light-toggle")
o.bind("XF86Tools", "Toggle Wayscriber light passthrough", wayscriber .. " --light-toggle")
o.bind("SUPER + ALT + D", "Toggle Wayscriber light drawing", wayscriber .. " --light-draw-toggle")

The configurator can install a native include file for traditional Hyprland configs. Its manual equivalent is:

# wayscriber - light passthrough controls
$wayscriber = wayscriber

unbind = SUPER ALT, L
bind = SUPER ALT, L, exec, $wayscriber --light-toggle
unbind = SUPER ALT, D
bind = SUPER ALT, D, exec, $wayscriber --light-draw-toggle
unbind = SUPER ALT, F
bind = SUPER ALT, F, exec, $wayscriber --light-draw-on
bindr = SUPER ALT, F, exec, $wayscriber --light-draw-off

# Optional: lower side mouse button (commonly mouse:275; verify on your mouse)
bind = , mouse:275, exec, $wayscriber --light-toggle

Use --light-draw-on on key/button press and --light-draw-off on release for draw-while-held. In the traditional config example, the unbind lines prevent duplicate manual bindings for these same keys from firing twice. If your shortcut environment does not resolve wayscriber, replace it with the absolute path from command -v wayscriber.

Light passthrough on KDE Plasma / Fedora KDE

Enable the daemon first:

systemctl --user enable --now wayscriber.service

The configurator can set up the main overlay toggle through the desktop portal. Light passthrough controls are manual for now: add global shortcuts in KDE System Settings that run these commands:

wayscriber --light-toggle
wayscriber --light-draw-toggle
wayscriber --light-draw-on
wayscriber --light-draw-off

Use --light-toggle for passthrough on/off and --light-draw-toggle for sticky drawing. Draw-while-held needs a shortcut system that can run one command on press and another on release; if your KDE shortcut UI only supports activation commands, use the sticky draw toggle instead.

Light passthrough requires compositor overlay support through layer-shell. If Wayscriber reports that passthrough is unavailable, your session is using a fallback path where regular app windows cannot provide a reliable click-through overlay.

GNOME: Fedora Workstation and Ubuntu GNOME

GNOME setup works for the normal overlay toggle:

systemctl --user enable --now wayscriber.service

Then use the configurator's Daemon tab, or create a GNOME custom shortcut that runs:

wayscriber --daemon-toggle

Freeze prefers compositor-native wlr-screencopy or ext-image-copy-capture when either protocol is available, then falls back to the screenshot portal. On GNOME, Freeze works when that portal is available and responsive; the first use may show a desktop permission prompt. Portal capture can be slower than direct compositor capture. On mixed-DPI or multi-monitor layouts, Wayscriber accepts a portal image only when it can validate the active output's crop; otherwise Freeze fails instead of guessing at an origin or scale. Freeze and Zoom also require the active output to advertise a current mode. Connecting or disconnecting a monitor cancels any in-flight Freeze or Zoom capture, including on screens that did not change.

Light passthrough mode is not available in the regular app on stock GNOME Wayland. GNOME's xdg-shell fallback does not expose the shell-level overlay behavior needed to keep annotations visible while input goes to apps underneath, so --light-toggle is intentionally disabled instead of pretending to pass input through. A GNOME Shell extension companion would be the real path for that workflow.

Method 3: One-Shot Mode (Alternative)

For quick one-time annotations without daemon:

# Run directly (not recommended - daemon mode is better)
wayscriber --active

This starts a fresh overlay each time. Exit with Escape.

Note: We recommend using daemon mode with Super+D instead as it preserves your drawings.

Usage Flow

  1. Daemon starts automatically → Runs in background with system tray icon (systemd user service or compositor autostart)
  2. Press Super+D → Drawing overlay appears
  3. Draw your annotations → All tools available
  4. Press Escape or Ctrl+Q → Overlay hides (daemon keeps running)
  5. Press Super+D again → Overlay reappears with previous drawings intact

No system tray/StatusNotifier watcher? Start the daemon with wayscriber --daemon --no-tray (or set WAYSCRIBER_NO_TRAY=1) to skip the tray icon; the Super+D toggle still works.

One-Shot Mode Workflow (Alternative)

  1. Run command → Fresh drawing overlay appears
  2. Draw your annotations → All tools available
  3. Press Escape → Drawing overlay closes completely
  4. Run command again → New fresh overlay (previous drawings lost)

Note: Daemon mode with Super+D is recommended as it preserves your drawings when you toggle the overlay.

Verification

Test the setup:

# Test binary is accessible
which wayscriber

# Test daemon mode
systemctl --user status wayscriber.service || wayscriber --daemon &

# Test keybind
Press <kbd>Super+D</kbd> (should show overlay)
Press <kbd>Escape</kbd> (should hide overlay)

Autostart

  • If you enabled wayscriber.service, systemd handles autostart.
  • If you used compositor autostart, the exec-once line starts wayscriber on login.

Troubleshooting

Keybind not working?

  • Check hyprctl reload was run
  • Check for conflicts: hyprctl binds | grep "SUPER, D"
  • Make sure you only defined the toggle once
  • Try a different key combo
  • If wayscriber is not found from the compositor, use the absolute path from command -v wayscriber

Binary not found?

  • Check type -a wayscriber and the path you installed to (/usr/bin, /usr/local/bin, or ~/.local/bin)
  • If you used ./tools/install.sh, the default dest is /usr/bin/wayscriber (or $WAYSCRIBER_INSTALL_DIR)
  • If you copied the binary by hand, add ~/.local/bin to PATH (see Manual Install) and restart the terminal

Settings or --about do not match the binary you just built?

  • Two copies can exist: the direct installer uses /usr/local, source tools/install.sh uses /usr/bin, and a manual copy may live in ~/.local/bin.
  • Check type -a wayscriber, systemctl --user show wayscriber.service -p ExecStart,MainPID,FragmentPath, and readlink -f /proc/$(systemctl --user show -p MainPID --value wayscriber.service)/exe.
  • --version is the crate version and can be identical on both copies. --about opens a window; use it on the path you intend to run, not as a substitute for the running daemon path.
  • Keep one prefix. ./tools/install.sh --replace-other removes the other known copies when installing to /usr/bin.

Want different key?

  • Edit bindings.lua or hyprland.conf, depending on your Hyprland config format
  • Examples:
    • SUPER, D → Super+D
    • ALT, D → Alt+D
    • CTRL SHIFT, 2 → Ctrl+Shift+2

Uninstall

If you used ./tools/install.sh (default /usr/bin):

sudo rm -f /usr/bin/wayscriber
systemctl --user disable --now wayscriber.service
# Remove the keybind from bindings.lua or hyprland.conf

If you copied the binary by hand to ~/.local/bin:

rm ~/.local/bin/wayscriber
# Remove the keybind from bindings.lua or hyprland.conf

Best setup (daemon mode):

  1. Install: ./tools/install.sh
  2. Add the daemon autostart and toggle binding using Method 2 above.
  3. Reload: hyprctl reload
  4. Use: Press Super+D to toggle overlay

Done! Drawings persist, tray icon available. ✨