Architecture

What each component owns, where the boundaries sit, and how credentials move — or deliberately don't. Start with Overview if you want the map first.

Four pieces, one hard rule#

Client (desktop / web)
  renders workspaces, chats, terminals, git review, settings
  holds no third-party integration credentials; for Local auth, transiently
  forwards direct provider keys or a scoped gateway virtual key to AnyHarness
  without persisting them in app storage

AnyHarness (runtime)
  runs the agent process; one shared runtime per machine,
  not one per workspace
  authoritative for runtime state: sessions, transcripts, terminals, workspaces
  the auth material it holds depends on how the agent authenticates

Runtime worker
  target-side bridge for enrollment, heartbeat, gateway configuration,
  catalog sync, and runtime/worker updates

Server (control plane)
  owns product metadata and config: accounts, orgs, workspace records,
  authentication, credentials, billing, projections, routing
  owns both gateways

The rule that never bends: third-party tool credentials never leave the control plane. Your Linear token, your Notion OAuth grant, your Slack access token — none of it is written to a workspace or handed to an agent. Every call to a connected tool goes through the integrations gateway instead. Model provider credentials follow a different, deliberate split, covered below.

Workspaces#

A workspace is a logical entity: a repository and branch paired with one execution target, its chat history, sessions, and review state. Its files are materialized at that target. The target stays fixed for the life of the workspace in the current product.

Both targets share the core chat, terminal, file, and git-review surfaces. Target-specific features and lifecycle still differ. See Workspaces for the full guide.

Agents and harnesses#

Proliferate calls each agent — Claude Code, Codex, OpenCode, Cursor, and others — through its own native harness (its CLI or agent protocol) rather than reimplementing it, so your existing login, tools, and model access carry over. See Agents for the supported list and per-agent notes.

The desktop app (and web)#

The desktop app (built on Tauri) is the primary client: it renders your workspaces, streams the transcript as an agent works, and drives terminals, files, and git review. It launches a single local AnyHarness runtime that serves all your local workspaces and talks to it over the same API a remote runtime would use. A lighter web client covers account settings.

The client implements no agent behavior and never receives the underlying credentials for connected integrations. Local model auth follows a different path: Desktop fetches the user's rendered auth document and forwards it to the local runtime. That document can contain a direct provider key or a scoped gateway virtual key, so those values pass through Desktop memory even though the app does not persist or display them. Native login state is read by the agent from its normal Local credential store.

AnyHarness: the runtime#

AnyHarness is the process that actually runs a session. Two things about it matter architecturally:

• One runtime per machine, not per workspace. The desktop app launches one shared AnyHarness runtime that serves every local checkout and worktree, and the client talks to it over the same API any runtime would expose. That keeps the interaction model consistent no matter how many workspaces you have open.
• Durable state vs. live execution. AnyHarness owns its own durable store — sessions, event history, and workspace records that survive a restart. Local chat history lives here, in the runtime, not on the Proliferate server. Live execution (the agent subprocess, its streams, pending permission prompts) exists only while the process runs. That split lets a session resume cleanly, and it's why a session belongs to one runtime at a time rather than floating between machines mid-task.

AnyHarness attaches the integrations gateway to every eligible session, and the model gateway when the agent is authenticated through it. It never calls a third-party tool API directly.

The runtime worker#

Some capabilities need a machine to have its own identity with the control plane, separate from the user in front of the client. That's the runtime worker: a small sidecar that enrolls with the server, sends a periodic heartbeat, and writes a gateway token to disk that AnyHarness reads at session launch. It runs optionally on your desktop machine, for integration access from local workspaces. AnyHarness only ever sees the narrower gateway token, never the worker's own credential.

The control plane (Server)#

The server is authoritative for product and control-plane state: accounts and organizations, connected integrations, encrypted key-vault entries, billing, policy, and routing. AnyHarness remains authoritative for runtime workspaces, sessions, ordered events, and transcripts. The control plane also hosts the gateway services. Self-hosted installs run this same control plane on infrastructure you own; see Self-hosting.

Two ways an agent authenticates#

Auth is set per user and per agent, not per workspace. Proliferate uses one of two modes:

• Native or direct-key auth. The agent can reuse its own existing login. A direct provider key is saved encrypted in the control-plane vault, then rendered to the runtime through Desktop memory. The agent calls the provider directly, not through the model gateway.
• Gateway auth. The credential is Proliferate-managed: shared managed credits, provider keys the server holds centrally, or an org policy that routes everyone through one place. LLM calls go through the model gateway.

You or your org admin choose which applies per agent. See Authentication. The integrations gateway is always in the path with no bypass; the model gateway only when an agent is in gateway auth mode.

The model gateway (LiteLLM)#

When an agent is in gateway auth mode, its LLM calls route through a gateway built on LiteLLM. The gateway infrastructure holds the upstream provider keys; AnyHarness gets a budget-scoped virtual key instead. The control plane returns that virtual key in the rendered auth document Desktop forwards to AnyHarness, so it passes through Desktop memory and is then persisted by the runtime. It is a scoped gateway credential, not a copy of an upstream provider key, and can be rotated or revoked centrally.

The integrations gateway#

Third-party tool calls (Linear, Notion, Slack, and others) always route through a control-plane-hosted MCP endpoint, no matter how the agent authenticates for models. AnyHarness advertises it to the agent as one tool source; the gateway resolves which provider is meant, attaches the right stored credential, and proxies the call. The agent and AnyHarness only ever see the Proliferate gateway and the worker's gateway token, never the underlying Linear API key or Notion OAuth grant.

Ownership at a glance#

Why it's split this way#

Keeping the integrations gateway mandatory means a compromised or misbehaving agent session can't walk off with your Slack token or Notion grant, however it authenticates for models. Making the model gateway optional keeps the default path simple: bring your own subscription and it works as it does outside Proliferate. The same split makes self-hosting real — run the control plane and the gateways yourself and point your client and runtimes at them, without changing how a workspace behaves day to day. See Self-hosting.