System Bridge

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, with a dashboard you can install from the Marketplace
• Optional Omarchy bar plugin
• An Android app, from F-Droid or each release, with notifications, quick settings tiles and sharing

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.
  • libpulse (pulseaudio-utils on Ubuntu and Fedora): pactl and paplay for audio devices, audio controls and notification sounds. Needs PulseAudio 16 or later, or PipeWire with pipewire-pulse.
  • alsa-utils (aplay): notification sounds when paplay isn't installed.
  • bluez: Bluetooth devices and controls.
  • ddcutil: brightness and power for external monitors over DDC/CI. Needs access to /dev/i2c-*, usually by being in the i2c group.
  • ffmpeg: takes pictures with webcams, when the cameras.capture setting is on.
  • gst-plugin-pipewire (gstreamer1.0-pipewire on Ubuntu, pipewire-gstreamer on Fedora): takes pictures with a webcam another app is using through PipeWire.

  Install with pacman (sudo pacman -S pciutils lm_sensors ddcutil) or apt (sudo apt install pciutils lm-sensors ddcutil).

• Windows: the waiting package update count needs winget, which Windows 11 includes. Nothing else is needed.

• 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.