Running

Linux

Desktop

If you installed System Bridge from a Linux package (deb, rpm, Arch or Flatpak), an application menu entry called “System Bridge” is added during installation. Launch it from your desktop’s app launcher to start the backend and open the web client.

Terminal

You can launch the app via the terminal:

system-bridge backend

Autostart

To start System Bridge automatically when you log in, you have a couple of options:

Autostart desktop file: Enable autostart in the application settings, which writes ~/.config/autostart/system-bridge.desktop. You can also create this file yourself:

[Desktop Entry]
Name=System Bridge
Comment=System Bridge
Exec=system-bridge backend
Icon=system-bridge
Type=Application
Categories=Utility;
X-GNOME-Autostart-enabled=true

Compositor autostart: If your window manager or compositor handles its own startup, add system-bridge backend to its autostart configuration instead. For Hyprland, see the Hyprland autostart docs.

Systemd

User service (recommended)

Run System Bridge as a user service so it shares your login session. This gives it access to your display, audio, notifications and media, and it reads its configuration from your home directory without any extra setup.

Create a user service file at ~/.config/systemd/user/system-bridge.service:
~/.config/systemd/user/system-bridge.service
```
[Unit]
Description=System Bridge
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/system-bridge backend
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
```
Adjust ExecStart if system-bridge is installed somewhere other than /usr/bin (for example a manual install under ~/.local/bin). Check the path with which system-bridge.
Reload the user systemd daemon:
Terminal window
```
systemctl --user daemon-reload
```

Enable and start the service:

systemctl --user enable --now system-bridge

Check the service status:
Terminal window
```
systemctl --user status system-bridge
```

To follow the logs:

journalctl --user -u system-bridge -f

System service

For headless or multi-user setups, you can run System Bridge as a system-wide service managed by root.

Create a systemd service file at /etc/systemd/system/system-bridge.service:
/etc/systemd/system/system-bridge.service
```
[Unit]
Description=System Bridge
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/system-bridge backend
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
SyslogIdentifier=system-bridge
Environment="HOME=/root"

[Install]
WantedBy=multi-user.target
```
The Environment="HOME=/root" setting is required for System Bridge to locate its configuration directory. Without this, the service will fail to start with a configuration path error.
Reload the systemd daemon:
Terminal window
```
sudo systemctl daemon-reload
```

Enable and start the service:

sudo systemctl enable --now system-bridge

Check the service status:
Terminal window
```
sudo systemctl status system-bridge
```

Token

The token is essential to connect to the API/WebSocket. You can get it using the CLI command:

system-bridge client token

The token is stored per user, so run this command as the same user that runs the backend. If you run System Bridge as a system service under root, switch to that user first:

sudo su -
system-bridge client token

You can also use the short form system-bridge c t.

Alternatively, you can find your Token in the application startup logs when running the backend. The logs will show “Your API token is” followed by your token value.

Windows

After installation, System Bridge can be started from the Start Menu shortcut that gets created during installation. Look for “System Bridge” in your Start Menu.

Alternatively, you can start System Bridge from a terminal:

cd "C:\Program Files\System Bridge"
.\system-bridge.exe backend

You can enable autostart in the settings. This may require restarting the application to apply.

macOS

Once built, start System Bridge from a terminal:

system-bridge backend

Next steps

Open the web client to monitor and control your system.
Use the CLI or TUI, and get your token.
Connect to the API and WebSocket to read data and control your system.
Integrate with Home Assistant.