Installation

Home · User guide · Platform support

Tessera works alongside a window manager rather than replacing it. XFCE on X11 with Xfwm4 is the first-release target and historical supported profile; the repository’s support manifest currently marks its complete profile implemented-unverified. Distribution and release build are not pinned, and same-commit CI and real-session smoke evidence are still required. GNOME and Plasma Wayland, macOS and Windows are in development, not verified release profiles.

Packages and distribution channels

The repository contains build recipes, not proof of a published release or installable package. Check the project’s actual release announcements before relying on any channel; no public package availability is established here.

These are packaging or planned distribution paths, not instructions to install an unverified package. Source builds are available to developers and users willing to build locally; a successful build does not establish support for a desktop profile.

Build on Linux from a source checkout

Use a checkout or source archive obtained from the project; run the following from its root. The workspace requires Rust 1.99 and GTK 4.18 development files. The distribution package script .github/actions/install-distro-packages/install.sh lists the current CI build and test dependencies, including C/C++ build tools, pkg-config, GTK, XKB and Qt development packages; consult it for the appropriate Debian/Ubuntu, Fedora or Arch package names. Those names and recipes are not evidence of a supported distribution.

cargo build --release --locked -p tessera-app -p tessera-worker

The resulting programs are target/release/tessera and target/release/tessera-layout-worker. The default app build includes GTK. The worker is needed for custom JavaScript layouts; on Linux its sandbox requires Landlock and seccomp support. See Custom layouts.

To install the executables for your user from that checkout:

install -Dm755 target/release/tessera "$HOME/.local/bin/tessera"
install -Dm755 target/release/tessera-layout-worker "$HOME/.local/bin/tessera-layout-worker"

Ensure ~/.local/bin is on PATH. This copies binaries only; it does not install desktop entries, icons, UI plugins or a service. Alternatively, the repository contains native packaging recipes that stage integration files; consult each recipe before building a local package. No installation method automatically proves runtime support.

Optional desktop integration

The following commands install the application menu entry and icons for the current user. Run them from the source checkout. They can overwrite files with the same names; back up existing custom files first. The desktop session must find tessera on its PATH.

case ${XDG_DATA_HOME-} in
  /*) data_home=$XDG_DATA_HOME ;;
  *)  data_home=$HOME/.local/share ;;
esac
install -Dm644 crates/tessera-app/data/org.xfce.Tessera.desktop \
  "$data_home/applications/org.xfce.Tessera.desktop"
install -Dm644 crates/tessera-ui/assets/icons/org.xfce.Tessera.svg \
  "$data_home/icons/hicolor/scalable/apps/org.xfce.Tessera.svg"
install -Dm644 crates/tessera-ui/assets/icons/tessera-window.svg \
  "$data_home/icons/hicolor/scalable/apps/tessera-window.svg"
for icon in tessera-tray tessera-tray-disabled; do
  install -Dm644 "crates/tessera-ui/assets/icons/$icon.svg" \
    "$data_home/icons/hicolor/scalable/status/$icon.svg"
done

To opt in to starting Tessera at XFCE login, install the XDG autostart entry separately. This enables it for subsequent sessions; do not also enable the systemd user service. Back up any existing entry first.

case ${XDG_CONFIG_HOME-} in
  /*) config_home=$XDG_CONFIG_HOME ;;
  *)  config_home=$HOME/.config ;;
esac
install -Dm644 crates/tessera-app/data/org.xfce.Tessera-autostart.desktop \
  "$config_home/autostart/org.xfce.Tessera-autostart.desktop"

Alternatively, the CLI offers tessera service install, tessera service enable and tessera service start for the optional systemd user service; installation alone does not enable or start it. See the user guide.

Experimental GNOME Wayland integration

GNOME Wayland remains blocked in the support manifest, not a verified release profile. Its experimental adapter needs a GNOME Shell extension. Installing it is an explicit user choice, never an automatic step:

tessera gnome-extension status
tessera gnome-extension install

Installation asks for consent and attempts to enable the extension. Check its output for an enable failure; log out and back in so GNOME can load it, then start Tessera. To inspect the installed copy later, run the status command again. tessera gnome-extension remove asks for consent before disabling and removing it. These commands do not establish profile support.

Start and diagnose

In an XFCE/X11 session, tessera opens preferences and tessera --autostart starts the controller without opening preferences. Choose one login-start method, not both an XDG autostart entry and a systemd user service. tessera --help shows the available commands, and tessera --debug-info reports the detected session and capabilities. Review diagnostic output before sharing it.

For configuration and shortcuts see the user guide; for session problems see XFCE troubleshooting. Contributors should also read Development.