system-bridge

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 the community.
• 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.
  • playerctl: reads what's playing and controls it. Without it, the Media module is empty and media controls do nothing.
  • 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:

1. Install mise and run mise install
2. Run mise run deps then mise run build:all
3. Run mise run serve:all (Linux) or mise run run (all platforms)

Packages

Connector

Allows other applications to connect to the backend. For example, in the Home Assistant integration.