Cline Architecture: Hub, Spokes, and Sessions

Official Cline SDK docs list four production failure modes that break single-process agents: sessions die when a window or CLI exits, only one client can view the same run, scheduled work needs a connected UI, and a runaway agent freezes the interface. The hub-spoke architecture exists to fix those four constraints by splitting coordination, execution, and client UI into separate roles.

Cline architecture separates a hub daemon that coordinates sessions from spoke workers that run the agent loop and clients (CLI, VS Code, JetBrains, or a custom app) that attach over WebSocket. That one-sentence model is the whole production design. Clients participate, spokes execute, and the hub coordinates. No two roles should own the same job.

In prose, the three roles look like this:

• Hub: A singleton daemon per machine. It coordinates sessions, routes events and approvals, manages schedules, and brokers capabilities between clients. It does not run the agent loop.
• Spoke: A worker process running @cline/core. It executes the agent loop, calls tools, streams output, and reports events back to the hub. The daemon owns the spoke, not any individual client.
• Client: CLI, VS Code, JetBrains, or your own app. It discovers the hub, registers over WebSocket, attaches to sessions, sends user input, and receives streamed events.

That split is deliberate. Single-process scripts still work for one-off tasks, but production use needs sessions that keep running after a window closes, multi-client attachment to the same session, scheduled agents with no UI present, and process isolation so a hung tool call cannot freeze the editor.

DataForSEO reports only about 40 US monthly searches for "cline architecture" at keyword difficulty 21. The query is small, but the content gap is real: marketing posts restate product features while official docs spend a full page on hub roles, capability brokerage, and backend mode tradeoffs. This guide stays on those production details.

Under the covers, the same product surface is also a layered SDK. Applications talk to @cline/core for sessions, storage, built-in tools, hub support, and automation. Core depends on @cline/agents (browser-compatible agent loop), @cline/llms (provider gateway and model catalogs), and @cline/shared (types, tools, hooks). Hub-spoke is the runtime topology for production; the package stack is the library boundary when you embed Cline yourself.

Helpful references: Fast.io Workspaces, Fast.io Collaboration, and Fast.io AI.

The hub is a background daemon that owns session state and event routing. Official docs put the default listen address at 127.0.0.1:25463 and hub logs at ~/.cline/logs/hub-daemon.log. Discovery uses lock files under ~/.cline/locks/hub/owners/. If a compatible hub is not already running, ClineCore can start one automatically.

You can also manage the hub from the CLI:

cline hub start
cline hub stop
cline hub status
cline hub ensure

cline hub ensure starts the daemon when needed and returns its URL. That is the practical entry point when you want a stable local coordinator without guessing whether something is already listening on port 25463.

Communication sequence

Clients never talk to spokes directly. The documented flow is:

1. The client discovers or starts the hub.
2. The client sends client.register over WebSocket and advertises capabilities such as shell access, file editing, or diff viewing.
3. The client creates a session or attaches to an existing one.
4. The hub spawns or assigns a spoke worker to run the agent loop.
5. The spoke executes tools, streams partial output, and reports events to the hub.
6. The hub fans those events out to every client attached to the session.

Because the hub owns fan-out, clients can come and go without interrupting execution. Close VS Code and the spoke keeps working. Open another terminal later and attach to the same session mid-flight. That is the difference between "chat that dies with the window" and "agent work that outlives the UI."

Process isolation Isolation cuts both ways.

If a client crashes, the hub and its running spokes stay up. The session continues in the worker. When the same client or a different client reconnects, it receives session history and resumes the live stream.

The spoke is also isolated from the hub. A runaway model call or hung tool inside a spoke does not stop the hub from coordinating other sessions, routing approvals, or fanning events to remaining clients. That boundary is why production agents should prefer hub mode over stuffing the agent loop into the IDE process itself.

What the hub does not do

The hub does not execute tools, call models, or own the agent loop. Those responsibilities stay on the spoke. Keeping coordination thin is what lets one daemon host many sessions without turning into a second full agent runtime.

ClineCore chooses how execution is hosted through backendMode. Official docs document four values:

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

• auto: Prefers a compatible local hub when available, falls back to in-process local execution when not. This is the default.
• hub: Requires a compatible WebSocket hub. Throws if none is reachable.
• remote: Requires an explicit remote WebSocket hub endpoint for hubs that do not live on the user machine.
• local: Always uses local in-process execution with local SQLite and file storage. No hub and no shared sessions.

Choosing a mode in practice

Use local for scripts, tests, and one-off tasks where a background daemon is overhead. Local mode is honest about its limits: no shared sessions across clients, no hub-backed multi-client fan-out, and no scheduled agent that outlives the process.

Use hub or the default auto path when you need session persistence across client restarts, multiple clients on the same session, scheduled agents, or connector-style integrations such as Telegram or Slack clients attaching to the same hub. Docs explicitly call out those cases as hub strengths.

Use remote when the hub lives on a server or when a team wants a shared hub instance rather than one daemon per laptop. Remote mode is the bridge from "agent on my machine" to "agent coordinated somewhere else," but it still depends on a reachable WebSocket hub endpoint you configure.

Tradeoffs production teams actually hit

Local mode is easiest to reason about and hardest to share. Hub mode adds a daemon, lock files, a port, and log paths to monitor, but it unlocks multi-client sessions and disconnect-tolerant runs. Remote mode moves operational burden to wherever the hub runs: network reachability, auth boundaries you place around the endpoint, and backup of session data.

For CI, local mode is often enough for a single headless job. For a developer who starts work in the CLI, continues in VS Code, and checks progress from another terminal, hub mode is the architecture the product was designed around. Force-fitting multi-client behavior onto pure local mode means reinventing the hub yourself.

Keep Cline outputs in a workspace humans can open

Use Fast.io as the shared layer next to local Cline sessions: MCP-accessible workspaces, versioned files, Intelligence Mode search, and a 14-day free trial for your org.

Start 14-Day Trial

Sessions are the durable unit of work in hub mode. Official docs store them under ~/.cline/data/sessions/ with two layers:

~/.cline/data/sessions/
  sessions.db                    # SQLite index
  [session-id].json              # Authoritative session record

The SQLite database is the index for efficient listing. Each session's JSON snapshot is the source of truth for conversation history, tool call records, and metadata. Sessions can list participants with roles such as creator, participant, and observer. The session lifecycle is independent of any single client's lifecycle.

That design has operational consequences. Back up both the index and the JSON files if you care about history. Treat sessions.db alone as incomplete. Treat a lone JSON file as hard to discover at scale. The pair is intentional: fast listing plus authoritative per-session state.

Capability brokerage

When more than one client attaches to a session, the hub routes capability requests to whichever client can handle them. Clients advertise capabilities at registration. VS Code might register open-file, reveal-diff, and run-build. The CLI might register shell and run-tests. When the agent needs a diff view, the hub can route to VS Code. When it needs a shell, it can route to the CLI.

Sessions get richer as more clients join. A terminal-only run can later gain IDE selection context when VS Code attaches. A diff produced in one client can be opened in another. Brokerage is not a plugin marketplace; it is request routing based on what each attached client claimed it can do.

Multi-client attachment

Multiple clients can connect to the same hub and attach to the same session at once. Docs show a simple pattern: start a task from one terminal, attach from VS Code or another CLI, and optionally add a messaging connector. All share the hub and can access the same sessions.

Roles matter for how you think about access. A creator starts the work. Participants contribute input. Observers watch the stream without driving it. Exact product UI for role assignment can vary by client, but the architecture already assumes multi-party attachment rather than a single exclusive owner of the live run.

What multi-client is not

Multi-client attachment is not automatically multi-user cloud collaboration with org-level permissions. The default hub listens on localhost. Remote mode can place the hub elsewhere, but shared team review of files, durable shares, and human handoff of deliverables still need a storage layer outside ~/.cline when the audience is not sitting on the same machine.

Cline's local session store is built for agent runtime state: conversation history, tool records, and session metadata under ~/.cline/data/sessions/. That is the right place for the agent loop. It is a weak place for long-lived team deliverables.

Most teams already solve durable file storage one of a few ways:

• Keep agent patches and reports in the git repository that the spoke is editing
• Drop artifacts into object storage such as S3 when jobs are batch-oriented
• Sync folders through Google Drive or Dropbox when humans need a familiar drive UI

Those options work. They also leave gaps for agent-heavy workflows. Git is excellent for code, weaker for large media, branded client packages, or non-repo research dumps. Object storage is durable but rarely offers human-friendly review, semantic search over mixed file types, or agent-native tooling out of the box. Consumer drive sync is familiar, but it is not built around MCP tool calls, ownership transfer from agent accounts to humans, or workspace-scoped intelligence.

Fast.io sits in that gap as a shared workspace layer around Cline, not as a replacement for the hub or spoke. An agent (or a human driving Cline) can write code and intermediate files locally, then upload finished artifacts into an org-owned workspace where teammates open the same files in the UI. Intelligence Mode indexes workspace content for semantic search and citation-backed chat. Hybrid search combines full-text matching with meaning-based retrieval. Metadata Views turn contracts, invoices, or media dumps into queryable fields when the output is structured data rather than source code. See document data extraction for that structured layer.

Agents connect through the Fast.io MCP server over Streamable HTTP at /mcp (legacy SSE at /sse). Humans use the same workspace in the browser. Ownership transfer lets an agent account build workspaces and shares, then hand the organization to a human while retaining admin where needed. Per-file version history keeps concurrent edits auditable when several agents or people touch the same deliverable. Webhooks can notify downstream systems when files change so review does not depend on polling ~/.cline.

A practical split that holds up in production:

1. Let Cline hub mode own the live session, approvals, and agent loop.
2. Let the spoke edit the working tree and produce artifacts.
3. Put durable outputs, client-facing packages, and cross-machine review into shared storage such as git for code, S3 for bulk blobs, or a Fast.io workspace when humans and agents need the same intelligent workspace.
4. Prefer branded Send, Receive, or Exchange shares when outsiders need controlled access without a full org seat.

Pricing on Fast.io is organization-based: Starter at $29/month, Business at $99/month, Growth at $299/month, each with a 14-day free trial that requires a credit card. There is no permanent free plan and no free agent tier. The common agent path is free account creation, then a human creates or joins an org and starts the trial so durable team storage has a billable home.

The architecture lesson is simple. Cline's hub-spoke model solves client disconnects and multi-client control of the agent. Shared workspaces solve multi-person ownership of the files the agent produced. You usually need both once the work leaves a single developer's laptop.