User guideWayseer 0.28.3Contents

Installing on Linux

Wayseer comes in four Linux packages. None needs Go, and each holds one program, wayseer, with every data source built in, SQL and Kubernetes among them.

Each package brings its own SDL3 3.4.16, the library that opens the window and draws. The app uses the packaged copy before your system's. Setting WAYSEER_SDL3 to a library's full path makes it use that one instead. The machine needs only what a desktop already has: a Vulkan driver (Mesa, or your GPU vendor's) and the Wayland or X11 libraries.

A package runs on any distribution with glibc 2.31 or newer: Debian 11, Ubuntu 20.04, Fedora 32 and everything since. It does not matter where the package was built.

bin/wayseer in the tarball and the AppImage is a small launcher, and the app itself is lib/wayseer/wayseer. Where glibc's loader is in its usual place, the launcher simply starts the app. Where it isn't, as on NixOS and Guix, the launcher starts the app through the loader your system's own /bin/sh uses, so the same signed package runs there too (see NixOS and Guix).

Distributions built on musl instead of glibc, such as Alpine, can't run the AppImage or the tarball. There the launcher says so and points to the Flatpak, which brings its own C library.

AppImage

chmod +x wayseer-*-x86_64.AppImage
./wayseer-*-x86_64.AppImage

It mounts itself with FUSE, which most desktops have (the fuse3 package). Without FUSE, add --appimage-extract-and-run. It adds no menu entry; use the tarball for that. Flags go after the file name, as for wayseer itself: ./wayseer-*.AppImage --config my.yaml.

Tarball

The tarball is laid out like /usr, with bin/, lib/wayseer/ and share/, so it unpacks straight into a prefix. For your user only:

tar -xzf wayseer-*-linux-x86_64.tar.gz -C ~/.local --strip-components=1

That puts wayseer in ~/.local/bin, which most distributions put on PATH, and adds Wayseer to the application menu with its icon. To remove it, delete ~/.local/bin/wayseer*, ~/.local/lib/wayseer/, ~/.local/share/applications/wayseer.desktop, ~/.local/share/icons/hicolor/scalable/apps/wayseer.svg and ~/.local/share/licenses/wayseer/.

NixOS and Guix

The AppImage and the tarball start on NixOS without nix-ld or steam-run. SDL3 still has to find the Wayland or X11 libraries and the Vulkan loader, and NixOS keeps those off the usual search path. If it doesn't find them, Wayseer opens no window and says where to get them. Any one of these provides them:

• the Nix package, which installs the same signed tarball
• appimage-run ./wayseer-*-x86_64.AppImage, or steam-run for the tarball's bin/wayseer (0.27.2 refuses to start there; 0.28.0 starts)
• LD_LIBRARY_PATH naming nixpkgs' wayland, libxkbcommon, vulkan-loader and the X11 libraries; the launcher passes it on to the app
• the Flatpak

With hardware.graphics.enable, the drivers in /run/opengl-driver are used.

On Guix the launcher starts the app the same way. Pointing it at the GPU drivers there hasn't been tried.

Flatpak

Download wayseer-<version>-x86_64.flatpak from wayseer.app, then install it for your user and run it:

flatpak install --user wayseer-*-x86_64.flatpak
flatpak run org.wayseer.Wayseer

Installing it fetches the Freedesktop 25.08 runtime from Flathub, and adds Flathub as a remote if you don't have it; Wayseer itself comes from the file. It is not on Flathub. It adds a menu entry, and it never updates itself. To update it, install the newer bundle over it; the config and state stay:

flatpak install --user --reinstall wayseer-*-x86_64.flatpak

The tarball and the AppImage are signed with Wayseer's release key, which the app checks when it updates them. The Flatpak is not; check it against the SHA256SUMS file served beside it, at https://wayseer.app/v1/app/<version>/SHA256SUMS:

sha256sum -c --ignore-missing SHA256SUMS

The sandbox lets Wayseer draw (Wayland, or X11 as a fallback, and the GPU), reach the network for Prometheus, Kubernetes and SQL, and list this machine's systemd units. It follows the desktop's light or dark setting through the Settings portal, which needs no permission.

It sees no other files. The config and state live inside the sandbox, under ~/.var/app/org.wayseer.Wayseer/, so the config is ~/.var/app/org.wayseer.Wayseer/config/wayseer/config.yaml. To bring over a config you already have, copy it in, or let the app read it where it is:

mkdir -p ~/.var/app/org.wayseer.Wayseer/config && cp -r ~/.config/wayseer ~/.var/app/org.wayseer.Wayseer/config/
# or
flatpak override --user --filesystem=xdg-config/wayseer:ro org.wayseer.Wayseer
flatpak run org.wayseer.Wayseer --config ~/.config/wayseer/config.yaml

When your config names a file or folder, such as a file module's CSV, a secret_file or a kubeconfig, let the app read it:

flatpak override --user --filesystem=~/inventory:ro org.wayseer.Wayseer
flatpak override --user --filesystem=~/.kube:ro org.wayseer.Wayseer

For a secret_keyring, let it reach the keyring:

flatpak override --user --talk-name=org.freedesktop.secrets org.wayseer.Wayseer

Inside the sandbox, this machine shows the host, its hardware and its systemd units. It does not show other programs' processes, and it cannot read the journal. Use the AppImage or the tarball to see those.

Nix

Wayseer's Nix flake installs the tarball, unchanged, on x86-64 Linux, from 0.27.2 on:

nix run github:wayseer-net/desktop-nix
nix run github:wayseer-net/desktop-nix -- --demo    # Wayseer's flags go after --

nix run keeps any flag before -- for itself, so nix run github:wayseer-net/desktop-nix --demo doesn't reach Wayseer.

On NixOS, add github:wayseer-net/desktop-nix to your flake's inputs, include its nixosModules.default, and set programs.wayseer.enable = true;. That installs Wayseer for every user and turns on hardware.graphics for the GPU drivers. Its README shows the whole configuration, and the overlay for your own nixpkgs.

The package starts the app through nixpkgs' own glibc loader, with nixpkgs' Wayland, X11 and Vulkan libraries. Nothing in the tarball is patched. A copy Nix installed doesn't update itself: when a release is out, run nix flake update and rebuild. Off NixOS, nixpkgs' Vulkan loader can't use your system's GPU drivers, so use another package there.

Modules

SQL, Kubernetes and every other module in this guide are built into wayseer. A module of your own runs once it is a signed package, installed with >modules.install into the state directory; nothing is installed beside wayseer (external modules).