System

Browse files, read and change settings, set up Discord, run commands and exit the backend over the WebSocket API.

Browse the filesystem, read and update settings, run allowlisted commands, and shut down the backend.

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.

List directories

Send the GET_DIRECTORIES event to list the available base directories. It takes no data and responds with the DIRECTORIES type.

{
    "id": "abc123",
    "token": "abc123",
    "event": "GET_DIRECTORIES",
    "data": {}
}

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.

{
    "id": "abc123",
    "token": "abc123",
    "event": "GET_DIRECTORY",
    "data": {
        "base": "documents"
    }
}

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.

{
    "id": "abc123",
    "token": "abc123",
    "event": "GET_FILES",
    "data": {
        "base": "documents",
        "path": "subfolder"
    }
}

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.

{
    "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 HTTP endpoint instead.

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.

{
    "id": "abc123",
    "token": "abc123",
    "event": "VALIDATE_DIRECTORY",
    "data": {
        "path": "/home/user/Music"
    }
}

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.

{
    "id": "abc123",
    "token": "abc123",
    "event": "GET_DISK_MOUNTS",
    "data": {}
}

Settings

Read and update the backend settings over the WebSocket connection.

Get settings

Send the GET_SETTINGS event to retrieve the current settings. It takes no data and responds with the SETTINGS_RESULT type.

{
    "id": "abc123",
    "token": "abc123",
    "event": "GET_SETTINGS",
    "data": {}
}

Update settings

Send the UPDATE_SETTINGS event with the settings object to update. It responds with the SETTINGS_UPDATED type and the updated settings.

{
    "id": "abc123",
    "token": "abc123",
    "event": "UPDATE_SETTINGS",
    "data": {
        "autostart": true,
        "logLevel": "INFO"
    }
}

UPDATE_SETTINGS replaces the whole commands.allowlist, so two clients saving at once can undo each other’s commands. To change one command, use the events below.

Add, change or remove a command

Each of these changes one command in commands.allowlist and leaves the rest as they’re saved, then responds with the updated settings.

{
    "id": "abc123",
    "token": "abc123",
    "event": "COMMAND_UPDATE",
    "data": {
        "id": "9ef69bc3-62f8-4d86-952d-5f498bbddf0f",
        "name": "Say hi",
        "command": "/usr/bin/echo",
        "arguments": ["hi"],
        "workingDir": "",
        "prefab": ""
    }
}

Adding a command whose ID is already on the list, or changing one that isn’t (such as one another client removed), returns an ERROR response. Removing a command that isn’t on the list does nothing. A command is checked the same way as through UPDATE_SETTINGS.

Settings changes

Whenever the settings are saved, through any of the events above, every connected client gets a SETTINGS_CHANGED message with the id system and the new settings as its data, so it can show them without asking again.

Settings keys

Discord setup

Read and save the Discord application System Bridge signs in with. See Discord for creating the application.

Get the Discord setup

Send the GET_DISCORD_SETUP event to see how far Discord is set up. It takes no data and responds with the DISCORD_SETUP type. The client secret is never sent back.

{
    "id": "abc123",
    "token": "abc123",
    "event": "GET_DISCORD_SETUP",
    "data": {}
}

{
    "configured": true,
    "clientId": "123456789012345678",
    "redirectUri": "http://localhost",
    "running": true,
    "connected": true,
    "authenticated": false,
    "error": ""
}

Update the Discord setup

Send the UPDATE_DISCORD_SETUP event with the application’s clientId and clientSecret. System Bridge saves them to discord.json, readable only by your user, then connects to Discord straight away. Changing the application drops the saved Discord token, so Discord asks you to approve it again. It responds with the DISCORD_SETUP_UPDATED type and the setup.

{
    "id": "abc123",
    "token": "abc123",
    "event": "UPDATE_DISCORD_SETUP",
    "data": {
        "clientId": "123456789012345678",
        "clientSecret": "YOUR_CLIENT_SECRET"
    }
}

A client ID that isn’t the long number from the OAuth2 page, or a missing secret, returns an ERROR response with the BAD_REQUEST subtype.

Execute command

Run a command from the allowlist defined in your settings.

Send the COMMAND_EXECUTE event with the commandID of an allowlisted command:

{
    "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.

List command prefabs

Send the GET_COMMAND_PREFABS event to list the prefab commands and whether each can run on this system. It takes no data and responds with the COMMAND_PREFABS type. A prefab only runs once it’s added to commands.allowlist.

{
    "id": "abc123",
    "token": "abc123",
    "event": "GET_COMMAND_PREFABS",
    "data": {}
}

[
    {
        "id": "lock",
        "name": "Lock screen",
        "description": "Lock the screen",
        "available": true,
        "command": "/usr/bin/loginctl",
        "arguments": ["lock-session"],
        "reason": ""
    }
]

Exit application

Send the EXIT_APPLICATION event to shut down the backend. It takes empty data.

{
    "id": "abc123",
    "token": "abc123",
    "event": "EXIT_APPLICATION",
    "data": {}
}