Tether

Tether is the desktop companion app for Open WebUI, available for macOS, Windows and Linux. It signs in to your instance and connects your own computer to it, so chats can use that computer as a terminal and the app can show desktop notifications. The project lives at github.com/open-webui/tether. It is free for personal non-commercial use. Commercial or organizational production use needs an Open WebUI Enterprise License.

Connecting

1. In Tether, enter the address of your Open WebUI instance.
2. Tether opens your browser at /auth/sessions/<id> on that instance. If you are not signed in yet, you sign in first. After sign-in the page returns you to Tether.
3. Tether stays signed in and renews its session in the background.

Each signed-in app is a separate session. Signing out from the app ends its session. A session also ends when it is deleted through the API or when nobody uses it for SESSION_EXPIRES_IN (default 90d). Access tokens last 15 minutes and every renewal replaces the refresh token.

What the App Gets

• Your computer as a terminal. While Tether is connected, your computer appears in your terminal list as tether:<connection id>. Only you see it, and only when Tether offers the open_terminal service. If the connection drops, an open terminal shows "Connection interrupted. Reconnecting to the same terminal…" and resumes the same terminal once Tether is back. Each connection handles up to 16 active operations at a time.
• Notifications. When a chat finishes or fails, a calendar alert fires or a channel message arrives, the server sends a notification to your connected apps that opted in. They are sent only if you turned on Browser Notifications in Settings > Notifications.

Requirements

• ENABLE_WEBSOCKET_SUPPORT is on.
• Open WebUI runs with one worker, or with Redis when UVICORN_WORKERS is above 1. Without Redis, a multi-worker instance refuses Tether connections and requests to a Tether terminal fail with "Tether requires Redis with multiple WebUI workers."

The app configuration at /api/config reports features.tether when these requirements are met and features.auth_sessions on every instance.

Session API

These endpoints are for developers of native clients. requests, exchange and refresh need no sign-in; every other endpoint needs the bearer token of a signed-in user. Calls to create, requests, exchange, refresh and authorize are limited to 30 per minute per IP address.

Method	Path	Purpose
POST	/api/v1/auths/sessions/requests	Starts a browser sign-in. Send the app name, a loopback redirect_uri such as http://127.0.0.1:<port>/callback (host 127.0.0.1, explicit port, no query or fragment), a state of 32 to 256 URL-safe characters and a PKCE code_challenge (S256, 43 characters). The request is valid for 10 minutes. Returns the session_id to open at /auth/sessions/<id>.
GET	/api/v1/auths/sessions/{id}/request	Returns the name and expiry of a waiting request.
POST	/api/v1/auths/sessions/{id}/authorize	Approves the request as the signed-in user and returns the callback address with a one-time code that is valid for 60 seconds. The /auth/sessions/<id> page calls it.
POST	/api/v1/auths/sessions/exchange	Trades the session_id, code, redirect_uri and code_verifier for an access token and a refresh token.
POST	/api/v1/auths/sessions/refresh	Trades a refresh token for new tokens. Send an optional request_id to recover the new tokens when the response was lost: repeating the call with the same request_id returns them again.
POST	/api/v1/auths/sessions	Creates a session directly from an already signed-in request.
GET	/api/v1/auths/sessions	Lists your sessions.
DELETE	/api/v1/auths/sessions/{id}	Revokes one of your sessions.

Connection

A client connects to the websocket /api/v1/tether/connect and sends a hello message with version (1 or 2), the access token of a session, a connection_id, a name and a list of services. Setting notifications to true opts the connection in to notifications. The server answers with ready.