Install and run¶

Use current stable Rust with rustfmt and clippy, and Python 3 for development scripts. On Debian/Ubuntu, build dependencies include:

sudo apt install build-essential cmake pkg-config libssl-dev libdbus-1-dev \
  libx11-dev libxkbcommon-dev libwayland-dev
cargo run --release

Linux credentials require a working Secret Service, such as GNOME Keyring or KeePassXC with Secret Service enabled. Windows uses Credential Manager; macOS uses Keychain. Linux file dialogs use the desktop portal, so install your desktop's xdg-desktop-portal implementation.

Install the optimized production build for your Linux user:

bash scripts/install-linux.sh
# Optionally pin it to the GNOME dash as well:
bash scripts/install-linux.sh --pin

The installer builds with --release --locked --no-default-features, installs ~/.local/bin/shep, and registers Shep in the applications menu. Right-click it and choose Add to Favorites or your panel's pin action. --pin supports GNOME and preserves existing favorites. KDE and other panels can pin the launcher through their normal menus. The desktop entry and window use so.shep.Shep, following the freedesktop launcher specification and iced's application ID guidance.

Shep reuses one running application per profile catalogue directory. Opening the launcher again restores its window, including after minimising or closing to the tray. Separate data directories remain independent. Opening Shep after an install asks a running older build to quit and takes over on the new one, or shows a notice to quit it from the tray when it does not answer; the installer prints the same advice when a Shep is still running the replaced binary. After upgrading from a version without launch ownership, quit the older copies normally before starting the new build; updating the executable does not replace running code. The launcher declares StartupNotify=false: Shep does not complete that desktop protocol, and advertising it leaves later GNOME dock activations waiting.

An extracted release archive includes the installer and can be installed without Rust. You can also supply an existing binary:

bash scripts/install-linux.sh --binary /path/to/shep
bash scripts/install-linux.sh --uninstall    # keeps accounts, mail, drafts and backups

--prefix changes the binary prefix; --data-dir changes launcher/icon placement. Launcher files otherwise follow XDG_DATA_HOME. Do not run the user installer with sudo. App images are cached WebP; the desktop launcher has a small PNG compatibility icon for Linux icon themes.