Installation

Installation

This guide covers installation, trial runs, and manual builds.

Requirements

• Wayland session.
• GTK4 + gtk4-layer-shell (pkg-config: gtk4-layer-shell-0).
• D-Bus session bus.
• A supported user service manager for installer-managed startup.
  • default: systemd --user
  • supported alternatives: dinit --user, user runit, and user s6-rc
• Rust toolchain for builds and the installer.

Optional widget backends:

• wpctl or pactl for volume.
• nmcli for Wi-Fi toggles.
• brightnessctl for brightness.
• bluetoothctl + dbus-monitor for Bluetooth.
• rfkill + udevadm for airplane mode.
• Optional Night backend: hyprsunset, gammastep, wlsunset, or sunsetr. UnixNotis creates editable helper scripts under the config directory when the shipped default Night toggle points at them.

Installer (recommended)

Downloaded release archives include unixnotis-installer at the archive root and the runtime binaries under bin/. Extract the archive, keep the files together, and run:

./unixnotis-installer

The archive also includes unixnotis-release.json. The installer checks that manifest and the listed bundled binaries before copying anything into $HOME/.local/bin.

When installing from a source checkout, the installer builds and installs binaries, writes config and theme files, and manages the selected user service:

cargo run --release -p unixnotis-installer

Installer actions:

• builds release binaries from source, or verifies bundled release binaries from an archive
• installs to $HOME/.local/bin
• writes config, theme files, and default helper scripts under $XDG_CONFIG_HOME/unixnotis
• adds a managed PATH block to the active shell startup file and .profile when needed
• writes and enables the selected user-service artifacts
• syncs the live Wayland session environment before starting the daemon
• adds a managed Hyprland startup block when an active Hyprland config is found

The installer shows the current UnixNotis version in the welcome screen and performs a best-effort GitHub release check. A failed update check does not block installation.

Reset and restore

The installer’s Reset config option opens a submenu:

• Reset to defaults: overwrites config.toml and theme CSS with bundled defaults.
• Restore backup: replaces current files with a selected backup snapshot.

Backups are created during reset and stored under: $XDG_CONFIG_HOME/unixnotis/Backup-YYYY-MM-DD

Retention is controlled by $XDG_CONFIG_HOME/unixnotis/installer.toml:

[backups]
keep = 3

After a successful install, the UI offers optional build acceleration. It can write a local .cargo/config.toml that uses a wrapper script for sccache and mold when available. This is opt-in, local to the repository, and safe to remove if not desired.

Build acceleration details:

• no files are written when neither sccache nor mold is available
• unmanaged existing .cargo/config.toml files are left alone
• installer-owned configs are recognized by the Generated by unixnotis-installer marker
• the wrapper prefers sccache, adds mold when available, and falls back to plain rustc
• Clippy is forwarded directly to avoid wrapper argument conflicts

Service manager selection

systemd --user is the default and remains the most tested path. Non-systemd setups can select another backend:

cargo run --release -p unixnotis-installer -- --service-manager dinit
cargo run --release -p unixnotis-installer -- --service-manager runit
cargo run --release -p unixnotis-installer -- --service-manager s6

The same setting can be exported for repeated installer runs:

UNIXNOTIS_SERVICE_MANAGER=runit cargo run --release -p unixnotis-installer

Accepted values:

• systemd or systemd-user
• dinit or dinit-user
• runit or runit-user
• s6 or s6-user

CLI selection takes priority over UNIXNOTIS_SERVICE_MANAGER.

Backend notes:

• systemd writes unixnotis-daemon.service under the user unit directory and runs systemctl --user daemon-reload when the unit changes.
• dinit writes a user service plus a boot.d enablement link. If the user boot service does not include boot.d, the installer can start UnixNotis now but warns that next-login autostart may need dinit user setup.
• runit writes a managed service directory with a generated run script. The chpst command must be available. UNIXNOTIS_RUNIT_SERVICE_DIR overrides the service root, then SVDIR, then $HOME/.config/service.
• s6 writes local s6-rc service source, compiles a local database, and updates the live user database. UNIXNOTIS_S6_DATA_DIR overrides the source/database root, and UNIXNOTIS_S6RC_LIVE_DIR overrides the live root.

For dinit, runit, and s6, verify the service state after installation. These backends are newer than the systemd path and depend more heavily on the user service setup already running correctly.

Session environment

The installer imports only the session values UnixNotis needs:

• WAYLAND_DISPLAY
• XDG_RUNTIME_DIR
• XDG_CURRENT_DESKTOP
• XDG_SESSION_TYPE
• XDG_SESSION_DESKTOP
• DISPLAY
• PATH

WAYLAND_DISPLAY and XDG_RUNTIME_DIR are required for installation from a live session. For systemd and dinit, the values are imported through the manager. For runit and s6, they are written into backend-owned env files before the service starts.

Shell PATH

Installed binaries are placed in $HOME/.local/bin. The installer adds a managed block:

# unixnotis-installer path entry
export PATH="$HOME/.local/bin:$PATH"

It updates the active shell startup file first (.zshrc for zsh, .bashrc for bash) and then .profile as a fallback. Existing PATH entries are detected, so repeated installs do not duplicate the block. The current terminal is not changed; open a new shell or export the PATH manually for the current session.

Hyprland startup

When Hyprland is detected, the installer updates the loaded Hyprland config with a managed UnixNotis bootstrap block. That block keeps the daemon environment fresh on new logins.

Current Hyprland Lua configs are preferred:

• $XDG_CONFIG_HOME/hypr/hyprland.lua
• fallback: $HOME/.config/hypr/hyprland.lua

Legacy hyprlang configs are still supported:

• $XDG_CONFIG_HOME/hypr/hyprland.conf
• fallback: $HOME/.config/hypr/hyprland.conf

If both files exist, UnixNotis targets the Lua config because newer Hyprland loads it first. Uninstall removes only the managed UnixNotis block and leaves user-managed startup lines alone.

Trial run

Trial mode temporarily replaces the current notification daemon and restores it on exit. Select “Trial run” in the installer UI.

Trial mode checks the current owner of org.freedesktop.Notifications, prints known notification daemon status, asks for confirmation, stops the active owner, and waits for the bus name to be released before UnixNotis starts.

Known daemons:

• mako
• dunst
• swaync
• notify-osd
• quickshell

Restore modes:

• auto: restart the matching systemd --user unit when active, otherwise restart the captured process command
• systemd: require an active known user unit and restore through systemctl --user start
• process: restore by spawning the captured argv from the previous process
• none: stop the previous daemon for the trial and do not restore it

Manual trial examples:

unixnotis-daemon --trial
unixnotis-daemon --trial --restore process
unixnotis-daemon --trial --restore none --yes

Trial mode only stops known daemons. If another process owns the notification bus, UnixNotis stops and reports that owner instead of guessing.

Build from source

cargo build --release

Run the daemon and UIs manually (Wayland session required):

cargo run --release -p unixnotis-daemon
cargo run --release -p unixnotis-center
cargo run --release -p unixnotis-popups

Open or close the panel:

cargo run --release -p noticenterctl -- open-panel
cargo run --release -p noticenterctl -- close-panel

User service

The installer manages the selected user service. The service runs the daemon from $HOME/.local/bin.

Common status commands:

systemctl --user status unixnotis-daemon.service
dinitctl --user status unixnotis-daemon
sv status "$HOME/.config/service/unixnotis-daemon"
s6-rc -l "${UNIXNOTIS_S6RC_LIVE_DIR:-/run/$USER/s6-rc}" -a list | grep unixnotis-daemon

Use the command that matches the selected backend and local service layout.

Uninstall

Run the installer and select uninstall to remove binaries, service files, and persisted state.

Uninstall removes only service artifacts that still match the installer-owned shape. If a service path was replaced with a symlink, special file, or unmarked directory, UnixNotis refuses to remove it automatically and prints the path for manual review.

First-run checklist

• Confirm the session type is Wayland (XDG_SESSION_TYPE=wayland).
• Confirm GTK4 + gtk4-layer-shell are installed.
• Confirm the compositor allows layer-shell surfaces.
• Run noticenterctl open-panel to validate panel control.