What each component owns, where the boundaries sit, and how credentials move (or, deliberately, don't). For the map first, start with Overview.

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 environment
  (your machine, or a cloud sandbox), 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.

Target	Where it runs
Local checkout	Directly in an existing repo on your machine.
Worktree	A separate branch and working tree on your machine. It is not a security boundary.
Cloud workspace	A remote sandbox that keeps running after you close your laptop.

Every target shares 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 whichever runtime backs the open workspace — local or remote — over the same API. A lighter web client covers browser-based access to cloud workspaces and 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 environment, not per workspace. On your machine, the desktop app launches one shared AnyHarness runtime that serves every local checkout and worktree. In the cloud, a single per-user sandbox runs one AnyHarness that backs all of that user's cloud workspaces. The client talks to whichever runtime is live over the same API. That keeps the core interaction model consistent without making Local and Cloud operationally identical.
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.

Moving work between local and cloud is a git operation, not a live handoff. Push the branch from one workspace and open or continue it on another; there is no way to migrate a running session between targets mid-task. See Local & cloud.

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 inside every cloud sandbox (started automatically alongside AnyHarness) and, 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, cloud workspace identity and lifecycle, connected integrations, encrypted key-vault entries, billing, policy, routing, and Cloud projections. AnyHarness remains authoritative for runtime workspaces, sessions, ordered events, and transcripts. The control plane provisions cloud sandboxes and 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, per agent, and per surface (Local and Cloud are configured separately) — not per workspace. Proliferate uses one of two modes:

Native or direct-key auth. On Local, the agent can reuse its own existing login. A direct provider key is saved encrypted in the control-plane vault, then rendered to the selected runtime — through Desktop memory for Local, or through Cloud materialization for a sandbox. 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 and surface. 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. For Local, 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. For Cloud, the materializer writes it into the sandbox runtime. In both cases 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

Component	Owns	Credential and state boundary
Client (desktop/web)	Rendering, user input, session control	Never receives integration credentials. Desktop transiently carries direct provider keys and gateway virtual keys while forwarding Local auth state, but does not persist them in app storage.
AnyHarness (runtime)	Agent execution and authoritative runtime workspaces, sessions, ordered events, transcripts, terminals, files, and git	Holds native/direct credentials or a scoped gateway virtual key as required. It never receives upstream gateway provider keys or underlying integration credentials.
Runtime worker	Target enrollment, heartbeat, gateway configuration, catalog sync, and runtime/worker updates	Bridges the control plane and runtime. It receives target-scoped gateway coordinates, not end-user integration credentials.
Server (control plane)	Accounts, orgs, cloud workspace records, auth configuration, encrypted key vault, billing, policy, routing, gateways, and Cloud projections	Owns product records and read projections, not the authoritative runtime session/event/transcript store inside AnyHarness.

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.

Architecture