Running

Start System Bridge from the desktop, the terminal or a service, find your token, and where it keeps its files.

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:
```
[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:
```
systemctl --user daemon-reload
```

Enable and start the service:

systemctl --user enable --now system-bridge

Check the service status:
```
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:

[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

Reload the systemd daemon:
```
sudo systemctl daemon-reload
```

Enable and start the service:

sudo systemctl enable --now system-bridge

Check the service status:
```
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

Configuration

Environment variables

System Bridge reads the following environment variables at startup. All are optional and fall back to the defaults below.

Variable	Default	Description
`SYSTEM_BRIDGE_PORT`	`9170`	Port for the HTTP and WebSocket API. Must be between `1` and `65535`; invalid values fall back to the default.
`SYSTEM_BRIDGE_SSDP_PORT`	`1900`	Port used for SSDP network discovery. Must be between `1` and `65535`; invalid values fall back to the default.
`SYSTEM_BRIDGE_CONFIG_DIR`	Per-OS path (see File locations)	Absolute path to override the directory holding settings, the token and stored data.
`SYSTEM_BRIDGE_LOG_DIR`	Per-OS path (see File locations)	Absolute path to override the directory where log files are written.

When running as a systemd service, set variables with Environment= lines in the unit file, for example:

[Service]
Environment="SYSTEM_BRIDGE_PORT=9171"

File locations

By default, settings, the token and logs are stored in per-user directories:

Platform	Settings / token / data	Logs
Linux	`~/.local/share/system-bridge/v5/`	`~/.local/state/system-bridge/YYYY-MM-DD.log`
Windows	`%LOCALAPPDATA%\system-bridge\v5\`	`%LOCALAPPDATA%\system-bridge\logs\YYYY-MM-DD.log`
macOS	`~/Library/Application Support/system-bridge/v5/`	`~/Library/Logs/system-bridge/YYYY-MM-DD.log`

The token is stored as a token file inside the settings directory. Override these locations with SYSTEM_BRIDGE_CONFIG_DIR and SYSTEM_BRIDGE_LOG_DIR.

Discord

System Bridge can show and change your Discord voice settings once you connect it to the Discord desktop app with your own Discord application. See Discord to set it up. Its files, discord.json and discord-token.json, are kept in the settings directory above.

Next steps

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