From fb3a86ead42f109fbd2eef8024ff30d54b1bdfc4 Mon Sep 17 00:00:00 2001 From: LinuxServer-CI Date: Thu, 6 Nov 2025 13:39:59 +0000 Subject: [PATCH] Bot Updating Documentation --- docs/images/docker-baseimage-selkies.md | 39 +++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/images/docker-baseimage-selkies.md b/docs/images/docker-baseimage-selkies.md index eead3ef882..8abdd32c87 100644 --- a/docs/images/docker-baseimage-selkies.md +++ b/docs/images/docker-baseimage-selkies.md @@ -179,6 +179,8 @@ The server can be forced to use a single, fixed resolution for all connecting cl | `SELKIES_USE_BROWSER_CURSORS` | `False` | Use browser CSS cursors instead of rendering to canvas. | | `SELKIES_USE_CSS_SCALING` | `False` | HiDPI when false, if true a lower resolution is sent from the client and the canvas is stretched. | | `SELKIES_PORT` (or `CUSTOM_WS_PORT`) | `8082` | Port for the data websocket server. | +| `SELKIES_CONTROL_PORT` | `8083` | Port for the internal control plane API, used for managing access tokens when in secure mode. | +| `SELKIES_MASTER_TOKEN` | `''` | Master token to enable secure mode. If set, clients must authenticate using tokens provided via the control plane API. | | `SELKIES_DRI_NODE` (or `DRI_NODE`) | `''` | Path to the DRI render node for VA-API. | | `SELKIES_AUDIO_DEVICE_NAME` | `'output.monitor'` | Audio device name for pcmflux capture. | | `SELKIES_WATERMARK_PATH` (or `WATERMARK_PNG`) | `''` | Absolute path to the watermark PNG file. | @@ -212,6 +214,43 @@ All base images are built for x86_64 and aarch64 platforms. | Kali | kali | | Ubuntu | ubuntunoble | +### Control Plane API for Token Management + +When secure mode is enabled (`SELKIES_MASTER_TOKEN` is set), the server runs a control plane API on the `control_port` (default: 8083). This API is used to dynamically set and update the access tokens that clients can use to connect. This control plane port is meant for integrators that want to wrap the baseimage in their own platforms and handle authentication, this port should never be exposed publically. + +**Endpoint:** `POST /tokens` + +**Authentication:** The request must include an `Authorization` header with the master token: `Authorization: Bearer ` + +**Request Body:** A JSON object where each key is a unique access token string you create, and the value is a permissions object defining that token's capabilities. + +**Permissions Object Fields:** +* `"role"`: (String, required) Can be one of the following: + * `"controller"`: Full access. Can send keyboard, mouse, and all other input events. + * `"viewer"`: Restricted access. Primarily for viewing the stream. Can be granted specific input rights via the `slot` property. +* `"slot"`: (Integer or `null`, required) Assigns an input slot, for gamepads. + * `null`: No specific input slot. A viewer with a `null` slot has no input capabilities. + * `1`: Grants the `viewer` control over the **Player 1** gamepad *only*. + * `2`: Grants the `viewer` control over the **Player 2** gamepad *only*. + * `3`: Grants the `viewer` control over the **Player 3** gamepad *only*. + * `4`: Grants the `viewer` control over the **Player 4** gamepad *only*. + +**Behavior:** When a valid request is received, the server replaces its entire set of active tokens with the new set provided in the payload. It then runs a reconciliation process: any connected client whose token is now invalid or has changed permissions will be disconnected and users input capabilities will be modified live. + +**Example `curl` Command:** +```bash +curl -X POST http://localhost:8083/tokens \ +-H "Authorization: Bearer my-secret-master-token" \ +-H "Content-Type: application/json" \ +-d '{ + "user-token-1": {"role": "controller", "slot": null}, + "user-token-2": {"role": "viewer", "slot": 1}, + "user-token-3": {"role": "viewer", "slot": null} +}' +``` + +Clients in this mode must connect with a valid token (`?token=...`) to establish a WebSocket connection. + ### DRI3 GPU Acceleration For accelerated apps or games, render devices can be mounted into the container and leveraged by applications using: