MIRU-DAEMON(1)

📦 version 0.14.0, in nixpkgs unstable

✨ MIRU-DAEMON(1) ✨

okay so this is the manual for miru-daemon — the Wayland-native screen magnifier and cursor spotlight daemon, and honestly it's giving main character energy 💅

🌸 NAME 🌸

miru-daemon — the Wayland-native screen magnifier and cursor spotlight daemon 🦋

🎀 SYNOPSIS 🎀

miru-daemon [options]

💖 DESCRIPTION 💖

miru-daemon is a long-running Wayland client. Like, it just sits there. It connects to the compositor, listens on a Unix socket, and stays completely idle until miructl(1) sends it a command. lowkey the chillest process on your whole system 😭

On toggle, it captures one frame via wlr-screencopy, shows it in a fullscreen wlr-layer-shell overlay, and lets you zoom, pan, highlight the cursor, draw simple annotations, and open an on-screen help panel. A second toggle (or Esc when help is closed) tears the overlay down. The underlying desktop is not continuously re-captured while the overlay is visible — it's a snapshot, bestie, not a livestream 🙈

Control is only through miructl(1) (toggle / quit). Global hotkeys must be bound in the compositor to run miructl toggle.

✨ OPTIONS ✨

  • -h, --help — prints usage and dips. ✌️
  • -v, --version — prints the version, then exits.
  • --gen-config, --interactive — walk through options and write $XDG_CONFIG_HOME/miru/config.toml. guided tour vibes 🧚

🌈 COMMANDS (via miructl) 🌈

See miructl(1). Typical usage:

miructl toggle

miructl quit

that's it. that's the whole command set. iconic, honestly 👑

💜 ENVIRONMENT 💜

  • MIRU_DEBUG — if set to a non-zero value (e.g. 1), print verbose diagnostics (input, zoom, texture upload, annotate/help toggles, and similar). Unset or 0 for normal logging. it's the "tell me everything" switch 🍓
  • WAYLAND_DISPLAY, XDG_RUNTIME_DIR — standard Wayland / runtime directory variables. The control socket is $XDG_RUNTIME_DIR/miru.sock.
  • XDG_CONFIG_HOME — if set, config is read from $XDG_CONFIG_HOME/miru/config.toml; otherwise $HOME/.config/miru/config.toml.

🦋 CONFIGURATION 🦋

Config path, fr fr:

$XDG_CONFIG_HOME/miru/config.toml # or
$HOME/.config/miru/config.toml

The directory and a default file are created on first launch. The file is watched; most options hot-reload without restarting the daemon. no restart required, we love a glow-up in real time ✨

Default:

[zoom]
factor = 2.0
increment = 0.25
max_factor = 10.0
smooth = false
upscale = "bicubic"

[spotlight]
radius = 250
dim = 0.65
softness = 20
animation_speed = 14.0
radius_step = 20.0

[general]
show_cursor = true
status_badge = true

[annotate]
default = "rect"
thickness = 4.0
color = "ff3333"
text_color = "ffd933"
text_size = 1.0

[loupe]
shape = "rect"

[export]
format = "png"

[filter]
default = "none"

[zoom]

  • factor — initial zoom on each toggle-on (min 1.0).
  • increment — zoom step for keys/scroll.
  • max_factor — maximum zoom.
  • smooth — interpolate zoom/pan when true.
  • upscale — Choose between linear/normal/bicubic for upscaling.

[spotlight]

Cursor Highlight while magnifier is active, toggled with Tab 🔦

  • radius, dim, softness — circle size, outside darkness, edge feather.
  • animation_speed — ease in/out speed for Tab.
  • radius_step — step for Shift+Plus/Minus and Ctrl+scroll.

[general]

  • show_cursor — hide the hardware cursor while the overlay is active when false (compositor-dependent).
  • status_badge — Choose to display the status badge (true/false).

[annotate]

  • default — Default shape when entering annotation mode.
  • thickness — Thickness of the stroke (1-8).
  • color — Hex RGB for annotation.
  • text_size — Size of annotation text (0.25 - 8.0).
  • text_color — Hex RGB for annotation text.

[loupe]

  • shape — Default shape when entering loupe mode.

[export]

  • format — File format of exported image.

[filter]

  • default — The default image filter to apply when the overlay is active.

Full detail (the reading material, iykyk): https://codeberg.org/Vaishnav-Sabari-Girish/miru#configuration

💅 CONTROLS (while overlay is active) 💅

  • Mouse move — Pan.
  • Scroll or + / - — Zoom.
  • WASD / arrow keys — Pan (key repeat supported).
  • Tab — Toggle Cursor Highlight.
  • Shift+Plus / Shift+Minus or Ctrl+scroll — Adjust highlight radius.
  • Shift+A — Toggle annotate mode (pan frozen; orange frame). W — arrow tool; R — rectangle; drag LMB — place; CTRL+Z/Y - Undo/Redo; P - freehand; C — clear.
  • B — Toggle Status Badge (Displays the zoom factor and the annotation tool chosen).
  • F — Shift between different image filters (Normal, Grayscale, Inverted/Negative, High Contrast).
  • Shift+H or ? — Toggle help panel. Esc closes help first if open.
  • Shift+E — Export current view to a .bmp file. The file is stored at $HOME/Pictures/miru/ 📸
  • Esc or compositor toggle keybind (miructl toggle) — Exit magnifier (after closing help if needed).

⭐ SYSTEMD ⭐

Example user unit at ~/.config/systemd/user/miru.service:

[Unit]
Description=Miru Zooming Daemon
PartOf=graphical-session.target
After=graphical-session.target
ConditionEnvironment=WAYLAND_DISPLAY
ConditionPathExists=%h/.local/bin/miru-daemon

[Service]
ExecStart=%h/.local/bin/miru-daemon
Restart=on-failure
RestartSec=1

[Install]
WantedBy=graphical-session.target

then:

systemctl --user enable --now miru.service

Adjust paths if binaries are installed elsewhere. 🫶

🔥 KEYBINDS (compositor) 🔥

Bind a key to miructl toggle in your compositor (Niri, Hyprland, Sway, Mango, etc.). The daemon must already be running — obviously, bestie, you can't poke something that isn't there 💀

See: https://codeberg.org/Vaishnav-Sabari-Girish/miru#setting-up-a-keybind

🌸 NOTES 🌸

Wayland does not expose a global pointer position while the overlay is inactive. The zoom view prefers the last pointer position from a previous session in the same daemon process when available. so it's a memory thing, not a stalker thing 🙈

Requires wlr-layer-shell-unstable-v1 and wlr-screencopy-unstable-v1.

GNOME (Mutter) and KDE Plasma (KWin) are not supported. 😭 not us being exclusive, it's literally a protocol thing.

🎀 SEE ALSO 🎀

miructl(1)

👑 AUTHORS 👑

Maintained by Vaishnav Sabari Girish <vaishnav.sabari.girish@gmail.com>.

Sources:

Issues and pull requests: https://codeberg.org/Vaishnav-Sabari-Girish/miru and https://github.com/Vaishnav-Sabari-Girish/miru (The issues are synced)

and that's the whole page, bestie 🫶 this was Miru, dated 2026-10-28, manual MIRU-DAEMON(1) — go forth and magnify, you absolute icon 💖✨

📦 where this page comes from