Help Guides
Substratal on Linux
The Linux app is a GNOME app (GTK 4 and libadwaita). It also runs on KDE Plasma and other desktops. It needs GNOME 46 or later, or any desktop that runs Flatpak. It has the same screens, names and order as every other Hub app, except the web-only Operations console.
Install
The app is in development and isn't on Flathub yet.
Flatpak: every change to the app's
mainbranch builds Flatpak bundles for x86_64 and ARM (the Flatpak workflow in substratalapps-linux). Download one from a run's artifacts, then runflatpak install --user substratal-hub-x86_64.flatpak.From source, on Ubuntu 24.04 or Fedora:
# Ubuntu: sudo apt install libgtk-4-dev libadwaita-1-dev blueprint-compiler librsvg2-common # Fedora: sudo dnf install gtk4-devel libadwaita-devel blueprint-compiler git clone https://github.com/CompositeCode/substratalapps-linux cd substratalapps-linux cargo run -p substratal-hub
Signing in and staying signed in
Sign in with your email and password, plus a code from your authenticator app if two-factor is on (see Signing in and keeping your account secure).
The app keeps you signed in through your desktop's keyring: GNOME Keyring or KWallet through the Secret Service, or the Secret portal inside Flatpak. It stores only a refresh token there, never your password. If no keyring is available, the app still works, but you sign in each time you open it.
Sign Out in the main menu (☰) ends the session on the server and removes the stored token.
Notifications
Linux desktops have no push service Substratal can use. While the app is running, it checks your inbox every minute and shows new notifications as desktop notifications, with buttons where a notification has actions. Everything is always in your Inbox. If the app is closed, you'll see new notifications the next time you open it.
The current development build doesn't raise desktop notifications yet. Check your Inbox.
Getting around
- Ctrl+K opens the command palette. Type part of a screen's name, its ID (such as
KEY-01) or its route. - F1 opens the help page for the screen you're on. So does Help on each screen.
- Alt+1 to Alt+6 jump to Home, Inbox, Organizations, Account, Plan & Billing and Settings.
- In a narrow window (under 600 px, or on a Linux phone), the sidebar becomes its own page. Use the back button to return to it.
Keyboard shortcuts on Linux lists every shortcut, and Ctrl+? shows them in the app.
Links into the app
Links such as substratal://admin/users open that screen in the running app. Only known screens open; anything else is ignored. Every screen's help page shows its route.
Themes and accessibility
Settings › Appearance offers Match system, Light or Dark, and the five light and five dark themes. When your desktop uses high contrast, the app follows it instead. The app works with the Orca screen reader and with large text.
Banners
| Banner | Meaning |
|---|---|
| You're offline | Showing what's already loaded. Changes are paused until you reconnect. |
| A newer version of Substratal is available | This app's API version is deprecated and stops working on the date shown. Update soon. |
| Update required | The API no longer accepts this app's version. Update the app to continue. |
| Connected to …, not production | The app is pointed at a test environment, such as the API's local devserver (SUBSTRATAL_API=local). |
The command-line companion
substratalctl uses the Linux app's code, so it signs in the same way, sends the same API version and gets the same errors. See substratalctl.
Screens in this guide
AUTH-01 · Sign in AUTH-02 · Two-factor challenge SET-01 · Settings — Global NTF-01 · Inbox NTF-03 · Devices & notifications GLB-01 · Command palette GLB-03 · System states