> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Architecture

Reference diagrams of the Warp stack, the cloud agent run lifecycle, self-hosted execution, and data boundaries.

The Automation Platform connects the tools that start agent work with the environments where that work runs. Warp operates the control plane, which coordinates runs and routes inference. Cloud agent runs execute in a Warp-hosted sandbox or on customer infrastructure. [Self-hosted](/platform/self-hosting/) execution, [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/), and customer-owned storage change where specific work and data stay.

## Stack overview

The platform has five layers: clients, the Warp-operated control plane that coordinates runs, the data plane that stores run data, the execution plane where agents access code and run tools, and external systems that agents read from and write to.

![Warp stack overview diagram showing clients, the Warp control plane, the data plane, Warp-hosted and customer-hosted execution planes, and external systems](/_astro/warp-stack-overview.B6F90D8o_Z1e96cA.webp?dpl=dpl_DH8NpjkfTpvx33S23CEQq1wtSq4H)

-   **Clients** - The surfaces that start and observe work, like the Warp app, the Oz CLI, the web app, the [factory dashboard](/factories/factory-dashboard/), and clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs.
-   **APIs** - The control plane’s entry points: the [Agent API and SDKs](/reference/api-and-sdk/), a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint.
-   **Control plane** - Warp coordinates runs, manages shared configuration, routes model calls, and records run history.
-   **Data plane** - Run data (transcripts, artifacts, and attachments) lives in Warp-managed storage or, on Enterprise plans, in your own Amazon S3, Google Cloud Storage, or Azure Blob Storage bucket. The choice is independent of where runs execute.
-   **Warp-hosted execution** - By default, each cloud agent run gets an isolated sandbox prepared from its environment. See [Warp-hosted execution](/platform/warp-hosting/).
-   **Self-hosted execution** - On Enterprise, a managed worker runs tasks on your infrastructure. Unmanaged setups run the Oz CLI in your CI or orchestrator. See [Self-hosting](/platform/self-hosting/).
-   **External systems** - The platform connects to identity providers, source control, integration providers, model providers, and a payment provider.

## Cloud agent run lifecycle

Every cloud agent run follows the same lifecycle, no matter what started it or where it executes. A trigger creates a task, the control plane resolves its configuration and dispatches it to an execution host, the agent works in a loop until it’s done, and the run leaves durable records behind.

![Cloud agent run lifecycle diagram showing triggers, the Warp control plane, the execution sandbox with its agent loop, LLM providers, and output targets](/_astro/cloud-agent-run-lifecycle.ByISHFqs_Z1wbhOx.webp?dpl=dpl_DH8NpjkfTpvx33S23CEQq1wtSq4H)

1.  **A trigger fires** - A [schedule](/platform/triggers/scheduled-agents/), an [integration](/platform/integrations/) event, an [API or SDK](/reference/api-and-sdk/) call, a CLI command, or a [Handoff](/platform/handoff/) from the Warp app starts the run.
2.  **The task is created** - The control plane opens a run record that tracks the task’s state, inputs, and provenance.
3.  **Configuration is resolved** - The platform picks the run’s [environment](/platform/environments/), [runner](/platform/runners/), execution host, and [model and harness](/platform/harnesses/).
4.  **The sandbox is provisioned** - The execution host clones the environment’s repositories, runs setup commands, and injects only the [secrets](/platform/secrets/) the run is allowed to use.
5.  **The agent loop runs** - The harness gathers context, calls the model, and runs tools until the task is done. Tools run in the sandbox. With the Warp Agent, model calls route through Warp to providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr); Claude Code and Codex call their provider directly.
6.  **Outputs land at their targets** - The agent pushes branches, opens pull requests, and replies to the Slack thread, Linear issue, or Jira work item that started the task.
7.  **The run record persists** - Transcripts, artifacts, and cost data attach to the run record.
8.  **The team has visibility** - Authorized users follow the run in the cloud agent dashboard or attach to it with [Agent Session Sharing](/agents/local-agents/session-sharing/).
9.  **The sandbox tears down** - When snapshotting is enabled, the platform captures workspace changes for a later [Handoff](/platform/handoff/), then destroys the sandbox.

During the run, prompts and code context, command and tool outputs, MCP tool calls and results, transcripts and run status, and model requests and responses pass through the control plane for session management and inference.

Self-hosted runs follow the same lifecycle; steps 4 through 6 execute on your managed worker instead of a Warp-hosted sandbox. See [Self-hosted execution flow](#self-hosted-execution-flow) for that variant.

### Sequence view

This sequence diagram shows the requests and responses exchanged among a trigger, a per-run sandbox, the Warp control plane, and external providers during a cloud agent run.

![Warp-hosted run sequence diagram showing numbered request and response flows between the trigger, the per-run sandbox, the Warp control plane, and providers and source control](/_astro/warp-hosted-run-sequence.CumOXcPq_Z2f8PXw.webp?dpl=dpl_DH8NpjkfTpvx33S23CEQq1wtSq4H)

## Self-hosted execution flow

Self-hosted execution keeps checkout, commands, and the workspace on your infrastructure while the Automation Platform keeps orchestrating, observing, and routing inference. A worker daemon dials out to Warp, so no inbound firewall ports are needed, and executes tasks locally. The numbers in the diagram mark the route.

![Self-hosted execution architecture diagram showing the managed worker on customer infrastructure connecting outbound to the Warp control plane, with numbered flow steps](/_astro/customer-dedicated-saas.DsiqMsRn_ZAJiQg.webp?dpl=dpl_DH8NpjkfTpvx33S23CEQq1wtSq4H)

1.  **The worker connects** - You run the managed worker (`oz-agent-worker`) on your infrastructure. It authenticates with an agent API key and holds an outbound-only connection, waiting for tasks routed to its [`--host`](/platform/self-hosting/#routing-runs-to-self-hosted-workers) ID.
2.  **Warp assigns the task** - When a trigger targets your worker, the control plane sends the task, its resolved configuration, and scoped runtime credentials over that connection.
3.  **The agent runs on your backend** - The worker clones repositories, runs setup, injects allowed [secrets](/platform/secrets/), and executes in a Docker container, a Kubernetes Job, or directly on the host, depending on the [backend](/platform/self-hosting/#managed-architecture) you chose. Code, build artifacts, and workspaces stay on your machines.
4.  **Run data returns to Warp** - Status, transcripts, artifacts, attachments, and telemetry flow back for the run record. Content the agent puts into prompts or results can include code context; see [security and networking](/platform/self-hosting/security-and-networking/).
5.  **Warp routes inference** - With the Warp Agent, model calls go from your worker through Warp to LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), or through your own provider account with [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/). Claude Code and Codex call their provider directly from your infrastructure.
6.  **Your team monitors the run** - Runs on self-hosted workers appear in the cloud agent dashboard and support [Agent Session Sharing](/agents/local-agents/session-sharing/), the same as Warp-hosted runs.

### Self-hosted sequence view

This sequence diagram shows the requests and responses exchanged among a trigger, your worker and sandbox, the Warp control plane, and external providers during a self-hosted run.

![Self-hosted run sequence diagram showing numbered request and response flows between the trigger, customer infrastructure, the Warp control plane, and providers](/_astro/self-hosted-run-sequence.RwvcRAWY_Z284S1x.webp?dpl=dpl_DH8NpjkfTpvx33S23CEQq1wtSq4H)

1.  **Create task** - A trigger fires: an integration event, a schedule, an API or SDK call, a CLI command, or a Handoff.
2.  **Assign task** - The control plane delivers the task over the worker’s authenticated connection, with resolved configuration and scoped runtime credentials.
3.  **Prepare workspace** - The worker clones repositories, runs setup commands, and injects allowed secrets.
4.  **Prompt and context** - The agent gathers context inside the sandbox and sends it for inference.
5.  **Inference** - Warp Agent model calls route through Warp to LLM providers under ZDR, or through your own provider account with [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/).
6.  **Run tools** - Tool calls execute locally: files, commands, internal services, and MCP servers.
7.  **Results** - Transcripts, tool outputs, and lifecycle updates return to the run record.
8.  **Outputs** - The agent pushes a branch, opens a pull request, and replies to the integration that started the run.
9.  **Observability** - Your team follows and steers the run from the dashboard and shared sessions.

## Warp Factories work-item flow

A software factory assembles the Automation Platform‘s primitives — runs, environments, runners, integrations, and secrets — into one measurable workflow. Work enters from the tools your team already uses, a foreman coordinates specialized agents through the stages each work item needs, and a human makes the final call.

![Warp Factories system diagram showing work sources, automations, the foreman and stage agents, human handoff, the factory definition, platform execution, the factory dashboard, and the measure-and-improve loop](/_astro/factories-work-item-flow.D9o3ediX_Z2x2Y6m.webp?dpl=dpl_DH8NpjkfTpvx33S23CEQq1wtSq4H)

[How Warp Factories work](/factories/how-factories-work/) explains each component in the diagram and how a work item moves through the stages.

## Data security and boundaries

Every run moves a few distinct classes of data, and each class has its own boundary. This section maps them across your infrastructure, the Warp platform, model providers, and the data plane where run data is stored. All communication is encrypted in transit (TLS 1.2+), all stored data is encrypted at rest (AES-256), and known secret values are redacted at output boundaries.

![Warp-hosted data security and boundaries diagram showing repositories, clients, and integrations in customer infrastructure, the per-run sandbox and control plane on the Warp platform, model providers, and the Warp-managed or customer-owned data plane](/_astro/warp-hosted-data-boundaries.695U6Z1v_ZxAHfS.webp?dpl=dpl_DH8NpjkfTpvx33S23CEQq1wtSq4H)

-   **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store repository clones or train on your code. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure. Either way, code context the agent puts into prompts, transcripts, or artifacts transits Warp and may persist as run data.
-   **Prompts and context** - With the Warp Agent, model calls route through Warp to LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements: providers don’t retain or train on the traffic. [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) keeps the same route but uses your provider account. Claude Code and Codex call their provider directly from the execution environment, under your provider agreement rather than Warp’s.
-   **Run data** - Transcripts, artifacts, and run attachments are stored in Warp-managed storage, encrypted at rest and access-controlled by your team’s roles. Enterprise teams can instead write them to a customer-owned Amazon S3, Google Cloud Storage, or Azure Blob Storage bucket. Warp writes with a service identity you authorize on the bucket policy, so no cloud credentials are shared. The choice is independent of where runs execute.
-   **Control-plane data** - Warp always retains what it needs to operate the platform: user and organization settings, agent and factory configuration, orchestration and lifecycle metadata, trigger and integration metadata, operational logs, and usage and billing.
-   **Execution secrets** - Secrets you inject locally never transit Warp. [Managed secrets](/platform/secrets/) are stored encrypted and fetched just-in-time by the execution environment with a run-scoped token, and each delivery is audit-logged. [Secret redaction](/support-and-community/privacy-and-security/secret-redaction/) at output boundaries is a backstop, not a substitute for narrow scopes and rotation.
-   **Inference credentials** - With the Warp Agent and Bring Your Own LLM, provider credentials are used only at the Warp–provider boundary and never enter the sandbox. Claude Code and Codex use your provider credentials inside the execution environment, delivered as managed secrets or injected locally.
-   **MCP credentials** - OAuth-connected and URL-backed MCP servers are proxied through the control plane, so their credentials stay with Warp. Command-based servers run inside the execution environment with local or managed secrets. Direct connections from the execution environment to URL-backed servers are in early access.
-   **Repository identity** - Agents check out and push with scoped repository credentials, and pull requests are attributed to the creating user or to the agent, depending on the configured [credential strategy](/factories/factory-as-code/#credentialstrategy). Branch protection and repository permissions apply as usual.

### With self-hosted execution

[Self-hosted execution](/platform/self-hosting/) moves the execution boundary: checkout, builds, and command execution stay on your infrastructure, and no Warp-hosted sandbox is involved. The control plane still coordinates runs, holds control-plane data, and routes Warp Agent inference. Run data goes to Warp-managed storage or your own bucket, the same as for Warp-hosted runs.

![Self-hosted data security and boundaries diagram showing what stays in customer infrastructure, what Warp retains, the Warp-managed or customer-owned data plane, and what transits Warp to model providers](/_astro/data-security-boundaries.y-9Aiqj9_Z2jVQY6.webp?dpl=dpl_DH8NpjkfTpvx33S23CEQq1wtSq4H)

## Related pages

-   [Deployment patterns](/platform/deployment-patterns/) - Choose between CLI-only, Warp-hosted, and self-hosted deployments.
-   [Self-hosting overview](/platform/self-hosting/) - Managed vs unmanaged architectures and setup guides.
-   [Self-hosting security and networking](/platform/self-hosting/security-and-networking/) - The data model and egress requirements for self-hosted workers.
-   [Security overview](/enterprise/security-and-compliance/security-overview/) - Warp’s data handling, encryption, and compliance posture.
-   [How Warp Factories work](/factories/how-factories-work/) - The work-item lifecycle in depth.
-   [Warp Factories infrastructure and security](/factories/infrastructure-and-security/) - The same boundaries applied to factories.