# Hub-Spoke Architecture

> A local daemon coordinates sessions across clients, while spoke workers handle agent execution.

- 网址：https://funcoding.ai/agents/cline/sdk/architecture/hub-spoke/
- 来源：Cline 官方文档原文（英文），Apache-2.0 许可，同步于 2026-10-11
- 官方原文：https://docs.cline.bot/sdk/architecture/hub-spoke

---
The SDK uses a hub-spoke architecture for production deployments. A background daemon (the hub) coordinates session state and event routing, spoke workers execute the agent loop, and clients (CLI, VS Code, JetBrains, etc.) attach as peers over WebSocket.

## Why Hub-Spoke?

A single-process architecture works for simple scripts, but breaks down when you need:

- Sessions that survive when a window closes or the CLI exits
- Multiple clients viewing and controlling the same session
- Scheduled agents that run when no client is connected
- Process isolation so a runaway agent doesn't freeze the UI

The hub-spoke model solves all of these by separating coordination from execution, and both from the client UI.

## Three Roles

**Hub**

Singleton daemon per machine. Coordinates sessions, routes events and approvals, manages schedules, brokers capabilities between clients. Does not run the agent loop.

**Spoke**

Worker process running `@cline/core`. Executes the agent loop, calls tools, streams output. Reports events back to the hub. Owned by the daemon, not by any client.

**Client**

CLI, VS Code, JetBrains, or any custom app. Discovers the hub, registers over WebSocket, attaches to sessions, sends user input, receives streamed events.

The single rule that keeps it clean: clients participate, spokes execute, the hub coordinates. No two roles should overlap.

## Communication Flow

Clients connect to the hub over WebSocket. The hub routes commands and streams events. Spokes report back to the hub, never directly to clients.

**Client discovers or starts the hub**

The hub is a singleton daemon per machine. If one isn't running, `ClineCore` starts it automatically. Discovery uses lock files at `~/.cline/data/locks/hub/owners/`.

**Client registers and attaches to a session**

The client sends a `client.register` command over WebSocket, advertising its capabilities (shell access, file editing, diff viewing, etc.). It then creates or attaches to a session.

**Hub assigns a spoke to execute**

The hub spawns or assigns a spoke worker to run the agent loop. The spoke executes tools, streams partial output, and handles abort/cancel.

**Hub fans out events to all attached clients**

As the spoke produces events (text deltas, tool calls, usage), the hub relays them to every client attached to that session. Clients can come and go without interrupting execution.

**Client disconnects, session keeps running**

If the CLI exits or a window closes, the spoke continues executing. Another client can attach to the same session and pick up the event stream mid-flight.

## Backend Modes

`ClineCore` selects the execution mode based on configuration:

```typescript
const cline = await ClineCore.create({
  clientName: "my-app",
  backendMode: "auto",
})
```

| Mode | Behavior |
|------|----------|
| `auto` | Prefers a compatible local hub when available, falls back to local in-process execution when not. This is the default. |
| `hub` | Requires a compatible WebSocket hub. Throws if one is not reachable. |
| `remote` | Requires an explicit remote WebSocket hub endpoint. For deployments where the hub doesn't live on the user's machine. |
| `local` | Always uses local in-process execution with local SQLite/file storage. No hub, no shared sessions. |

### When to Use Each Mode

Use `local` for:
- Simple scripts and one-off tasks
- Testing and development
- Environments where a background process isn't appropriate

Use `hub` (or `auto`) for:
- Session persistence across client restarts
- Multiple clients sharing the same session
- Scheduled agents
- Connector integrations (Telegram, Slack, etc.)

Use `remote` for:
- Cloud deployments where the hub runs on a server
- Team-shared hub instances

## Capability Brokerage

When multiple clients are attached to a session, the hub routes capability requests to whichever client can handle them. Clients advertise their capabilities at registration.

For example, VS Code might register `open-file`, `reveal-diff`, and `run-build` capabilities. The CLI might register `shell` and `run-tests`. When the agent needs to open a diff, the hub routes the request to VS Code. When it needs to run a shell command, the hub routes to the CLI.

This means a session gets richer as more clients join. A CLI session can later be enriched by VS Code attaching -- an IDE selection can be sent into a running terminal session, or a diff created by one client can be opened by another.

## Session Persistence

Sessions are stored with full conversation history, tool call records, and metadata. The hub keeps a SQLite index for listing sessions, and a folder for each session with its metadata and messages.

```
~/.cline/data/
  db/
    sessions.db                  # SQLite session index
  sessions/
    [session-id]/
      [session-id].json          # Session metadata
      [session-id].messages.json # Conversation history
```

Sessions can have multiple participants, each tracked with a role (`creator`, `participant`, `observer`). The session persists independently of any single client's lifecycle.

## Managing the Hub

The hub starts automatically when `ClineCore` needs it. You can also manage it manually:

```bash
cline hub start      # Start the hub daemon
cline hub stop       # Stop it
cline hub status     # Check if running
cline hub ensure     # Start if not running, return URL
cline hub drain      # Refuse new work while accepted runs finish (--off lifts it)
cline hub upgrade    # Drain the hub and restart it; does not wait for --zen or scheduled tasks
```

The hub listens on `127.0.0.1:25463` by default (set `CLINE_HUB_PORT` to change the port) and logs to `~/.cline/data/logs/hub-daemon.log`.

## Multi-Client Access

Multiple clients can connect to the same hub and attach to the same session simultaneously:

```bash
# Terminal 1: start a task
cline "Work on feature X"

# Terminal 2: attach to the same session from VS Code or another CLI

# Terminal 3: Telegram connector
cline connect telegram -k $TOKEN

# All three share the same hub and can access the same sessions
```

## Process Isolation

If a client crashes, the hub and its running spokes are unaffected. The session continues executing in the spoke worker. When the client reconnects (or a different client attaches), it receives the full session history and resumes the live event stream.

The spoke also has a process boundary from the hub itself. A runaway model call in a spoke doesn't degrade the hub's ability to coordinate other sessions, route approvals, or fan out events.