Installation
Install both Mantle binaries, create a config, check it, and start the shell. The
introduction provides a first bar to put in shell.lua.
Install
Releases carry the .deb, .rpm and tarball.
mantle-bin packages each release; mantle-git
and source builds follow main.
| Route | What to do |
|---|---|
| Arch | Install mantle-bin from the AUR for the latest release, or mantle-git to build main. Both install the PAM stack |
| Ubuntu, Fedora | Install a release package with sudo apt install ./mantle_<version>_amd64.deb or sudo dnf install ./mantle-<version>-1.x86_64.rpm. These packages install under /usr, with library dependencies and the PAM stack. They require Ubuntu 26.04 or Fedora 44 or later because the binaries need glibc 2.43 |
| Release tarball | sudo tar -xzf mantle-<version>-x86_64-linux.tar.gz -C / installs under /usr/local and leaves /etc alone, so an upgrade keeps your edits: copy the system files from /usr/local/share/mantle/ once. Install the required libraries yourself. It needs glibc 2.43 |
| From source | cargo build --workspace --release, then put target/release/mantle and target/release/mantle-renderer together on PATH, for example in ~/.local/bin. See build requirements |
| From a checkout, for development | just run [config] builds and runs a config (default share/starter). just swap builds an optimised pair into $CARGO_HOME/bin and restarts the running shell |
The mantle executable starts mantle-renderer from its own directory. Keep the two binaries
from the same build together (binaries).
Set up a config
mantle init
mantle check
init writes shell.lua and .luarc.json under ~/.config/mantle by default. It keeps files
that already exist; mantle init --force replaces them. Use -c DIR to work in another directory
(config selection). Then edit shell.lua or copy the
first bar into it. Run mantle check after edits to catch
Lua and layout errors before starting the shell.
The .luarc.json points lua-language-server at the lua-meta/ stubs. A package
installs them under $PREFIX/share/mantle/lua-meta. Otherwise init writes the binary’s embedded
copy to $XDG_DATA_HOME/mantle/lua-meta and updates changed stubs. mantle check reports when
those stubs need refreshing with mantle init. The editor config enables type, unbalanced,
strict, global and unused-local warnings.
Run the shell
From a terminal inside your Wayland session:
mantle -d
mantle log -f
-d returns after starting the shell and prints its pid. log -f follows its output. Run
mantle without -d to keep it in the foreground, or mantle stop to end a detached shell.
The CLI explains logs, multiple running shells and command flags.
To start it with your compositor session, add one of these lines to that compositor’s config:
# niri
spawn-at-startup "mantle"
# Hyprland
exec-once = mantle
Start Mantle inside the compositor session so workspaces, windows and keyboard can find niri
or Hyprland through that session’s environment.
Requirements
| Feature | Needs |
|---|---|
| Surfaces | A Wayland compositor with wlr-layer-shell-v1; ext-session-lock-v1 for lock |
window, popup | xdg-shell; these surfaces are skipped when absent |
capture | ext-image-copy-capture-v1, else wlr-screencopy-v1 |
compositor_blur = true | ext-background-effect-v1; ignored when absent |
| Fonts | fontconfig (fc-match) |
| Editor completion | lua-language-server |
A capability starts when the config first reads mantle.<name>. You need only the backends for
capabilities your config uses. Each capability page says what happens when its backend is missing.
| Capability | Backend |
|---|---|
notifications, tray | Session bus; no other notification daemon or tray host holding the name |
mpris | Session bus |
appearance | xdg-desktop-portal on the session bus; defaults without it |
network | NetworkManager |
bluetooth | bluetoothd, running before Mantle starts |
audio, privacy | PipeWire, running when the capability starts; it does not reconnect |
battery | UPower |
power | UPower, power-profiles-daemon |
brightness | A /sys/class/backlight device, logind |
keyboard | Read access to the /dev/input keyboard; niri, Hyprland, sway or mango for layouts |
workspaces | niri, Hyprland, sway or mango |
windows | niri, Hyprland, sway or mango, else wlr-foreign-toplevel-management-v1 |
idle | ext-idle-notify-v1, logind |
lock | ext-session-lock-v1, logind, the Mantle PAM stack (system files) |
polkit | polkitd with its helper socket /run/polkit/agent-helper.socket, $XDG_SESSION_ID, no other polkit agent running |
sysinfo | hwmon k10temp, coretemp or acpitz for CPU temperature; amdgpu, nouveau, nvidia, i915 or xe for GPU temperature; lsblk for disks; nvtop, nvidia-smi or DRM sysfs for GPU telemetry; /proc/net/dev for network throughput |
updates | pacman and its curl, dnf or apt-get; pkexec, answered by the polkit agent; paru or yay for AUR |
applications | $TERMINAL for Terminal=true entries, xdg-open for open_url |
clock, folders, storage and processes need nothing beyond the paths and programs the config
names.
Build from source
A source build needs Rust 1.99 or later, a C compiler and pkg-config for vendored Lua,
clang for PipeWire’s bindings, and development files for the linked libraries:
| Distro | Packages |
|---|---|
| Arch | base-devel clang pipewire pam systemd-libs wayland libxkbcommon libglvnd mesa |
| Fedora | gcc pkgconf-pkg-config clang pipewire-devel pam-devel systemd-devel wayland-devel libxkbcommon-devel mesa-libEGL-devel mesa-libgbm-devel |
| Debian, Ubuntu | build-essential pkg-config clang libclang-dev libpipewire-0.3-dev libpam0g-dev libudev-dev libwayland-dev libxkbcommon-dev libegl-dev libgbm-dev |
Use rustup where the distro’s cargo is older. Mantle is developed and run
on Arch. The Fedora and Debian package lists build the workspace in a container; running the
shell, and the updates capability’s dnf and apt backends, are untested on Fedora and Ubuntu.
System files
Packages install the files they need. The tarball puts them in /usr/local/share/mantle/, and a
source build has them in packaging/.
On Debian and Ubuntu, install the -debian variant of each PAM stack under the same name: they
include common-* where the others include system-auth.
| File | Install to | Without it |
|---|---|---|
pam.d/mantle | /etc/pam.d/mantle | Unlock uses the login stack, whose pam_nologin or pam_shells may refuse the right password. Polkit prompts use polkit’s own stack either way |
pam.d/mantle-fingerprint | /etc/pam.d/mantle-fingerprint | The lock screen takes no fingerprint |
polkit-1/rules.d/50-mantle-pacman.rules | /etc/polkit-1/rules.d/ | updates installs through pacman ask for a password on every pkexec; with it, a wheel user approves once per run |
Gotchas
| Trap | Fix |
|---|---|
cargo run -p supervisor runs a stale Renderer and reports the mismatch as a config error | Use just run, which builds both binaries |
| Another notification daemon, tray host or polkit agent is running | Stop it: Mantle takes those names only when free, and the tray waits in the queue (FAQ) |
See also: introduction, CLI, FAQ.
Source: init, binaries, capability wiring, PAM worker.