docs: add an architecture reference page and embed the platform diagrams - #661
Open
hongyi-chen wants to merge 4 commits into
Open
docs: add an architecture reference page and embed the platform diagrams#661hongyi-chen wants to merge 4 commits into
hongyi-chen wants to merge 4 commits into
Conversation
Adds a Cloudflare-style Architecture section under the Platform topic with six pages, each pairing a reference diagram with numbered prose: overview, stack overview, cloud agent run lifecycle (with a Warp-hosted sequence view), self-hosted execution flow (with its sequence view), Warp Factories work-item flow, and data security and boundaries (Warp-hosted primary, self-hosted variant). Embeds the diagrams on the pages readers already visit: - Deployment patterns: deployment models comparison, plus a refreshed Warp-hosted architecture figure (replaces the stale export in place). - Self-hosting overview: refreshed self-hosted execution figure (replaces customer-dedicated-saas.png in place) with flow links. - Self-hosting security and networking: network egress diagram. - Factories: the work-item flow diagram on How factories work, and the self-hosted data boundaries diagram on Infrastructure and security. - Enterprise architecture and deployment: fills the system-architecture diagram TODO with the stack overview and adds the deployment models figure to the model-selection section. All internal links and anchors verified against the current factories IA (automations, factory dashboard); site builds cleanly. Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR adds a new architecture reference section with platform, lifecycle, self-hosted, factories, and data-boundary diagrams, and embeds those diagrams into related existing docs. The structure and sidebar updates are generally coherent, but one security-sensitive retention statement needs tightening before merge.
Concerns
- The new data-boundaries page says Warp does not persistently store source code while the same section explains that transcripts and artifacts persist and can include code context; that distinction needs to be explicit for security reviewers.
- No approved or repository spec context was available for this PR, so there were no spec commitments to validate against.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
|
|
||
| ## The data classes | ||
|
|
||
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store your source code or train on it. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Either way, code context the agent puts into prompts and transcripts still transits Warp. |
Contributor
There was a problem hiding this comment.
Suggested change
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store your source code or train on it. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Either way, code context the agent puts into prompts and transcripts still transits Warp. | |
| 1. **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, and the worker's connection to Warp is outbound-only. Code context the agent puts into prompts, transcripts, or artifacts still transits Warp and may persist as run data. |
![warp-factories[bot]](https://avatars.githubusercontent.com/in/2278701?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
Adds a six-page architecture reference suite and embeds the new diagrams across seven existing pages; CI (build, link-check, CodeQL) is green, the internal link/anchor audit is clean, and I visually verified all pages render correctly and legibly on the live Vercel preview. One factual inconsistency between prose and diagram is independently confirmed and should block merge; a design-invariant mismatch and a scope question are flagged for the author's judgment.
Concerns
- The "Run data" bullet on
data-security-boundaries.mdxsays the customer-owned bucket is used "instead" of Warp's store, but both accompanying diagrams (and the page's own "With self-hosted execution" section) state the bucket holds an "exported copy" while "Warp still retains the primary run record." See inline comment for a suggested fix. - Three of the six new pages (
stack-overview.mdx,factories-work-item-flow.mdx,data-security-boundaries.mdx) present numbered prose lists next to diagrams that carry no numeric markers at all — verified both from the source PNGs and by loading the live preview. This contradicts the PR description's claim that "each pairing a diagram with numbered prose that matches the numbers in the figure," andsrc/sidebar.ts's own new code comment ("each page pairs a numbered diagram with matching numbered prose sections"). Readers can't map a list item to a diagram element on these three pages.
Verdict
Checks: build pass, tests n/a (no test suite), CI green, visual proof present (verified via live Vercel preview at all three affected pages plus sidebar structure)
Found: 1 critical, 1 important, 1 suggestion/question (non-blocking, for author judgment), 0 nits
Recommendation: Request changes — the data-retention contradiction is an unambiguous fix; the diagram/prose numbering mismatch needs either updated diagrams or a list-format change. The internal-architecture-detail question does not block merge on its own.
|
|
||
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store your source code or train on it. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Either way, code context the agent puts into prompts and transcripts still transits Warp. | ||
| 2. **Prompts and context** - The agent's model calls route through Warp's inference routing 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, except for provider-specific models the ZDR terms don't cover. | ||
| 3. **Run data** - Transcripts, artifacts, run metadata, and costs persist in Warp's stores, encrypted at rest and access-controlled by your team's roles. Enterprise teams can keep the supported classes — transcripts, artifacts, and run attachments — in a customer-owned Amazon S3 or Google Cloud Storage bucket instead; configuration and other control-plane state stay with Warp. |
Contributor
There was a problem hiding this comment.
🚨 [CRITICAL] This says the customer-owned bucket is used "instead" of Warp's store, but both diagrams on this page (warp-hosted-data-boundaries.png and data-security-boundaries.png) label it "Optional customer-owned export" and state "An additional copy of run data writes to your bucket. Warp still retains the primary run record." The "With self-hosted execution" section below (line 24) agrees with the diagrams ("exported copy"), so only this bullet is wrong. This misstates a data-retention boundary that security reviewers rely on.
Suggested change
| 3. **Run data** - Transcripts, artifacts, run metadata, and costs persist in Warp's stores, encrypted at rest and access-controlled by your team's roles. Enterprise teams can keep the supported classes — transcripts, artifacts, and run attachments — in a customer-owned Amazon S3 or Google Cloud Storage bucket instead; configuration and other control-plane state stay with Warp. | |
| 3. **Run data** - Transcripts, artifacts, run metadata, and costs persist in Warp's stores, encrypted at rest and access-controlled by your team's roles. Enterprise teams can also export the supported classes — transcripts, artifacts, and run attachments — to a customer-owned Amazon S3 or Google Cloud Storage bucket; Warp retains the primary run record, and configuration and other control-plane state stay with Warp. |
|
|
||
| ## The data classes | ||
|
|
||
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store your source code or train on it. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Either way, code context the agent puts into prompts and transcripts still transits Warp. |
Contributor
There was a problem hiding this comment.
warp-hosted-data-boundaries.png above — confirmed on the live preview. The PR description states every page "pairs a diagram with numbered prose that matches the numbers in the figure," and src/sidebar.ts's new comment makes the same claim. Either add numbered callouts to the diagram or change this to a bulleted list.
|
|
||
| ## Components | ||
|
|
||
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the Warp Factories control room, and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. |
Contributor
There was a problem hiding this comment.
data-security-boundaries.mdx: this "Components" list is numbered 1–7, but warp-stack-overview.png has no numeric markers anywhere — confirmed on the live preview. This contradicts the PR description and src/sidebar.ts's new comment, both of which claim numbered diagrams matching numbered prose across the suite.
|
|
||
| ## How a factory runs | ||
|
|
||
| 1. **Work sources** - Work items arrive from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), from local coding agents through the [Factory MCP](/factories/factory-mcp/), or from direct runs and schedules. |
Contributor
There was a problem hiding this comment.
factories-work-item-flow.png has no numeric markers — confirmed on the live preview. Please reconcile all three affected pages (this one, stack-overview.mdx, data-security-boundaries.mdx) the same way, either by adding diagram callouts or dropping the numbering.
|
|
||
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the Warp Factories control room, and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. | ||
| 2. **APIs** - The control plane's entry points: a GraphQL API used by Warp's own clients, the REST [Agent API and SDKs](/reference/api-and-sdk/) for programmatic use, a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. | ||
| 3. **Control plane services** - The coordination layer. Agent orchestration owns run workflows and state; triggers evaluate [schedules](/platform/triggers/scheduled-agents/) and automations; identity and configuration manage teams, [secrets](/platform/secrets/), [environments](/platform/environments/), and [runners](/platform/runners/); inference routing brokers every model call; observability keeps run records and shared sessions; and the codebase index powers [Codebase Context](/agents/capabilities/codebase-context/) retrieval. |
Contributor
There was a problem hiding this comment.
💡 [SUGGESTION] This enumerates internal control-plane services (orchestration, identity/config, inference routing, observability, codebase index) in detail. AGENTS.md's "Document the user-visible model, not our architecture" guidance normally caps internal-component detail at one actionable sentence. This may be an intentional exception for this security/evaluation-focused suite (index.mdx states the pages exist to "answer security questions"), matching the precedent already set by the enterprise architecture-and-deployment.mdx page — flagging so a maintainer can confirm this is the intended scope rather than drift.
The stack overview described a previous revision of the diagram: it listed a GraphQL API, a data-stores layer (relational database, vector index, cache), and the codebase index, none of which appear in the current figure, and used the retired 'control room' name. Rewrote the components list to match the figure: three public entry points, control plane services including run data storage (with the optional customer-owned export), and external systems including compute providers. Data security and boundaries: customer-owned storage is an additional export copy, not a replacement — reworded to match the embedded figure. Tightened the cross-reference sentences added on deployment patterns, self-hosting, factories, and the enterprise page: removed restated benefits and doubled links, one purposeful link per pointer. Co-Authored-By: Warp <agent@warp.dev>
Per review feedback that six new pages was too much new IA surface: merge the architecture suite into one /platform/architecture/ page with anchored sections (stack overview, run lifecycle + sequence, self-hosted flow + sequence, factories work-item flow, data boundaries + self-hosted variant). The page keeps every diagram and numbered walkthrough; the per-page intros, duplicate related-pages lists, and the index page go away. Sidebar: the six-entry Architecture group becomes a single entry in Deployment & hosting. All cross-references on existing pages now point at section anchors. No redirects needed - the sub-pages were never published. Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
changed the title
hongyi-chen
dismissed
warp-factories[bot]’s stale review
August 31, 2026 21:53
Feedback addressed in later commits: 1949d23 reworded customer-owned storage as an additional export copy (Warp retains the primary run record) and simplified the control-plane enumeration; 021891d consolidated the suite and scoped the numbered-walkthrough claim to the two sections whose diagrams carry numeric markers.
rachaelrenk
reviewed
Sep 1, 2026
|  | ||
|  | ||
|
|
||
| The [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-lifecycle) reference walks through this architecture step by step. |
Contributor
There was a problem hiding this comment.
Suggested change
| The [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-lifecycle) reference walks through this architecture step by step. | |
| See the [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-lifecycle) reference for a description of each component in the architecture. |
rachaelrenk
reviewed
Sep 1, 2026
|
|
||
| Self-hosting moves only the execution plane: with a managed self-hosted worker, repository checkouts, command execution, and the sandbox filesystem stay on machines you control, but content that enters prompts, results, transcripts, attachments, artifacts, or telemetry still flows through Warp and the providers you configure. See [deployment patterns](/platform/deployment-patterns/) and [self-hosting security and networking](/platform/self-hosting/security-and-networking/) for the broader data model. | ||
|
|
||
| The diagram below maps those boundaries for self-hosted execution; factory runs follow the same data model. The [data security and boundaries](/platform/architecture/#data-security-and-boundaries) reference walks through each data class. |
Contributor
There was a problem hiding this comment.
Suggested change
| The diagram below maps those boundaries for self-hosted execution; factory runs follow the same data model. The [data security and boundaries](/platform/architecture/#data-security-and-boundaries) reference walks through each data class. | |
| The diagram below maps those boundaries for self-hosted execution; factory runs follow the same data model. See the [data security and boundaries](/platform/architecture/#data-security-and-boundaries) reference for a description of each data class. |
rachaelrenk
reviewed
Sep 1, 2026
|
|
||
|  | ||
|
|
||
| 1. **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store your source code or train on it. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure, and the worker's connection to Warp is outbound-only. Either way, code context the agent puts into prompts and transcripts still transits Warp. |
Contributor
There was a problem hiding this comment.
Not clear what the numbers in this list correspond to (there's no numbers in the diagram and no introduction in the preceding paragraph). Unless these correspond to steps of a workflow or something that needs numbers, reformat as a bulleted list.
rachaelrenk
reviewed
Sep 1, 2026
| --- | ||
| import { VARS } from '@data/vars'; | ||
|
|
||
| This page describes how the {VARS.WARP_AUTOMATION_PLATFORM} is put together and how data moves through it. Each section pairs a diagram with a numbered walkthrough. Use it to evaluate the platform, plan a deployment, or answer security questions. |
Contributor
There was a problem hiding this comment.
We don't need to describe the page formatting. Style guidance says to not introduce what the page does; just start describing the concept.
Suggested change
| This page describes how the {VARS.WARP_AUTOMATION_PLATFORM} is put together and how data moves through it. Each section pairs a diagram with a numbered walkthrough. Use it to evaluate the platform, plan a deployment, or answer security questions. | |
| The {VARS.WARP_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. |
rachaelrenk
reviewed
Sep 1, 2026
|
|
||
| This page describes how the {VARS.WARP_AUTOMATION_PLATFORM} is put together and how data moves through it. Each section pairs a diagram with a numbered walkthrough. Use it to evaluate the platform, plan a deployment, or answer security questions. | ||
|
|
||
| The diagrams describe the Warp-operated platform. Deployment choices such as [self-hosted execution](/platform/self-hosting/), [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/), and customer-owned storage move specific boundaries; each section notes where those options apply. |
Contributor
There was a problem hiding this comment.
Suggested change
| The diagrams describe the Warp-operated platform. Deployment choices such as [self-hosted execution](/platform/self-hosting/), [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/), and customer-owned storage move specific boundaries; each section notes where those options apply. |
rachaelrenk
reviewed
Sep 1, 2026
|
|
||
| ## Stack overview | ||
|
|
||
| The platform splits into a small number of layers: clients that people and programs use, a Warp-operated control plane that coordinates everything, execution planes where agents actually run, and the external systems agents read from and write to. |
Contributor
There was a problem hiding this comment.
Suggested change
| The platform splits into a small number of layers: clients that people and programs use, a Warp-operated control plane that coordinates everything, execution planes where agents actually run, and the external systems agents read from and write to. | |
| The platform has four layers: clients, the Warp-operated control plane that coordinates runs, the execution plane where agents access code and run tools, and external systems that agents read from and write to. |
rachaelrenk
reviewed
Sep 1, 2026
|
|
||
|  | ||
|
|
||
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the [factory dashboard](/factories/factory-dashboard/) (the control room in the diagram), and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. |
Contributor
There was a problem hiding this comment.
This numbered list should be a bulleted list. The numbers don't correspond to anything--this isn't steps in a workflow or procedure, and there's no numbers in the preceding diagram for this list to map to. If we want the list and diagram truly mapped, then we need to add numbers to the diagram.
rachaelrenk
reviewed
Sep 1, 2026
|
|
||
|  | ||
|
|
||
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the [factory dashboard](/factories/factory-dashboard/) (the control room in the diagram), and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. |
Contributor
There was a problem hiding this comment.
If the diagrams are revised to use "factory dashboard" instead of "control room" then we can remove the parenthetical explainer.
Suggested change
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the [factory dashboard](/factories/factory-dashboard/) (the control room in the diagram), and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. | |
| 1. **Clients** - The surfaces that start and observe work, like the Warp app, the {VARS.WARP_AGENT_CLI}, the web app, the [factory dashboard](/factories/factory-dashboard/) (the control room in the diagram), and clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. |
rachaelrenk
reviewed
Sep 1, 2026
|  | ||
|
|
||
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the [factory dashboard](/factories/factory-dashboard/) (the control room in the diagram), and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. | ||
| 2. **APIs** - The control plane's entry points: the REST [Agent API and SDKs](/reference/api-and-sdk/), a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. |
Contributor
There was a problem hiding this comment.
Suggested change
| 2. **APIs** - The control plane's entry points: the REST [Agent API and SDKs](/reference/api-and-sdk/), a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. | |
| 2. **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. |
rachaelrenk
reviewed
Sep 1, 2026
|
|
||
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the [factory dashboard](/factories/factory-dashboard/) (the control room in the diagram), and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. | ||
| 2. **APIs** - The control plane's entry points: the REST [Agent API and SDKs](/reference/api-and-sdk/), a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. | ||
| 3. **Control plane services** - The coordination layer. Agent orchestration owns run workflows and state; triggers evaluate [schedules](/platform/triggers/scheduled-agents/) and automations; identity and configuration manage teams, [secrets](/platform/secrets/), [environments](/platform/environments/), and [runners](/platform/runners/); inference routing brokers every model call; and run history, sessions, and costs keep every run observable. Run data — transcripts and selected outputs — is retained by Warp, with an optional export copy to customer-owned S3 or GCS on Enterprise plans. |
Contributor
There was a problem hiding this comment.
Almost all of this can go. The diagram already names the component categories, and the dedicated data-boundaries section should own retention details. These links also exist elsewhere in the page.
Suggested change
| 3. **Control plane services** - The coordination layer. Agent orchestration owns run workflows and state; triggers evaluate [schedules](/platform/triggers/scheduled-agents/) and automations; identity and configuration manage teams, [secrets](/platform/secrets/), [environments](/platform/environments/), and [runners](/platform/runners/); inference routing brokers every model call; and run history, sessions, and costs keep every run observable. Run data — transcripts and selected outputs — is retained by Warp, with an optional export copy to customer-owned S3 or GCS on Enterprise plans. | |
| 3. **Control plane** - Warp coordinates runs, manages shared configuration, routes model calls, and records run history. |
rachaelrenk
reviewed
Sep 1, 2026
| 1. **Clients** - The surfaces that start and observe work: the Warp app, the {VARS.WARP_AGENT_CLI}, the web app and cloud agent dashboard, the [factory dashboard](/factories/factory-dashboard/) (the control room in the diagram), and MCP clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. | ||
| 2. **APIs** - The control plane's entry points: the REST [Agent API and SDKs](/reference/api-and-sdk/), a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. | ||
| 3. **Control plane services** - The coordination layer. Agent orchestration owns run workflows and state; triggers evaluate [schedules](/platform/triggers/scheduled-agents/) and automations; identity and configuration manage teams, [secrets](/platform/secrets/), [environments](/platform/environments/), and [runners](/platform/runners/); inference routing brokers every model call; and run history, sessions, and costs keep every run observable. Run data — transcripts and selected outputs — is retained by Warp, with an optional export copy to customer-owned S3 or GCS on Enterprise plans. | ||
| 4. **Warp-hosted execution** - The default execution plane. Each cloud agent run gets an isolated, per-run sandbox provisioned on a runner's compute shape (OS, architecture, vCPUs, memory), with the workspace prepared from an environment. See [Warp-hosted execution](/platform/warp-hosting/). |
Contributor
There was a problem hiding this comment.
runner-compute detail belongs in runner reference
Suggested change
| 4. **Warp-hosted execution** - The default execution plane. Each cloud agent run gets an isolated, per-run sandbox provisioned on a runner's compute shape (OS, architecture, vCPUs, memory), with the workspace prepared from an environment. See [Warp-hosted execution](/platform/warp-hosting/). | |
| 4. **Warp-hosted execution** - By default, each cloud agent run gets an isolated sandbox prepared from its environment. See [Warp-hosted execution](/platform/warp-hosting/). |
rachaelrenk
reviewed
Sep 1, 2026
| 2. **APIs** - The control plane's entry points: the REST [Agent API and SDKs](/reference/api-and-sdk/), a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. | ||
| 3. **Control plane services** - The coordination layer. Agent orchestration owns run workflows and state; triggers evaluate [schedules](/platform/triggers/scheduled-agents/) and automations; identity and configuration manage teams, [secrets](/platform/secrets/), [environments](/platform/environments/), and [runners](/platform/runners/); inference routing brokers every model call; and run history, sessions, and costs keep every run observable. Run data — transcripts and selected outputs — is retained by Warp, with an optional export copy to customer-owned S3 or GCS on Enterprise plans. | ||
| 4. **Warp-hosted execution** - The default execution plane. Each cloud agent run gets an isolated, per-run sandbox provisioned on a runner's compute shape (OS, architecture, vCPUs, memory), with the workspace prepared from an environment. See [Warp-hosted execution](/platform/warp-hosting/). | ||
| 5. **Customer-hosted execution** - The Enterprise execution plane on your infrastructure. A managed worker (the `oz-agent-worker` daemon) connects outbound and executes tasks in Docker containers, Kubernetes Jobs, or directly on the host; unmanaged setups run the {VARS.WARP_AGENT_CLI} inside your own CI or orchestrator. See [Self-hosting](/platform/self-hosting/). |
Contributor
There was a problem hiding this comment.
Suggested change
| 5. **Customer-hosted execution** - The Enterprise execution plane on your infrastructure. A managed worker (the `oz-agent-worker` daemon) connects outbound and executes tasks in Docker containers, Kubernetes Jobs, or directly on the host; unmanaged setups run the {VARS.WARP_AGENT_CLI} inside your own CI or orchestrator. See [Self-hosting](/platform/self-hosting/). | |
| 5. **Self-hosted execution** - On Enterprise, a managed worker runs tasks on your infrastructure. Unmanaged setups run the {VARS.WARP_AGENT_CLI} in your CI or orchestrator. See [Self-hosting](/platform/self-hosting/). | |
rachaelrenk
reviewed
Sep 1, 2026
| 3. **Control plane services** - The coordination layer. Agent orchestration owns run workflows and state; triggers evaluate [schedules](/platform/triggers/scheduled-agents/) and automations; identity and configuration manage teams, [secrets](/platform/secrets/), [environments](/platform/environments/), and [runners](/platform/runners/); inference routing brokers every model call; and run history, sessions, and costs keep every run observable. Run data — transcripts and selected outputs — is retained by Warp, with an optional export copy to customer-owned S3 or GCS on Enterprise plans. | ||
| 4. **Warp-hosted execution** - The default execution plane. Each cloud agent run gets an isolated, per-run sandbox provisioned on a runner's compute shape (OS, architecture, vCPUs, memory), with the workspace prepared from an environment. See [Warp-hosted execution](/platform/warp-hosting/). | ||
| 5. **Customer-hosted execution** - The Enterprise execution plane on your infrastructure. A managed worker (the `oz-agent-worker` daemon) connects outbound and executes tasks in Docker containers, Kubernetes Jobs, or directly on the host; unmanaged setups run the {VARS.WARP_AGENT_CLI} inside your own CI or orchestrator. See [Self-hosting](/platform/self-hosting/). | ||
| 6. **External systems** - Everything the platform integrates with: your SSO or identity provider for authentication, source control (GitHub, GitLab, Bitbucket, Azure DevOps), integration providers (Slack, Linear, Jira), LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) (Anthropic, OpenAI, Google, xAI, Fireworks), embedding providers, the compute providers that host Warp-hosted sandboxes, and billing. |
Contributor
There was a problem hiding this comment.
Suggested change
| 6. **External systems** - Everything the platform integrates with: your SSO or identity provider for authentication, source control (GitHub, GitLab, Bitbucket, Azure DevOps), integration providers (Slack, Linear, Jira), LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) (Anthropic, OpenAI, Google, xAI, Fireworks), embedding providers, the compute providers that host Warp-hosted sandboxes, and billing. | |
| 6. **External systems** - The platform connects to identity providers, source control, integration providers, model providers, and billing systems. |
rachaelrenk
approved these changes
Sep 1, 2026
rachaelrenk
left a comment
rachaelrenk
left a comment
Contributor
There was a problem hiding this comment.
Approving to unblock!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an architecture reference page and embeds the new platform diagrams across the docs, replacing stale visuals where they existed.
New: Architecture page (Platform → Deployment & hosting)
One page at
/platform/architecture/with anchored sections, each pairing a diagram with a numbered walkthrough:Embeds on existing pages
cloud-agents-infra.png) replaced in place with the current Warp-hosted architecture render.customer-dedicated-saas.pngreplaced in place with the current self-hosted execution render, plus a link to the numbered flow reference.Notes
/factories/automations/,/factories/factory-dashboard/).npm run buildpasses; the sidebar gains a single "Architecture" entry in the Deployment & hosting group.Co-Authored-By: Warp agent@warp.dev