# open-webui/tether architecture

> Architecture diagram of the GitHub repository open-webui/tether, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-webui/tether
- Repository: https://github.com/open-webui/tether

## Overview

Tether is an Electron desktop companion for Open WebUI: users configure a WebUI connection, select it in the desktop interface, and work with it alongside local terminal access. The graph covers the renderer-to-main-process boundary, connection/session handling, terminal runtime and workspace sandboxing, plus Spotlight and MCP integrations documented by the README. Relationships involving unsampled modules are limited to source-index references or explicit README statements; MCP wiring is shown as unverified.

Main entry points: [`src/main/connections.ts`](https://github.com/open-webui/tether/blob/main/src/main/connections.ts) (Connection manager), [`src/preload/index.ts`](https://github.com/open-webui/tether/blob/main/src/preload/index.ts) (IPC bridge), [`src/renderer/src/components/Settings.svelte`](https://github.com/open-webui/tether/blob/main/src/renderer/src/components/Settings.svelte) (Settings), [`src/renderer/src/App.svelte`](https://github.com/open-webui/tether/blob/main/src/renderer/src/App.svelte) (Connection workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_app_ui["Connection workspace<br/>[App.svelte]"]
  node_settings_ui["Settings<br/>[Settings.svelte]"]
  node_spotlight_ui["Spotlight UI<br/>[Spotlight.svelte]"]
  node_terminal_ui["Terminal view<br/>[Terminal.svelte]"]
  node_preload["IPC bridge<br/>[index.ts]"]
  node_main["Electron main<br/>[index.ts]"]
end

subgraph group_connections["WebUI connections"]
  node_connections["Connection manager<br/>[connections.ts]"]
  node_sessions["Connection sessions<br/>[sessions.ts]"]
  node_network["Network checks<br/>[network.ts]"]
  node_relay["Connection relay<br/>[relay.ts]"]
  node_store[("App state store<br/>[store.ts]")]
  node_access["Access handling<br/>[access.ts]"]
end

subgraph group_terminal["Local terminal"]
  node_terminal_settings["Terminal settings"]
  node_runtime["Local runtime<br/>[runtime.ts]"]
  node_terminal_service["Managed service<br/>[managedService.ts]"]
  node_sandbox["Workspace sandbox<br/>[index.ts]"]
  node_sandbox_policy["Sandbox policy<br/>[policy.ts]"]
end

subgraph group_platform["Desktop services"]
  node_mcp["MCP integrations<br/>[mcp.ts]"]
  node_spotlight["Spotlight service<br/>[spotlight.ts]"]
end

node_user(("Desktop user"))
node_webui["Open WebUI"]
node_external_mcp["MCP servers"]

node_user -->|"uses"| node_app_ui
node_app_ui -->|"invokes API"| node_preload
node_settings_ui -->|"invokes API"| node_preload
node_terminal_ui -->|"uses terminal API"| node_preload
node_preload -->|"bridges IPC"| node_main
node_main -->|"initializes"| node_connections
node_connections -->|"uses sessions"| node_sessions
node_connections -->|"checks network"| node_network
node_connections -->|"uses relay"| node_relay
node_connections -->|"uses store"| node_store
node_connections -->|"uses access"| node_access
node_sessions -->|"reads state"| node_store
node_sessions -->|"checks network"| node_network
node_app_ui -->|"connects to"| node_webui
node_settings_ui -->|"configures runtime"| node_runtime
node_runtime -->|"manages process"| node_terminal_service
node_terminal_service -->|"launches sandbox"| node_sandbox
node_sandbox -->|"verifies workspace"| node_sandbox_policy
node_terminal_ui -.->|"streams terminal"| node_terminal_service
node_main -->|"initializes"| node_spotlight
node_spotlight_ui -.->|"controls"| node_spotlight
node_settings_ui -.->|"configures servers"| node_mcp
node_mcp -.->|"connects servers"| node_external_mcp

click node_app_ui "https://github.com/open-webui/tether/blob/main/src/renderer/src/App.svelte"
click node_settings_ui "https://github.com/open-webui/tether/blob/main/src/renderer/src/components/Settings.svelte"
click node_spotlight_ui "https://github.com/open-webui/tether/blob/main/src/renderer/src/components/Spotlight.svelte"
click node_terminal_ui "https://github.com/open-webui/tether/blob/main/src/renderer/src/components/Terminal.svelte"
click node_preload "https://github.com/open-webui/tether/blob/main/src/preload/index.ts"
click node_main "https://github.com/open-webui/tether/blob/main/src/main/index.ts"
click node_connections "https://github.com/open-webui/tether/blob/main/src/main/connections.ts"
click node_sessions "https://github.com/open-webui/tether/blob/main/src/main/sessions.ts"
click node_network "https://github.com/open-webui/tether/blob/main/src/main/network.ts"
click node_relay "https://github.com/open-webui/tether/blob/main/src/main/relay.ts"
click node_store "https://github.com/open-webui/tether/blob/main/src/main/store.ts"
click node_access "https://github.com/open-webui/tether/blob/main/src/main/access.ts"
click node_terminal_settings "https://github.com/open-webui/tether/blob/main/src/renderer/src/components/Settings/OpenTerminal.svelte"
click node_runtime "https://github.com/open-webui/tether/blob/main/src/main/runtime.ts"
click node_terminal_service "https://github.com/open-webui/tether/blob/main/src/main/process/managedService.ts"
click node_sandbox "https://github.com/open-webui/tether/blob/main/src/main/sandbox/index.ts"
click node_sandbox_policy "https://github.com/open-webui/tether/blob/main/src/main/sandbox/policy.ts"
click node_mcp "https://github.com/open-webui/tether/blob/main/src/main/mcp.ts"
click node_spotlight "https://github.com/open-webui/tether/blob/main/src/main/spotlight.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_ui,node_settings_ui,node_spotlight_ui,node_terminal_ui,node_preload,node_main,node_user,node_webui toneBlue
class node_connections,node_sessions,node_network,node_relay,node_store,node_access toneAmber
class node_terminal_settings,node_runtime,node_terminal_service,node_sandbox,node_sandbox_policy,node_external_mcp toneMint
class node_mcp,node_spotlight toneRose
```

## Components

### Desktop experience

- [Connection workspace](https://github.com/open-webui/tether/blob/main/src/renderer/src/App.svelte): `src/renderer/src/App.svelte`
- [Settings](https://github.com/open-webui/tether/blob/main/src/renderer/src/components/Settings.svelte): `src/renderer/src/components/Settings.svelte`
- [Spotlight UI](https://github.com/open-webui/tether/blob/main/src/renderer/src/components/Spotlight.svelte): `src/renderer/src/components/Spotlight.svelte`
- [Terminal view](https://github.com/open-webui/tether/blob/main/src/renderer/src/components/Terminal.svelte): `src/renderer/src/components/Terminal.svelte`
- [IPC bridge](https://github.com/open-webui/tether/blob/main/src/preload/index.ts): `src/preload/index.ts`
- [Electron main](https://github.com/open-webui/tether/blob/main/src/main/index.ts): `src/main/index.ts`

### WebUI connections

- [Connection manager](https://github.com/open-webui/tether/blob/main/src/main/connections.ts): `src/main/connections.ts`
- [Connection sessions](https://github.com/open-webui/tether/blob/main/src/main/sessions.ts): `src/main/sessions.ts`
- [Network checks](https://github.com/open-webui/tether/blob/main/src/main/network.ts): `src/main/network.ts`
- [Connection relay](https://github.com/open-webui/tether/blob/main/src/main/relay.ts): `src/main/relay.ts`
- [App state store](https://github.com/open-webui/tether/blob/main/src/main/store.ts): `src/main/store.ts`
- [Access handling](https://github.com/open-webui/tether/blob/main/src/main/access.ts): `src/main/access.ts`

### Local terminal

- [Terminal settings](https://github.com/open-webui/tether/blob/main/src/renderer/src/components/Settings/OpenTerminal.svelte): `src/renderer/src/components/Settings/OpenTerminal.svelte`
- [Local runtime](https://github.com/open-webui/tether/blob/main/src/main/runtime.ts): `src/main/runtime.ts`
- [Managed service](https://github.com/open-webui/tether/blob/main/src/main/process/managedService.ts): `src/main/process/managedService.ts`
- [Workspace sandbox](https://github.com/open-webui/tether/blob/main/src/main/sandbox/index.ts): `src/main/sandbox/index.ts`
- [Sandbox policy](https://github.com/open-webui/tether/blob/main/src/main/sandbox/policy.ts): `src/main/sandbox/policy.ts`

### Desktop services

- [MCP integrations](https://github.com/open-webui/tether/blob/main/src/main/mcp.ts): `src/main/mcp.ts`
- [Spotlight service](https://github.com/open-webui/tether/blob/main/src/main/spotlight.ts): `src/main/spotlight.ts`

### Other components

- **Desktop user**
- **Open WebUI**
- **MCP servers**

## Connections

- Desktop user → Connection workspace: uses (evidence: `README.md`)
- Connection workspace → IPC bridge: invokes API (evidence: `src/renderer/src/App.svelte`)
- Settings → IPC bridge: invokes API
- Terminal view → IPC bridge: uses terminal API (evidence: `src/renderer/src/components/Terminal.svelte`)
- IPC bridge → Electron main: bridges IPC (evidence: `src/preload/index.ts`)
- Electron main → Connection manager: initializes (evidence: `src/main/index.ts`)
- Connection manager → Connection sessions: uses sessions (evidence: `src/main/connections.ts`)
- Connection manager → Network checks: checks network (evidence: `src/main/connections.ts`)
- Connection manager → Connection relay: uses relay (evidence: `src/main/connections.ts`)
- Connection manager → App state store: uses store (evidence: `src/main/connections.ts`)
- Connection manager → Access handling: uses access (evidence: `src/main/connections.ts`)
- Connection sessions → App state store: reads state (evidence: `src/main/sessions.ts`)
- Connection sessions → Network checks: checks network (evidence: `src/main/sessions.ts`)
- Connection workspace → Open WebUI: connects to (evidence: `README.md`)
- Settings → Local runtime: configures runtime
- Local runtime → Managed service: manages process (evidence: `src/main/process/managedService.ts`)
- Managed service → Workspace sandbox: launches sandbox (evidence: `src/main/sandbox/index.ts`)
- Workspace sandbox → Sandbox policy: verifies workspace (evidence: `src/main/sandbox/index.ts`)
- Terminal view → Managed service: streams terminal
- Electron main → Spotlight service: initializes (evidence: `src/main/index.ts`)
- Spotlight UI → Spotlight service: controls
- Settings → MCP integrations: configures servers
- MCP integrations → MCP servers: connects servers (evidence: `README.md`)
