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

## 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](/using/web-client/).

### Terminal

You can launch the app via the terminal:

```bash
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:

```ini title="~/.config/autostart/system-bridge.desktop"
[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](https://wiki.hypr.land/Configuring/Basics/Autostart/).

:::tip
For a service that survives logout and restarts on failure, use a user systemd service (see [User service](#user-service-recommended) below) instead.
:::

### Systemd

:::caution
Not supported with Flatpak.
You will need to configure the service
manually to the correct path.
:::

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

1. Create a user service file at `~/.config/systemd/user/system-bridge.service`:

   ```ini title="~/.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
   ```

   :::note
   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`.
   :::

2. Reload the user systemd daemon:

   ```bash
   systemctl --user daemon-reload
   ```

3. Enable and start the service:

   ```bash
   systemctl --user enable --now system-bridge
   ```

4. Check the service status:

   ```bash
   systemctl --user status system-bridge
   ```

To follow the logs:

```bash
journalctl --user -u system-bridge -f
```

:::tip
User services only run while you are logged in. To keep System Bridge running at boot and after you log out, enable lingering for your user:

```bash
sudo loginctl enable-linger $USER
```

:::

#### System service

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

1. Create a systemd service file at `/etc/systemd/system/system-bridge.service`:

   ```ini title="/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
   ```

   :::caution
   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.
   :::

2. Reload the systemd daemon:

   ```bash
   sudo systemctl daemon-reload
   ```

3. Enable and start the service:

   ```bash
   sudo systemctl enable --now system-bridge
   ```

4. Check the service status:

   ```bash
   sudo systemctl status system-bridge
   ```

### Token

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

```bash
system-bridge client token
```

:::note
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:

```bash
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.

:::note
The Start Menu shortcut may not appear immediately after installation until Windows indexes it. If you cannot find it, try searching for "System Bridge" in the Start Menu or restart Windows Explorer.
:::

Alternatively, you can start System Bridge from a terminal:

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

:::caution
Simply double-clicking `system-bridge.exe` will not start the application visibly. You must use the `backend` command or the Start Menu shortcut.
:::

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

## macOS

:::caution
macOS is not officially supported. There are no prebuilt packages, so you need to [build it from source](/install/) first.
:::

Once built, start System Bridge from a terminal:

```bash
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](#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](#file-locations)) | Absolute path to override the directory where log files are written. |

:::note
`SYSTEM_BRIDGE_CONFIG_DIR` and `SYSTEM_BRIDGE_LOG_DIR` must be absolute paths, otherwise the backend fails to start.
:::

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

```ini
[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](/features/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](/using/web-client/) to monitor and control your system.
- Use the [CLI](/using/cli/) and get your [token](/using/cli/#token).
- Connect to the [API and WebSocket](/api/) to read data and control your system.
- Integrate with [Home Assistant](/using/home-assistant/).