This is the full developer documentation for System Bridge # System Bridge > A bridge for your systems. System Bridge is an application for your desktop that allows you to monitor and control your system. ## Features [Section titled “Features”](#features) System Information Access your system’s information via the data modules using the API/WebSocket. Open files and URLs Automate your system by opening a URL/path via the API/WebSocket. Send Notifications Send system notifications via the API/WebSocket. AI / MCP Integration Connect agents to your system with the built-in [Model Context Protocol](https://modelcontextprotocol.io) server, or feed the docs to a model with [llms.txt](/llms/). Cross-Platform Compatible with Windows and Linux. Integrated with Home Assistant Interact with your Bridges using [Home Assistant](https://www.home-assistant.io/integrations/system_bridge). See the [Home Assistant guide](/using/home-assistant/) to get started. Android Companion App Available on the [Play Store](https://play.google.com/store/apps/details?id=dev.timmo.systembridge). Source is on [GitHub](https://github.com/timmo001/system-bridge-android-companion). ## Modules [Section titled “Modules”](#modules) Battery Battery level, capacity and configuration. CPU CPU usage, clock speed, and configuration. Disks Disk and filesystem information. Display Display information. GPU Graphics card configuration and usage. Media Media player information. Memory Memory configuration and usage. Network Networking information. Processes Process information. Sensors Sensor data. System System information. ## Links / Resources [Section titled “Links / Resources”](#links--resources) Discussions Participate in discussions and get help here. [Open discussions](https://github.com/timmo001/system-bridge/discussions) Suggest a Feature / Report a Bug Thought of a feature that could be added? Found an issue? Suggest it here. [Open issues](https://github.com/timmo001/system-bridge/issues) Contribute to the Application Contribute to the project by submitting a pull request. [View repository](https://github.com/timmo001/system-bridge) Contribute to the Website / Documentation Contribute to the website by submitting a pull request. [View website repository](https://github.com/timmo001/system-bridge-website) # Overview > Guides and reference for installing, running, and integrating with System Bridge. System Bridge runs on your desktop and exposes your system over a local API and WebSocket. Use these guides to get set up and start integrating. ## Getting Started [Section titled “Getting Started”](#getting-started) [Install ](/install/)Download and install System Bridge on Windows or Linux. [Running ](/running/)Start System Bridge and keep it running. ## Using [Section titled “Using”](#using) [Desktop ](/using/desktop/)Use the system tray and desktop app launcher. [CLI ](/using/cli/)Control System Bridge from the command line. [TUI ](/using/tui/)Control System Bridge from an interactive terminal interface. [Web Client ](/using/web-client/)Monitor and control System Bridge from the browser. [Home Assistant ](/using/home-assistant/)Monitor and control your machine from Home Assistant. ## API [Section titled “API”](#api) [Overview ](/api/)Base URL, authentication and the three protocols. [HTTP ](/api/http/)Simple request/response reads over the HTTP API. [Status & Health ](/api/status/)Check whether the backend is running. [Data ](/api/data/)Request system data over the HTTP API. [Media File Data ](/api/media-file-data/)Access media file information. [MCP Server ](/api/mcp/)Connect agents over the Model Context Protocol. ## WebSocket [Section titled “WebSocket”](#websocket) [Overview ](/api/websocket/)Connection URL, message envelopes and errors. [Data ](/api/websocket/data/)Request, subscribe to and receive system data. [Input ](/api/websocket/input/)Send keyboard keypresses and text. [Control ](/api/websocket/control/)Media, notifications, opening files/URLs and power. [System ](/api/websocket/system/)Files, settings, commands and exiting the app. ## LLMs [Section titled “LLMs”](#llms) [LLMs ](/llms/)Feed the documentation to an agent using llms.txt. # API > Reference for the System Bridge HTTP, WebSocket and MCP interfaces. System Bridge exposes your system over a local API. There are three ways to interact with it: an HTTP API for simple request/response calls, a WebSocket API for live data and control, and an MCP server for agents. The [WebSocket API](/api/websocket/) is the primary interface and covers most operations: live data, input, media and power control, notifications, settings, and commands. Reach for HTTP only when you want a quick one-off read of status or a module’s current data. ## Base URL [Section titled “Base URL”](#base-url) By default the backend listens on port `9170`, so the base URL is: ```text http://{host}:9170 ``` Replace `{host}` with the hostname or IP address of the machine running System Bridge. The port can be changed with the `SYSTEM_BRIDGE_PORT` environment variable. ## Authentication [Section titled “Authentication”](#authentication) Most endpoints require your API token. Get it with the CLI: ```bash system-bridge client token ``` See the [CLI reference](/using/cli/#token) for more ways to find it. How you pass the token depends on the protocol: * **HTTP**: send the `X-API-Token` or `token` header. The media file endpoint takes a `token` query parameter instead. * **WebSocket**: include `token` in every message you send. * **MCP**: authenticated with the same token. The `GET /api` and `GET /api/health` endpoints do not require a token. ## Protocols [Section titled “Protocols”](#protocols) [WebSocket ](/api/websocket/)Live data subscriptions and system control. Covers most operations. [HTTP ](/api/status/)Request/response endpoints for status and module data. [MCP Server ](/api/mcp/)Connect agents over the Model Context Protocol. ### When to use which [Section titled “When to use which”](#when-to-use-which) | Protocol | Best for | | --------- | ------------------------------------------------------------------------------------------------------------ | | WebSocket | Most operations: live updates, control actions (media, power, notifications, input), settings, and commands. | | HTTP | Simple one-off reads: health checks and fetching a module’s current data. | | MCP | Letting agents query data and trigger actions. | # Data *Get data from data modules.* ## Authentication [Section titled “Authentication”](#authentication) This endpoint requires authentication via the `X-API-Token` header or the `token` header. ## Request [Section titled “Request”](#request) * X-API-Token header ```http GET /api/data/{module} X-API-Token: {token} ``` * token header ```http GET /api/data/{module} token: {token} ``` `{module}` is one of: `battery`, `cpu`, `disks`, `displays`, `gpus`, `media`, `memory`, `networks`, `processes`, `sensors`, `system`. ## Response [Section titled “Response”](#response) The response format varies depending on the module requested. Here’s an example: Response ```json { "boot_time": 1651433957.3015134, "fqdn": "Desktop", "hostname": "Desktop", "ip_address_4": "1.1.1.1", "mac_address": "aa:bb:cc:dd:ee:ff", "platform": "Windows", "platform_version": "10.0.22000", "uptime": 7.015625, "uuid": "abcd-efgh-abcd-efgh-abcd", "version": "5.0.2", "version_latest": "5.0.7", "version_newer_available": false } ``` # Overview > The System Bridge HTTP API for simple request/response reads, and when to use the WebSocket API instead. The HTTP API handles simple request/response reads: confirming the backend is running and fetching a module’s current data. For everything else, use the [WebSocket API](/api/websocket/), which is the primary interface and covers most operations: live data, input, media and power control, notifications, settings, and commands. Note Most endpoints need your API token. See [Authentication](/api/#authentication). ## Base URL [Section titled “Base URL”](#base-url) By default the backend listens on port `9170`, so the base URL is: ```text http://{host}:9170 ``` Replace `{host}` with the hostname or IP address of the machine running System Bridge. The port can be changed with the `SYSTEM_BRIDGE_PORT` environment variable. ## Endpoints [Section titled “Endpoints”](#endpoints) [Status & Health ](/api/status/)Confirm the backend is running. No token required. [Data ](/api/data/)Fetch a module's current data on demand. [Media File Data ](/api/media-file-data/)Download a media file by base directory and path. # MCP Server > Connect agents to System Bridge over the Model Context Protocol to query system data and trigger actions. System Bridge includes a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, letting agents and other MCP clients query your system and trigger actions. The server runs over a WebSocket at `ws://{host}:9170/api/mcp`. Replace `{host}` with the hostname or IP of the machine running System Bridge; the port can be changed with the `SYSTEM_BRIDGE_PORT` environment variable. The connection is authenticated with your API token, passed either as a `token` query parameter or an `Authorization: Bearer {token}` header. A missing or invalid token is rejected with `401 Unauthorized`. See [how to find your token](/using/cli/#token). ## Setup [Section titled “Setup”](#setup) Agents launch MCP servers as a local command and talk to them over stdio. Because System Bridge serves MCP over a WebSocket, a bridge such as [`websocat`](https://github.com/vi/websocat) is needed to pipe stdio to the WebSocket. With `websocat` installed, add System Bridge to your agent’s MCP config: mcp.json ```json { "mcpServers": { "system-bridge": { "command": "websocat", "args": ["ws://localhost:9170/api/mcp?token=YOUR_TOKEN"] } } } ``` * Replace `localhost` with the host running System Bridge if the agent is on another machine. * Replace `YOUR_TOKEN` with your API token. See [how to find your token](/using/cli/#token). Note The config key and file location vary by agent. Check your agent’s MCP documentation for where its config lives and which key it uses. Tip If you sync one config across several machines, hardcoding a token doesn’t travel well. Use a small wrapper script that reads the token from `system-bridge client token` at launch and execs `websocat`, then point `command` at it so each machine uses its own token automatically: mcp.json ```json { "mcpServers": { "system-bridge": { "command": "system-bridge-mcp" } } } ``` ## Tools [Section titled “Tools”](#tools) ### `system_bridge_get_data` [Section titled “system\_bridge\_get\_data”](#system_bridge_get_data) Get current system information from one or more data modules. The tool returns each requested module’s latest data as JSON. * `modules` (required): An array of module names to fetch. Available modules: | Module | Description | | ----------- | ----------------------------------------------------------- | | `battery` | Charge level, charging state, and time remaining. | | `cpu` | Usage, frequency, core counts, and per-core load. | | `disks` | Mounted devices, partitions, and used/free space. | | `displays` | Connected displays, resolution, and refresh rate. | | `gpus` | GPU model, load, memory, and temperature. | | `media` | Currently playing media: title, artist, and playback state. | | `memory` | Physical and virtual memory usage. | | `networks` | Network interfaces, addresses, and throughput. | | `processes` | Running processes with CPU and memory usage. | | `sensors` | Hardware sensors such as temperatures and fan speeds. | | `system` | Hostname, OS, uptime, users, and version details. | Example arguments: ```json { "modules": ["cpu", "memory", "battery"] } ``` ### `system_bridge_send_notification` [Section titled “system\_bridge\_send\_notification”](#system_bridge_send_notification) Send a desktop notification to the machine running System Bridge. * `title` (required): The notification title. * `message` (required): The notification body text. * `icon` (optional): An icon name to display with the notification. Example arguments: ```json { "title": "Build finished", "message": "All tests passed", "icon": "dialog-information" } ``` ### `system_bridge_media_control` [Section titled “system\_bridge\_media\_control”](#system_bridge_media_control) Control playback of the system’s current media session. * `action` (required): The action to perform. Must be uppercase. Available actions: | Action | Effect | | ------------- | ----------------------------- | | `PLAY` | Resume playback. | | `PAUSE` | Pause playback. | | `STOP` | Stop playback. | | `NEXT` | Skip to the next track. | | `PREVIOUS` | Return to the previous track. | | `VOLUME_UP` | Raise the volume. | | `VOLUME_DOWN` | Lower the volume. | | `MUTE` | Toggle mute. | Example arguments: ```json { "action": "PAUSE" } ``` # Media - Get File Data *Get media file from system.* ## Request [Section titled “Request”](#request) ```http GET /api/media/file/data?base={base}&path={path}&token={token} ``` Base is the base directory to search from. Path is the relative path to the file from the base. The available base directories are: * documents * downloads * home * music * pictures * videos ## Response [Section titled “Response”](#response) This will be the binary version of the file you request, so an image will return the image etc. # Status & Health These endpoints report whether the backend is running. Neither requires authentication. ## Status [Section titled “Status”](#status) ```http GET /api ``` Returns a JSON object confirming the API is running: Response ```json { "status": "success", "message": "API is running", "data": {} } ``` ## Health [Section titled “Health”](#health) ```http GET /api/health ``` Returns the health status, current time and backend version: Response ```json { "status": "healthy", "timestamp": "2025-01-01T12:00:00Z", "version": "5.0.0" } ``` # Overview > Connect to the System Bridge WebSocket API and understand the request, response, and error message formats shared across every event. The WebSocket API gives you a single persistent connection to System Bridge for live data and control. Every feature uses the same message envelope, so once you understand the format below, each event page builds on it. ## Sections [Section titled “Sections”](#sections) * [Data](/api/websocket/data/): Request system data on demand or subscribe to live updates. * [Input](/api/websocket/input/): Simulate keyboard input on the host. * [Control](/api/websocket/control/): Control media, notifications, opening paths and URLs, and power state. * [System](/api/websocket/system/): Browse files, read and update settings, run allowlisted commands, and exit the backend. ## Connecting [Section titled “Connecting”](#connecting) Connect to the WebSocket API at: ```http GET /api/websocket ``` By default this is served on port `9170`, so the full URL is usually `ws://{host}:9170/api/websocket`. ## Request format [Section titled “Request format”](#request-format) Every message you send uses the same envelope: Request ```json { "id": "abc123", "token": "abc123", "event": "EVENT_NAME", "data": {} } ``` * `id`: An identifier you choose. It is echoed back on the response so you can match requests to responses. * `token`: Your API token. See [how to find your token](/using/cli/#token). * `event`: The event to trigger (for example `GET_DATA`). * `data`: The payload for the event. Use `{}` when the event takes no data. ## Response format [Section titled “Response format”](#response-format) Responses use a different envelope to requests: Response ```json { "id": "abc123", "type": "RESPONSE_TYPE", "subtype": "NONE", "data": {}, "message": "Human-readable message", "module": "system" } ``` * `id`: The same `id` you sent on the request. * `type`: The response type (for example `DATA_UPDATE`). * `subtype`: Extra context. `NONE` on success, or an error code when `type` is `ERROR`. * `data`: The response payload. * `message`: A human-readable description. * `module`: The data module the response relates to, when applicable. ## Errors [Section titled “Errors”](#errors) When a request fails, the response `type` is `ERROR` and `subtype` describes the cause: Error response ```json { "id": "abc123", "type": "ERROR", "subtype": "BAD_TOKEN", "data": {}, "message": "Invalid token" } ``` Possible error subtypes include: * `BAD_REQUEST`, `BAD_TOKEN`, `BAD_JSON` * `BAD_DIRECTORY`, `BAD_FILE`, `BAD_PATH` * `INVALID_ACTION`, `MISSING_ACTION` * `LISTENER_ALREADY_REGISTERED`, `LISTENER_NOT_REGISTERED` * `MISSING_BASE`, `MISSING_KEY`, `MISSING_MODULES`, `MISSING_PATH`, `MISSING_PATH_URL` * `MISSING_SETTING`, `MISSING_TEXT`, `MISSING_TITLE`, `MISSING_TOKEN`, `MISSING_VALUE` * `COMMAND_NOT_FOUND`, `UNKNOWN_EVENT` # Control Control playback, send notifications, open files and URLs, and manage system power state. ## Media control [Section titled “Media control”](#media-control) Send the `MEDIA_CONTROL` event with an `action` to control media playback. Available actions: * `PLAY` * `PAUSE` * `STOP` * `NEXT` * `PREVIOUS` * `VOLUME_UP` * `VOLUME_DOWN` * `MUTE` Request ```json { "id": "abc123", "token": "abc123", "event": "MEDIA_CONTROL", "data": { "action": "PAUSE" } } ``` ## Send notification [Section titled “Send notification”](#send-notification) Send the `NOTIFICATION` event to show a desktop notification. `title` and `message` are required; the rest are optional. Request ```json { "id": "abc123", "token": "abc123", "event": "NOTIFICATION", "data": { "title": "Hello", "message": "World" } } ``` Available fields: * `title` (required): The notification title. * `message` (required): The notification body. * `icon` (optional): The icon name. * `duration` (optional): How long to show the notification, in milliseconds. * `actionUrl` (optional): A URL to open when the notification is clicked. * `actionPath` (optional): A file or folder path to open when the notification is clicked. * `sound` (optional): Path to a sound file to play with the notification. ## Open a path [Section titled “Open a path”](#open-a-path) Send the `OPEN` event with a `path` to open a file or folder with the default application. Request ```json { "id": "abc123", "token": "abc123", "event": "OPEN", "data": { "path": "C:\\users\\user\\Downloads\\example.txt" } } ``` ## Open a URL [Section titled “Open a URL”](#open-a-url) Send the `OPEN` event with a `url` to open it in the default browser. Request ```json { "id": "abc123", "token": "abc123", "event": "OPEN", "data": { "url": "https://timmo.dev" } } ``` ## Power control [Section titled “Power control”](#power-control) Control the system power state with one of the following events. Each takes empty `data`. * `POWER_HIBERNATE` * `POWER_LOCK` * `POWER_LOGOUT` * `POWER_RESTART` * `POWER_SHUTDOWN` * `POWER_SLEEP` Request ```json { "id": "abc123", "token": "abc123", "event": "POWER_SLEEP", "data": {} } ``` # Data Request system data on demand, subscribe to live updates, and handle the messages the backend sends back. ## Requesting data [Section titled “Requesting data”](#requesting-data) To request data, send a message with the `GET_DATA` event listing each module to receive data from. Request ```json { "id": "abc123", "token": "abc123", "event": "GET_DATA", "data": { "modules": ["system"] } } ``` ## Registering as a listener [Section titled “Registering as a listener”](#registering-as-a-listener) To receive data whenever it changes, send the `REGISTER_DATA_LISTENER` event with each module you want to subscribe to. Request ```json { "id": "abc123", "token": "abc123", "event": "REGISTER_DATA_LISTENER", "data": { "modules": ["cpu", "memory", "system"] } } ``` The backend replies with a `DATA_LISTENER_REGISTERED` response, then sends a [`DATA_UPDATE`](#receiving-data) message whenever a subscribed module changes. To stop receiving updates, send the `UNREGISTER_DATA_LISTENER` event. It takes no data and responds with the `DATA_LISTENER_UNREGISTERED` type. Request ```json { "id": "abc123", "token": "abc123", "event": "UNREGISTER_DATA_LISTENER", "data": {} } ``` ## Receiving data [Section titled “Receiving data”](#receiving-data) After a `GET_DATA` request or while registered as a listener, you receive messages with the `DATA_UPDATE` type. This will look something like this: Response ```json { "id": "abc123", "type": "DATA_UPDATE", "subtype": "NONE", "data": { "boot_time": 1651433957.3015134, "fqdn": "Desktop", "hostname": "Desktop", "ip_address_4": "1.1.1.1", "mac_address": "aa:bb:cc:dd:ee:ff", "platform": "Windows", "platform_version": "10.0.22000", "uptime": 7.015625, "uuid": "abcd-efgh-abcd-efgh-abcd", "version": "5.0.2", "version_latest": "5.0.7", "version_newer_available": false }, "message": "Data received", "module": "system" } ``` # Input Simulate keyboard input on the host machine. ## Keyboard keypress [Section titled “Keyboard keypress”](#keyboard-keypress) Send the `KEYBOARD_KEYPRESS` event with a `key` to press a single key. Request ```json { "id": "abc123", "token": "abc123", "event": "KEYBOARD_KEYPRESS", "data": { "key": "a" } } ``` ## Keyboard text [Section titled “Keyboard text”](#keyboard-text) Send the `KEYBOARD_TEXT` event with a `text` string to type text. Request ```json { "id": "abc123", "token": "abc123", "event": "KEYBOARD_TEXT", "data": { "text": "hello" } } ``` # System Browse the filesystem, read and update settings, run allowlisted commands, and shut down the backend. ## Files & directories [Section titled “Files & directories”](#files--directories) These events let you browse the base directories System Bridge exposes, list and inspect files within them, and validate paths. The available base directory keys are `documents`, `downloads`, `home`, `music`, `pictures` and `videos`, plus any custom directories configured in `media.directories` in your [settings](#settings). ### List directories [Section titled “List directories”](#list-directories) Send the `GET_DIRECTORIES` event to list the available base directories. It takes no data and responds with the `DIRECTORIES` type. Request ```json { "id": "abc123", "token": "abc123", "event": "GET_DIRECTORIES", "data": {} } ``` ### Get a directory [Section titled “Get a directory”](#get-a-directory) Send the `GET_DIRECTORY` event with the base directory key to look up a single directory. It responds with the `DIRECTORY` type. Request ```json { "id": "abc123", "token": "abc123", "event": "GET_DIRECTORY", "data": { "base": "documents" } } ``` ### List files [Section titled “List files”](#list-files) Send the `GET_FILES` event with a base directory, and optionally a relative `path` within it, to list files. It responds with the `FILES` type. Request ```json { "id": "abc123", "token": "abc123", "event": "GET_FILES", "data": { "base": "documents", "path": "subfolder" } } ``` ### Get a file [Section titled “Get a file”](#get-a-file) Send the `GET_FILE` event with the absolute `path` to a file to get its information. It responds with the `FILE` type. Request ```json { "id": "abc123", "token": "abc123", "event": "GET_FILE", "data": { "path": "/home/user/Documents/example.txt" } } ``` To read the contents of a media file, use the [Media File Data](/api/media-file-data/) HTTP endpoint instead. ### Validate a directory [Section titled “Validate a directory”](#validate-a-directory) Send the `VALIDATE_DIRECTORY` event with a `path` to check whether it exists and is a directory. It responds with the `DIRECTORY_VALIDATED` type and a `data.valid` boolean. Request ```json { "id": "abc123", "token": "abc123", "event": "VALIDATE_DIRECTORY", "data": { "path": "/home/user/Music" } } ``` ### Get disk mounts [Section titled “Get disk mounts”](#get-disk-mounts) Send the `GET_DISK_MOUNTS` event to list mounted disks, categorised into primary and secondary (bind and squashfs) mounts. It takes no data and responds with the `DISK_MOUNTS` type. Request ```json { "id": "abc123", "token": "abc123", "event": "GET_DISK_MOUNTS", "data": {} } ``` ## Settings [Section titled “Settings”](#settings) Read and update the backend settings over the WebSocket connection. ### Get settings [Section titled “Get settings”](#get-settings) Send the `GET_SETTINGS` event to retrieve the current settings. It takes no data and responds with the `SETTINGS_RESULT` type. Request ```json { "id": "abc123", "token": "abc123", "event": "GET_SETTINGS", "data": {} } ``` ### Update settings [Section titled “Update settings”](#update-settings) Send the `UPDATE_SETTINGS` event with the settings object to update. It responds with the `SETTINGS_UPDATED` type and the updated settings. Request ```json { "id": "abc123", "token": "abc123", "event": "UPDATE_SETTINGS", "data": { "autostart": true, "logLevel": "INFO" } } ``` ### Settings keys [Section titled “Settings keys”](#settings-keys) | Key | Type | Description | | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | | `autostart` | boolean | Start the backend automatically when you log in. | | `logLevel` | string | One of `DEBUG`, `INFO`, `WARN`, `ERROR`. Defaults to `WARN`. | | `hotkeys` | array | List of `{ name, key }` hotkey bindings. | | `commands.allowlist` | array | Commands that can be run via [Execute Command](#execute-command). Each entry is `{ id, name, command, workingDir, arguments }`. | | `disks.allowedSecondaryMountPoints` | array | Secondary mount points to include in disk data. | | `media.directories` | array | Custom media directories as `{ name, path }`, exposed as [base directories](#files--directories). | Note Changing `autostart` or `logLevel` is applied immediately by the backend. ## Execute command [Section titled “Execute command”](#execute-command) Run a command from the allowlist defined in your [settings](#settings). Send the `COMMAND_EXECUTE` event with the `commandID` of an allowlisted command: Request ```json { "id": "abc123", "token": "abc123", "event": "COMMAND_EXECUTE", "data": { "commandID": "my-command" } } ``` The command runs asynchronously. You receive a `COMMAND_EXECUTING` response immediately, followed by a `COMMAND_COMPLETED` response once it finishes. Caution Only commands present in `commands.allowlist` can be executed. Requesting an unknown command returns an `ERROR` response with the `COMMAND_NOT_FOUND` subtype. ## Exit application [Section titled “Exit application”](#exit-application) Send the `EXIT_APPLICATION` event to shut down the backend. It takes empty `data`. Request ```json { "id": "abc123", "token": "abc123", "event": "EXIT_APPLICATION", "data": {} } ``` # Download & Install 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--1-x86_64.pkg.tar.zst` * Debian / Ubuntu: `system-bridge__.deb` * Fedora / RHEL: `system-bridge-..rpm` * Flatpak: `system-bridge-.flatpak` * Windows: `system-bridge--setup.exe` 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. * 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--1-x86_64.pkg.tar.zst ``` * Debian / Ubuntu Install the `.deb` asset with `apt` so dependencies are resolved automatically: ```bash sudo apt install ./system-bridge__.deb ``` You can also install it with `dpkg`: ```bash sudo dpkg -i system-bridge__.deb ``` * Fedora / RHEL Install the `.rpm` asset with `dnf`: ```bash sudo dnf install ./system-bridge-..rpm ``` * Flatpak Install the `.flatpak` bundle: ```bash flatpak install system-bridge-.flatpak ``` Then run it with: ```bash flatpak run dev.timmo.system-bridge ``` * Windows 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--1-x86_64.pkg.tar.zst ``` * macOS Install the `.deb` asset with `apt` so dependencies are resolved automatically: ```bash sudo apt install ./system-bridge__.deb ``` You can also install it with `dpkg`: ```bash sudo dpkg -i system-bridge__.deb ``` * Arch Linux Install the `.rpm` asset with `dnf`: ```bash sudo dnf install ./system-bridge-..rpm ``` * Debian / Ubuntu Install the `.flatpak` bundle: ```bash flatpak install system-bridge-.flatpak ``` Then run it with: ```bash flatpak run dev.timmo.system-bridge ``` * Fedora / RHEL Run the `system-bridge--setup.exe` installer to install the application. After installation completes, you can start System Bridge from the Start Menu shortcut. * Flatpak macOS is not officially supported and has no prebuilt packages. You can still build it from source and test it for yourself. 1. Clone the [repository](https://github.com/timmo001/system-bridge). 2. Run `make build`. See the project’s [README](https://github.com/timmo001/system-bridge#readme) for the development setup and toolchain requirements. 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. ## Next steps [Section titled “Next steps”](#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 [TUI](/using/tui/), and get your [token](/using/cli/#token). * Connect it to [Home Assistant](/using/home-assistant/). # LLMs > Feed the System Bridge documentation to an agent using llms.txt. The System Bridge documentation is published in formats that an agent can read directly, following the [llms.txt](https://llmstxt.org) convention. Point an agent at one of these files to give it the docs as context. ## Available files [Section titled “Available files”](#available-files) * [`/llms.txt`](https://system-bridge.timmo.dev/llms.txt) - an index of the documentation with links to each section. Use this when you want the agent to pick what it needs. * [`/llms-full.txt`](https://system-bridge.timmo.dev/llms-full.txt) - the entire documentation in a single file. Use this for the most complete context. * [`/llms-small.txt`](https://system-bridge.timmo.dev/llms-small.txt) - a trimmed version for smaller context windows. These files are generated from the docs at build time, so they stay in sync with the rest of the site. ## How to use them [Section titled “How to use them”](#how-to-use-them) * Paste one of the URLs above into an agent and ask it to read the page. * Use the actions in the page header on any docs page to copy the page as Markdown, then paste it straight into an agent. This gives the agent the content directly, so it does not need to fetch the page over the web. ## Relationship to MCP [Section titled “Relationship to MCP”](#relationship-to-mcp) `llms.txt` gives an agent the documentation. The [MCP server](/api/mcp/) goes further and lets an agent read live system data and control your machine over the [Model Context Protocol](https://modelcontextprotocol.io). Use `llms.txt` to help an agent understand System Bridge, and the MCP server to let it act on your system. # Running ## Linux [Section titled “Linux”](#linux) ### Desktop [Section titled “Desktop”](#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 [Section titled “Terminal”](#terminal) You can launch the app via the terminal: ```bash system-bridge backend ``` ### Autostart [Section titled “Autostart”](#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: \~/.config/autostart/system-bridge.desktop ```ini [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 [Section titled “Systemd”](#systemd) Caution Not supported with Flatpak. You will need to configure the service manually to the correct path. #### User service (recommended) [Section titled “User service (recommended)”](#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`: \~/.config/systemd/user/system-bridge.service ```ini [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 [Section titled “System service”](#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`: /etc/systemd/system/system-bridge.service ```ini [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 [Section titled “Token”](#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 [Section titled “Windows”](#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 [Section titled “macOS”](#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 ``` ## Next steps [Section titled “Next steps”](#next-steps) * Open the [web client](/using/web-client/) to monitor and control your system. * Use the [CLI](/using/cli/) or [TUI](/using/tui/), 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/). # CLI The System Bridge CLI provides commands to interact with the System Bridge backend. Most commands live under the `system-bridge client` subcommand, while `backend`, `tui` and `version` are top-level commands. ## Token [Section titled “Token”](#token) The token is essential to connect to the API/WebSocket. To get it, run the following 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. ## Notification [Section titled “Notification”](#notification) To send a notification, use the following command: ```bash system-bridge client notification --title "Title" --message "Message" --icon "icon-name" ``` Available flags: * `--title`: The title of the notification (default: “System Bridge”) * `--message`: The message of the notification (default: “Hello, world!”) * `--icon`: The icon of the notification (default: “system-bridge”) * `--sound`: Path to a sound file to play with the notification (Linux only) * `--action-url`: URL to open when the notification is clicked (Linux only) * `--action-path`: File/folder path to open when the notification is clicked (Linux only) ## Discovery [Section titled “Discovery”](#discovery) ### List Services [Section titled “List Services”](#list-services) To list discovered services on the network, run: ```bash system-bridge client discovery list ``` This will scan for available System Bridge instances and display them with their hostname, IP, port, and type. ## Data [Section titled “Data”](#data) ### List Modules [Section titled “List Modules”](#list-modules) To list all available data modules, run: ```bash system-bridge client data list ``` By default, this outputs as a simple list. You can also use: ```bash system-bridge client data list --json ``` To output as a JSON array. Available flags: * `--json`: Output as a JSON array * `--table`: Output as a table (default) ### Run Modules [Section titled “Run Modules”](#run-modules) To run a specific data module and get its data as JSON, use: ```bash system-bridge client data run --module cpu ``` For example, to get CPU data: ```bash system-bridge client data run --module cpu ``` To run all modules and get a JSON object with all data: ```bash system-bridge client data run --all ``` To pretty-print the JSON output: ```bash system-bridge client data run --module cpu --pretty ``` Available flags: * `--module` or `-m`: Module name (e.g., cpu, memory) * `--all`: Run all modules * `--pretty`: Pretty-print JSON output ## Backend [Section titled “Backend”](#backend) To run the backend server, use: ```bash system-bridge backend ``` Add `--open-web-client` to open the [web client](/using/web-client/) once the backend has started: ```bash system-bridge backend --open-web-client ``` See [Running](/running/) for autostart and service setup. ## Version [Section titled “Version”](#version) To get the version of System Bridge, run: ```bash system-bridge version ``` ## Next steps [Section titled “Next steps”](#next-steps) * Prefer a graphical interface? Use the [web client](/using/web-client/). * Prefer an interactive menu? Use the [TUI](/using/tui/). * Connect to the [API and WebSocket](/api/) to read data and control your system. * Integrate with [Home Assistant](/using/home-assistant/). * Not started the backend yet? See [Running](/running/). # Desktop > Use System Bridge from your desktop, including the system tray and app launcher. When System Bridge runs on your desktop, it adds an application menu entry and a system tray icon so you can launch and control it without the terminal. ## Launching [Section titled “Launching”](#launching) Installing System Bridge adds a **System Bridge** entry to your desktop app launcher: the Start Menu on Windows, or your application menu on Linux. Launch it to start the backend and open the [web client](/using/web-client/). For terminal launch, services, and autostart, see [Running](/running/). ## System tray [Section titled “System tray”](#system-tray) While the backend is running, a System Bridge icon appears in your system tray. Its menu has the following options: * **Open web client**: open the [web client](/using/web-client/) in your default browser. * **Launch TUI**: open the interactive [TUI](/using/tui/) in a terminal window. * **Open logs directory**: open the folder containing the application logs. * **Quit**: stop the backend and exit System Bridge. ## Next steps [Section titled “Next steps”](#next-steps) * Monitor and control your system from the [web client](/using/web-client/). * Prefer the terminal? Use the [TUI](/using/tui/) or [CLI](/using/cli/). # Home Assistant > Monitor and control System Bridge from Home Assistant. System Bridge integrates with [Home Assistant](https://www.home-assistant.io/integrations/system_bridge), so you can monitor and control your machine from your Home Assistant instance. The integration uses a local push connection and is maintained by the System Bridge author. Tip The official [System Bridge integration documentation](https://www.home-assistant.io/integrations/system_bridge) is the most up-to-date reference for entities, actions, and setup. Use this page as a starting point and follow the official docs for the current details. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A running System Bridge backend. See [Running](/running/). * Your API token. See [how to find your token](/running/#token). ## Adding the integration [Section titled “Adding the integration”](#adding-the-integration) System Bridge can be auto-discovered by Home Assistant. When an instance is found, it appears under **Settings > Devices & services** as a discovered device, ready to set up. To add it manually: 1. In Home Assistant, go to **Settings > Devices & services**. 2. Select **Add Integration** and choose **System Bridge**. 3. Enter the host and your token when prompted, then follow the on-screen steps. ## Features [Section titled “Features”](#features) The integration exposes your system as sensors, a media player, and a set of actions, plus notifications and update tracking. ### Sensors [Section titled “Sensors”](#sensors) Sensors report system information such as battery, CPU speed, memory, load, displays, filesystems, GPU usage, processes, and version details. Many are enabled by default, with additional CPU and GPU sensors (temperatures, clock speeds, fan speed, and more) available to enable manually. ### Binary sensors [Section titled “Binary sensors”](#binary-sensors) Binary sensors report on/off states such as whether the battery is charging, the camera is in use, a reboot is pending, or a new version is available. ### Media player [Section titled “Media player”](#media-player) Control currently playing media on your device from Home Assistant. Media player support is currently limited to devices running System Bridge on Windows. ### Media source [Section titled “Media source”](#media-source) Browse and play media from your system through the Home Assistant media browser and supported media players. ### Update [Section titled “Update”](#update) An update entity notifies you when a new version of System Bridge is available. ### Notifications [Section titled “Notifications”](#notifications) Send rich notifications to your device, including a title, message, image, action buttons, and audio. ### Actions [Section titled “Actions”](#actions) Trigger actions on the machine running System Bridge: * Get a process by its ID, or get processes by name. * Open a path or a URL with the default application. * Send a keypress or type text. * Send a power command such as `sleep`, `lock`, `restart`, or `shutdown`. ## Next steps [Section titled “Next steps”](#next-steps) * Read the official [integration documentation](https://www.home-assistant.io/integrations/system_bridge) for entity names, action parameters, and examples. * Connect to System Bridge directly with the [API and WebSocket](/api/). # TUI > Control System Bridge from an interactive terminal interface. The TUI is an interactive terminal interface for System Bridge. It wraps the [CLI](/using/cli/) commands in a searchable, keyboard-driven menu. Note The TUI needs an interactive terminal, so everything on this page assumes you are running it in one. Running `system-bridge` on its own launches the TUI when the terminal is interactive. In a non-interactive context, such as a script or when input is piped, the bare command prints help instead. ## Launching the TUI [Section titled “Launching the TUI”](#launching-the-tui) ```bash system-bridge tui ``` You can also use the short alias: ```bash system-bridge t ``` ## Navigating [Section titled “Navigating”](#navigating) * Use the arrow keys to move through the menu and `Enter` to select an item. * Start typing to fuzzy-search the menu by title, description, or keyword. * Vim-style commands work too, such as `:q` to quit. ## Menu [Section titled “Menu”](#menu) ### Backend [Section titled “Backend”](#backend) Start the backend server. A variant lets you start the backend and open the [web client](/using/web-client/) in your browser at the same time. ### Client [Section titled “Client”](#client) Run client commands: * **Token**: print your API token. * **Notification**: send a notification using a form for the title, message, and icon. Advanced fields cover the sound, action URL, and action path. * **Discovery**: list System Bridge services discovered on your network. * **Data**: list the available data modules, or run a module and print its output. Running a module lets you pick the module and pretty-print the JSON. ### Version [Section titled “Version”](#version) Show the application version. ### Quit [Section titled “Quit”](#quit) Exit the TUI. ## Next steps [Section titled “Next steps”](#next-steps) * See the [CLI](/using/cli/) for the underlying commands and flags. * Prefer a browser? Use the [web client](/using/web-client/). # Web Client > Monitor and control System Bridge from the built-in browser interface. The web client is the built-in browser interface served by the System Bridge backend. Use it to view live system data, change settings, and trigger actions without writing any code. ## Opening the web client [Section titled “Opening the web client”](#opening-the-web-client) ### Desktop [Section titled “Desktop”](#desktop) When you launch System Bridge from your desktop app launcher, the web client opens automatically. While System Bridge is running, you can also open the web client from the system tray. See the [Desktop](/using/desktop/) page for the system tray and desktop app. ### Terminal [Section titled “Terminal”](#terminal) Start the backend and open the web client in your browser with: ```bash system-bridge backend --open-web-client ``` By default the backend serves the web client on port `9170`. When opened for you, it loads `http://127.0.0.1:9170`. See the [CLI](/using/cli/#backend) for more on the `backend` command. ## Connecting [Section titled “Connecting”](#connecting) The web client connects to the backend over the WebSocket API. On the connection screen, set: * **Host**: the hostname or IP address of the machine running System Bridge (pre-filled with `0.0.0.0`). * **Port**: the backend port (default `9170`). * **Use SSL**: enable if the backend is served over HTTPS. * **API Token**: your System Bridge token. You need your token to connect. See [how to find your token](/running/#token). Tip When the backend opens the web client for you, the host, port, and token are filled in automatically. ## What you can do [Section titled “What you can do”](#what-you-can-do) ### Data [Section titled “Data”](#data) View real-time data from every [data module](/api/websocket/data/), including CPU, memory, disks, displays, GPUs, media, networks, processes, sensors, and system information. ### Settings [Section titled “Settings”](#settings) Configure the backend without editing files: * **General**: core application settings. * **Media Directories**: folders exposed to the media source. * **Commands**: allowlisted commands the backend can run. * **Disks**: disk and filesystem options. ### Actions [Section titled “Actions”](#actions) Trigger actions on the machine running System Bridge: * **Notifications**: send a system notification. * **Open**: open a path or URL with the default application. * **Media Controls**: control currently playing media. ## Next steps [Section titled “Next steps”](#next-steps) * Connect programmatically with the [API and WebSocket](/api/). * Prefer the terminal? Use the [TUI](/using/tui/) or [CLI](/using/cli/).