System Bridge
[!IMPORTANT]
Any version 4 users will need to remove any integrations, and uninstall the
old application before installing v5 to avoid conflicts. Your token and
settings will not carry over to the new version.
A bridge for your systems.
[!NOTE]
Contributions welcome!
Feel free to submit a PR if you have any changes, fixes or improvements.
Features
- Supports Linux and Windows. MacOS is untested but can be compiled and tested by
- Access your system information via data modules and the API/WebSocket server.
- Control your system via the API/WebSocket server.
- Integrated with Home Assistant
- Optional Omarchy bar plugin
Installation
See installation documentation.
Optional dependencies
System Bridge reads most hardware metrics directly from the kernel, so these tools are not required. Installing them improves detection on some systems:
- Linux
lm_sensors: helps expose the full set of temperature and fan sensors on
some boards. Run sudo sensors-detect once to load the relevant modules.
- nvidia-utils (nvidia-smi): required for NVIDIA GPU metrics. Intel and
AMD GPUs use the kernel drm/hwmon interfaces and need nothing extra.
- pciutils (lspci): resolves friendly GPU model names. GPUs are still
detected without it, but fall back to a generic name.
- pipewire (pw-dump; pipewire-bin on Ubuntu, pipewire-utils on
Fedora): names the apps using the microphone or camera. Without it,
microphone usage falls back to ALSA, which names the sound server instead
of the app.
- zenity: shows the confirmation before Quit or Hide system tray.
Without it, those actions can't be confirmed, so they don't run.
Install with pacman (sudo pacman -S pciutils lm_sensors) or apt
(sudo apt install pciutils lm-sensors).
- Windows / macOS: no optional tools are needed.
Desktop controls
The system tray is enabled by default. Choose Hide system tray to hide it
after confirmation while the backend keeps running. To restore it, open the web
client's General Settings, enable System tray, save, and restart System
Bridge. The backend --no-tray flag overrides this setting.
On experimental macOS builds, hiding the icon also requires a restart.
Tray and Omarchy exit actions ask for confirmation before stopping System Bridge.
On Linux, these desktop prompts need zenity: install it with
sudo pacman -S zenity or sudo apt install zenity. Windows uses PowerShell and
macOS uses osascript, both included with the OS.
File Locations
- Linux settings/token:
~/.local/share/system-bridge/v5/ - Windows settings/token:
%LOCALAPPDATA%\system-bridge\v5\ - macOS settings/token:
~/Library/Application Support/system-bridge/v5/ - Linux logs:
~/.local/state/system-bridge/YYYY-MM-DD.log - Windows logs:
%LOCALAPPDATA%\system-bridge\logs\YYYY-MM-DD.log - macOS logs:
~/Library/Logs/system-bridge/YYYY-MM-DD.log
Development Setup
See the developing documentation for toolchain setup, build tasks, the pitchfork dev-server workflow, testing, and quality checks.
Quick start:
- Install
miseand runmise install - Run
mise run depsthenmise run build:all - Run
mise run serve:all(Linux) ormise run run(all platforms)
Packages
Connector
Allows other applications to connect to the backend. For example, in the Home Assistant integration.