---
title: Download and install
description: Install System Bridge on Linux or Windows from the AUR, a package, the installer, mise, aqua or an archive.
---

Download the package for your platform from the [releases page](https://github.com/timmo001/system-bridge/releases).

Each release ships these assets:

- Arch Linux: `system-bridge-*-x86_64.pkg.tar.zst` (stable releases only)
- Debian / Ubuntu: `system-bridge_<version>_<arch>.deb`
- Fedora / RHEL: `system-bridge-<version>.<arch>.rpm`
- Flatpak: `system-bridge-<version>.flatpak`
- Linux archive: `system-bridge-<version>-linux-x86_64.tar.gz`
- Windows: `system-bridge-<version>-setup.exe`
- Windows archive: `system-bridge-<version>-windows-x86_64.zip`

The archives hold just the executable, for [mise](https://mise.jdx.dev) and manual installs. Prefer a package where there is one, as the archives don't set up a service, shortcuts or dependencies.

:::note
Stable builds are attached to the releases page. Development builds from the latest `dev` branch are also available as workflow artifacts on the [GitHub Actions runs](https://github.com/timmo001/system-bridge/actions), which require a GitHub account to download.
:::

**Linux**

Install the package that matches your distribution's package manager, or use mise or the archive on any distribution.

**Arch Linux**

Install from the AUR with an AUR helper such as [yay](https://github.com/Jguer/yay).

For the latest stable release, use the [system-bridge](https://aur.archlinux.org/packages/system-bridge) package:

```bash
yay -S system-bridge
```

For the development branch, use the [system-bridge-git](https://aur.archlinux.org/packages/system-bridge-git) package. This builds and installs the application from the latest `dev` branch, which is updated automatically every commit:

```bash
yay -S system-bridge-git
```

Alternatively, install the `.pkg.tar.zst` from the releases page or downloaded workflow asset directly:

```bash
sudo pacman -U system-bridge-*-x86_64.pkg.tar.zst
```

**Debian / Ubuntu**

Install the `.deb` asset with `apt` so dependencies are resolved automatically:

```bash
sudo apt install ./system-bridge_<version>_<arch>.deb
```

You can also install it with `dpkg`:

```bash
sudo dpkg -i system-bridge_<version>_<arch>.deb
```

**Fedora / RHEL**

Install the `.rpm` asset with `dnf`:

```bash
sudo dnf install ./system-bridge-<version>.<arch>.rpm
```

**Flatpak**

Install the `.flatpak` bundle:

```bash
flatpak install system-bridge-<version>.flatpak
```

Then run it with:

```bash
flatpak run dev.timmo.system-bridge
```

**NixOS**

The repository is a Nix flake that builds System Bridge from source on x86_64 Linux, from the latest `dev` branch. Run it without installing:

```bash
nix run github:timmo001/system-bridge -- backend --open-web-client
```

Or add it to your NixOS configuration as a flake input:

```nix
{
  inputs.system-bridge.url = "github:timmo001/system-bridge";

  outputs = { nixpkgs, system-bridge, ... }: {
    nixosConfigurations.<host> = nixpkgs.lib.nixosSystem {
      modules = [
        {
          environment.systemPackages = [
            system-bridge.packages.x86_64-linux.default
          ];
        }
      ];
    };
  };
}
```

`system-bridge-full` is the same package with most of the [optional dependencies](#optional-dependencies) added to its `PATH`: `lm_sensors`, `pciutils`, `pipewire`, `pulseaudio` (for `pactl` and `paplay`, which work with PipeWire's `pipewire-pulse` too), `alsa-utils`, `zenity` and `ddcutil`. Use `system-bridge.packages.x86_64-linux.system-bridge-full` instead of `default` to get them, or add whichever you want to `environment.systemPackages` with the plain package.

The rest come from NixOS options, with either package:

- `nvidia-smi` comes with the NVIDIA driver, from `hardware.nvidia` and `services.xserver.videoDrivers = [ "nvidia" ]`, so it always matches the driver that's running.
- Bluetooth devices need `hardware.bluetooth.enable = true`.
- `ddcutil` needs `hardware.i2c.enable = true`, with your user in the `i2c` group.

If you run System Bridge from `systemd.user.services` in your configuration, NixOS gives the service a minimal `PATH`, so it won't find tools from `environment.systemPackages`. Use `system-bridge-full`, or list the tools in the service's `path`.

**mise**

[mise](https://mise.jdx.dev) installs the Linux archive from the latest release, through the [aqua registry](https://github.com/aquaproj/aqua-registry):

```bash
mise use -g aqua:timmo001/system-bridge
```

Pin a version with `aqua:timmo001/system-bridge@<version>`; the archives start at 5.20.0. mise checks the download against the release's [GitHub attestation](https://docs.github.com/actions/security-for-github-actions/using-artifact-attestations). [aqua](https://aquaproj.github.io) itself works too, with `aqua g -i timmo001/system-bridge` and then `aqua i`.

The executable needs `libx11`, `libxtst`, `libxkbcommon` and `libxkbcommon-x11` (`libx11-6`, `libxtst6`, `libxkbcommon0` and `libxkbcommon-x11-0` on Debian / Ubuntu), even without a desktop. Nothing starts it for you: run `system-bridge backend`, or add your own service or autostart entry. See [Running](/running).

**Archive**

Download the archive with the [GitHub CLI](https://cli.github.com) and put `system-bridge` somewhere on your `PATH`:

```bash
gh release download -R timmo001/system-bridge -p '*-linux-x86_64.tar.gz'
tar -xzf system-bridge-*-linux-x86_64.tar.gz -C ~/.local/bin system-bridge
```

Check the download first with `gh attestation verify system-bridge-*-linux-x86_64.tar.gz -R timmo001/system-bridge`.

The executable needs the same libraries as with mise, and nothing starts it for you. See [Running](/running).

**Windows**

**Installer**

Run the `system-bridge-<version>-setup.exe` installer to install the application. After installation completes, you can start System Bridge from the Start Menu shortcut.

**mise**

[mise](https://mise.jdx.dev) installs the Windows archive from the latest release, through the [aqua registry](https://github.com/aquaproj/aqua-registry):

```powershell
mise use -g aqua:timmo001/system-bridge
```

Pin a version with `aqua:timmo001/system-bridge@<version>`; the archives start at 5.20.0. aqua itself works too, with `aqua g -i timmo001/system-bridge` and then `aqua i`. mise checks the download against the release's [GitHub attestation](https://docs.github.com/actions/security-for-github-actions/using-artifact-attestations). Nothing starts it for you: run `system-bridge backend`. See [Running](/running).

**Archive**

Download the archive with the [GitHub CLI](https://cli.github.com):

```powershell
gh release download -R timmo001/system-bridge -p '*-windows-x86_64.zip'
Expand-Archive system-bridge-*-windows-x86_64.zip "$env:LOCALAPPDATA\Programs\system-bridge"
```

Add that folder to your `PATH`, and keep the `now-playing` folder beside `system-bridge.exe`, as the [media](/api/data/#media) module needs it. Nothing starts it for you: run `system-bridge backend`. See [Running](/running).

### Code signing policy

Free code signing provided by [SignPath.io](https://about.signpath.io), certificate by [SignPath Foundation](https://signpath.org).

The Windows executable and installer are built from this repository on GitHub Actions and signed through SignPath, so Windows shows SignPath Foundation as the publisher. The NowPlaying helper bundled with them comes from [dotnet-now-playing](https://github.com/timmo001/dotnet-now-playing) and isn't signed.

- Committers and reviewers: [Aidan Timson (timmo001)](https://github.com/timmo001)
- Approvers: [Aidan Timson (timmo001)](https://github.com/timmo001)

Pull requests from anyone else are reviewed by a committer before they're merged, and every release is approved by hand before it's signed.

System Bridge doesn't send any information to other networked systems unless you ask it to, apart from what's listed on [Privacy and security](/privacy).

**macOS**

macOS is not officially supported and has no prebuilt packages. You can still build it from source and test it for yourself.

See [Developing](/developing) for the full build, run, and test workflow from source.

:::note
Please do not submit feedback or bug reports for macOS, as it is not supported. Contributions are welcome if you would like to help improve macOS support.
:::

## Updating

On Linux, System Bridge restarts itself within a minute of a package update replacing it, so the new version runs without you restarting it. Flatpak keeps running the version it started with, so restart System Bridge after updating it there.

The same goes for replacing the Linux executable from an archive by hand. mise installs each version to its own folder instead, so restart System Bridge after `mise upgrade`, and after updating from the Windows archive.

## Optional dependencies

System Bridge reads most hardware metrics directly from the kernel, so these tools aren't required. On Linux, installing them improves detection on some systems:

| Package | Tool | What it adds |
| --- | --- | --- |
| `lm_sensors` (Arch, Fedora), `lm-sensors` (Debian / Ubuntu) | `sensors` | 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` | NVIDIA GPU metrics. Intel and AMD GPUs use the kernel `drm`/`hwmon` interfaces and need nothing extra. |
| `pciutils` | `lspci` | Friendly GPU model names. GPUs are still detected without it, but fall back to a generic name. |
| `pipewire` (Arch), `pipewire-bin` (Debian / Ubuntu), `pipewire-utils` (Fedora) | `pw-dump` | 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` | `zenity` | The confirmation before **Quit** or **Hide system tray**. Without it, those actions can't be confirmed, so they don't run. |
| `libpulse` (Arch), `pulseaudio-utils` (Debian / Ubuntu, Fedora) | `pactl`, `paplay` | Audio devices and [audio controls](/features/remote-control/#audio), and notification sounds. Needs PulseAudio 16 or later, or PipeWire with `pipewire-pulse`. |
| `alsa-utils` | `aplay` | Notification sounds when `paplay` isn't installed. |
| `bluez` | `bluetoothd` | Bluetooth devices and [Bluetooth controls](/features/remote-control/#bluetooth). |
| `ddcutil` | `ddcutil` | Brightness and power for [external monitors](/features/remote-control/#displays) over DDC/CI. Needs access to `/dev/i2c-*`, usually by being in the `i2c` group. |

The `.deb` and `.rpm` packages recommend `pciutils`, PipeWire, `zenity` and `pulseaudio-utils`, so `apt` and `dnf` install them by default. The Arch package lists all of these as optional dependencies, which `pacman` shows but doesn't install.

The [command prefabs](/features/commands/#prefab-commands) run tools for the desktop you're on, such as `grim` for screenshots. A prefab that can't run says which tools it looks for. [Reading and setting the clipboard](/features/remote-control/#clipboard) needs `wl-clipboard`, or `xclip` or `xsel` on X11.

On Windows, the waiting package update count needs [winget](https://learn.microsoft.com/windows/package-manager/winget/), which Windows 11 includes. Nothing else is needed.

## Power readings on Linux

CPU power, integrated Intel GPU power and, on laptops, system power come from the kernel's RAPL energy counters. Since [CVE-2020-8694](https://nvd.nist.gov/vuln/detail/CVE-2020-8694) the kernel lets only root read them, so the Arch, `.deb` and `.rpm` packages install a udev rule, `60-system-bridge-rapl.rules`, that makes them readable by every local user.

:::warning
Readable counters let local programs measure power use, which CVE-2020-8694 showed can leak data from the CPU, mostly from SGX enclaves. If that matters on your system, delete or override the rule with an empty `/etc/udev/rules.d/60-system-bridge-rapl.rules`. Those readings then stay empty; on battery, system power still comes from the battery.
:::

mise, the archive and Flatpak can't install the rule. Add it yourself, then apply it without a reboot:

```ini title="/etc/udev/rules.d/60-system-bridge-rapl.rules"
SUBSYSTEM=="powercap", KERNEL=="intel-rapl:*|intel-rapl-mmio:*", ACTION=="add|change", RUN+="/bin/chmod a+r /sys%p/energy_uj"
```

```bash
sudo udevadm control --reload
sudo udevadm trigger --subsystem-match=powercap --action=change
```

On NixOS, add the package to `services.udev.packages` as well.

## Next steps

- Start System Bridge: see [Running](/running).
- Monitor and control your system from the [web client](/using/web-client).
- Explore the [CLI](/using/cli) and get your [token](/using/cli#token).
- Connect it to [Home Assistant](/using/home-assistant).