diff --git a/src/assets/agent-platform/cloud-agent-run-lifecycle.png b/src/assets/agent-platform/cloud-agent-run-lifecycle.png new file mode 100644 index 000000000..165db95b3 Binary files /dev/null and b/src/assets/agent-platform/cloud-agent-run-lifecycle.png differ diff --git a/src/assets/agent-platform/cloud-agents-infra.png b/src/assets/agent-platform/cloud-agents-infra.png index b64a2063b..2d7412668 100644 Binary files a/src/assets/agent-platform/cloud-agents-infra.png and b/src/assets/agent-platform/cloud-agents-infra.png differ diff --git a/src/assets/agent-platform/customer-dedicated-saas.png b/src/assets/agent-platform/customer-dedicated-saas.png index 64ead3300..4fdc80d3d 100644 Binary files a/src/assets/agent-platform/customer-dedicated-saas.png and b/src/assets/agent-platform/customer-dedicated-saas.png differ diff --git a/src/assets/agent-platform/data-security-boundaries.png b/src/assets/agent-platform/data-security-boundaries.png new file mode 100644 index 000000000..521b6662a Binary files /dev/null and b/src/assets/agent-platform/data-security-boundaries.png differ diff --git a/src/assets/agent-platform/deployment-models.png b/src/assets/agent-platform/deployment-models.png new file mode 100644 index 000000000..b6d2abe94 Binary files /dev/null and b/src/assets/agent-platform/deployment-models.png differ diff --git a/src/assets/agent-platform/factories-work-item-flow.png b/src/assets/agent-platform/factories-work-item-flow.png new file mode 100644 index 000000000..49c7f1658 Binary files /dev/null and b/src/assets/agent-platform/factories-work-item-flow.png differ diff --git a/src/assets/agent-platform/self-hosted-execution-flow.png b/src/assets/agent-platform/self-hosted-execution-flow.png new file mode 100644 index 000000000..4fdc80d3d Binary files /dev/null and b/src/assets/agent-platform/self-hosted-execution-flow.png differ diff --git a/src/assets/agent-platform/self-hosted-network-egress.png b/src/assets/agent-platform/self-hosted-network-egress.png new file mode 100644 index 000000000..c423cebd3 Binary files /dev/null and b/src/assets/agent-platform/self-hosted-network-egress.png differ diff --git a/src/assets/agent-platform/self-hosted-run-sequence.png b/src/assets/agent-platform/self-hosted-run-sequence.png new file mode 100644 index 000000000..46790711e Binary files /dev/null and b/src/assets/agent-platform/self-hosted-run-sequence.png differ diff --git a/src/assets/agent-platform/warp-hosted-data-boundaries.png b/src/assets/agent-platform/warp-hosted-data-boundaries.png new file mode 100644 index 000000000..57e966c8b Binary files /dev/null and b/src/assets/agent-platform/warp-hosted-data-boundaries.png differ diff --git a/src/assets/agent-platform/warp-hosted-run-sequence.png b/src/assets/agent-platform/warp-hosted-run-sequence.png new file mode 100644 index 000000000..627559d1c Binary files /dev/null and b/src/assets/agent-platform/warp-hosted-run-sequence.png differ diff --git a/src/assets/agent-platform/warp-stack-overview.png b/src/assets/agent-platform/warp-stack-overview.png new file mode 100644 index 000000000..9bb3dc780 Binary files /dev/null and b/src/assets/agent-platform/warp-stack-overview.png differ diff --git a/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx b/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx index 1130480de..51af8d11b 100644 --- a/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx +++ b/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx @@ -19,7 +19,9 @@ Warp's cloud agent infrastructure has four key components: 3. **Execution** - Where the agent actually runs (Warp-hosted environment, your infrastructure, or your existing CI/orchestrator). 4. **Visibility** - How the team monitors and intervenes ({VARS.DASHBOARD}, session sharing, APIs/SDKs). -{/* TODO: Insert system architecture diagram once received from design team */} +![Warp stack overview diagram showing clients, the Warp control plane, Warp-hosted and customer-hosted execution planes, and external systems](../../../../assets/agent-platform/warp-stack-overview.png) + +The [stack overview](/platform/architecture/#stack-overview) reference describes each component in this diagram. ### High-level data flow @@ -136,6 +138,8 @@ Understanding what data stays where is critical for security and compliance deci Consider the following when selecting a deployment model: +![Deployment models diagram comparing Warp-hosted, managed self-hosted, and unmanaged self-hosted patterns by what runs on Warp versus customer infrastructure](../../../../assets/agent-platform/deployment-models.png) + **Warp-hosted** is right if: * You want zero infrastructure management for agent execution. * Your security team is comfortable with SOC 2 Type II certified, ZDR-covered infrastructure. @@ -152,6 +156,7 @@ Consider the following when selecting a deployment model: ## Related resources +* [Architecture reference](/platform/architecture/) - Diagrams of the stack, the run lifecycle, self-hosted execution, and data boundaries * [Deployment Patterns](/platform/deployment-patterns/) - Detailed patterns for CLI-only, {VARS.WARP_AUTOMATION_PLATFORM}-hosted, and self-hosted setups * [Security overview](/enterprise/security-and-compliance/security-overview/) - Data handling, encryption, and compliance details * [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) - Route inference through your own cloud infrastructure diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index 672e5a475..4e8bf1ac8 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -17,6 +17,10 @@ Deciding which repositories belong in this factory is a separate question. See [ A **work item** is a single request the factory acts on, such as an issue, support request, pull request, or Factory MCP task. It keeps its identity from intake to handoff, however many agents contribute to it along the way. +![Warp Factories system diagram showing work sources, automations, the foreman and stage agents, human handoff, the factory definition, platform execution, and the outer loop](../../../assets/agent-platform/factories-work-item-flow.png) + +The [Warp Factories work-item flow](/platform/architecture/#warp-factories-work-item-flow) reference explains each component in the diagram. + ## How a work item moves through the factory The foreman coordinates every work item. It routes work between the factory's agents, passes each one the context it needs, and continues existing agent conversations instead of starting new ones. See [factory agents](/factories/factory-agents/) for what each agent does. diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index c0b07368b..f065c02fe 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -29,6 +29,10 @@ flowchart LR 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. + +![Self-hosted data security and boundaries diagram showing what stays in customer infrastructure, what Warp retains, and what transits Warp to model providers](../../../assets/agent-platform/data-security-boundaries.png) + ## Runners A runner defines the compute a factory's agents work on: the operating system and architecture, the sandbox image, and the instance shape (vCPUs and memory). It's the infrastructure choice you make for a factory. The workspace itself — repositories, setup commands, and secrets — comes from the factory's [definition](/factories/factory-as-code/), and Warp keeps it in step for you. See the [runner reference](/platform/runners/) for the available compute options. diff --git a/src/content/docs/platform/architecture.mdx b/src/content/docs/platform/architecture.mdx new file mode 100644 index 000000000..0c79c11d9 --- /dev/null +++ b/src/content/docs/platform/architecture.mdx @@ -0,0 +1,121 @@ +--- +title: Architecture +description: >- + Reference diagrams of the Warp stack, the cloud agent run lifecycle, + self-hosted execution, factories, and data boundaries. +--- +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. + +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. + +## 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. + +![Warp stack overview diagram showing clients, the Warp control plane, Warp-hosted and customer-hosted execution planes, and external systems](../../../assets/agent-platform/warp-stack-overview.png) + +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/). +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. + +## 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 Warp 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. The numbers in the diagram match the steps below. + +![Cloud agent run lifecycle diagram showing triggers, the Warp control plane, the execution sandbox with its agent loop, LLM providers, and output targets](../../../assets/agent-platform/cloud-agent-run-lifecycle.png) + +1. **A trigger fires** - Work starts from a [schedule](/platform/triggers/scheduled-agents/), an [integration](/platform/integrations/) event such as a Slack mention or GitHub comment, an [API or SDK](/reference/api-and-sdk/) call, a CLI command like `oz agent run-cloud`, or a [Handoff](/platform/handoff/) from the Warp app. +2. **The task is created** - The control plane opens a run record that tracks the task's state, inputs, and provenance for its entire life. +3. **Configuration is resolved** - The platform determines the run's [environment](/platform/environments/), [runner](/platform/runners/) shape, execution host (Warp-hosted or a self-hosted worker), and [model and harness](/platform/harnesses/). +4. **The sandbox is provisioned** - The execution host prepares an isolated workspace on the runner's compute: it clones the environment's repositories with scoped repository credentials, runs setup commands, and injects only the [secrets](/platform/secrets/) the run is allowed to use. +5. **The agent loop runs** - The harness repeats a cycle until the task is done: gather context, call the model, and run tools (files, commands, MCP servers, and optionally [computer use](/agents/capabilities/computer-use/)). Every model call routes through Warp's inference routing to LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), with known secret values redacted in transit. Tool calls execute inside the sandbox, not on Warp's control plane. +6. **Outputs land at their targets** - The agent pushes branches and opens pull requests on your source control, and posts replies back 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, encrypted at rest. +8. **The team has visibility** - Anyone authorized can follow the run in the {VARS.DASHBOARD} or attach to it with [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor and steer while it's live. +9. **The sandbox tears down** - When the run ends, the platform captures a [workspace snapshot](/platform/handoff/snapshots/) so the work can be continued later — in the cloud or [handed off](/platform/handoff/) to a local session — and then destroys the sandbox. + +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 + +The same lifecycle as a request/response sequence between the trigger, the per-run sandbox, the Warp control plane, and providers: + +![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](../../../assets/agent-platform/warp-hosted-run-sequence.png) + +## Self-hosted execution flow + +Self-hosted execution keeps checkout, commands, and the sandbox filesystem on your infrastructure while the {VARS.WARP_AUTOMATION_PLATFORM} keeps orchestrating, observing, and routing inference. The split is a worker daemon that dials out to Warp — no inbound firewall ports — and executes tasks locally. The numbers in the diagram match the steps below. + +![Self-hosted execution architecture diagram showing the managed worker on customer infrastructure connecting outbound to the Warp control plane, with numbered flow steps](../../../assets/agent-platform/self-hosted-execution-flow.png) + +1. **The worker connects and waits for work** - You run the managed worker (the `oz-agent-worker` daemon) on your infrastructure. It authenticates to Warp 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 delivers the task** - When a Slack mention, Linear or Jira event, schedule, API call, or `oz agent run-cloud` command targets your worker, the control plane sends the task with its resolved configuration and scoped runtime credentials over that same encrypted connection. +3. **The task executes on your backend** - The worker prepares the workspace from the run's [environment](/platform/environments/) — cloning repositories from your source control, running setup, and injecting allowed [secrets](/platform/secrets/) — then 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 execution workspaces stay on your machines. +4. **Results stream back to the control plane** - Status, transcripts, artifacts, attachments, and telemetry flow to Warp for the run record. Content the agent puts into prompts, results, or transcripts can include code context, so review [security and networking](/platform/self-hosting/security-and-networking/) if that matters for your data classification. +5. **Inference routes through Warp** - The agent's model calls go from your worker to Warp's inference routing and on to LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), with known secret values redacted in transit. Enterprise teams can route inference through their own provider accounts with [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/). +6. **Your team watches from the usual surfaces** - Runs on self-hosted workers appear in the {VARS.DASHBOARD} and support [Agent Session Sharing](/agents/local-agents/session-sharing/), the same as Warp-hosted runs. + +### Self-hosted sequence view + +The same flow as a request/response sequence between your infrastructure, the Warp control plane, and providers: + +![Self-hosted run sequence diagram showing numbered request and response flows between the trigger, customer infrastructure, the Warp control plane, and providers](../../../assets/agent-platform/self-hosted-run-sequence.png) + +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 WebSocket, with resolved configuration and scoped runtime credentials. +3. **Prepare workspace** - The worker clones repositories with scoped credentials, 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** - Model calls route through Warp to LLM providers under ZDR with secrets redacted; [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) can route eligible calls through your own provider account instead. +6. **Run tools** - Tool calls execute locally: files, commands, internal services, and MCP servers. +7. **Results** - Transcripts, artifacts, and telemetry stream back to the run record. +8. **Outputs** - The agent pushes branches and opens pull requests on your source control. +9. **Observability** - Your team follows and steers the run from the dashboard and shared sessions; teardown captures a workspace snapshot for handoff. + +## Warp Factories work-item flow + +A software factory assembles the {VARS.WARP_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, control room, and outer loop](../../../assets/agent-platform/factories-work-item-flow.png) + +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. +2. **Automations** - Each provider event runs through [automations](/factories/automations/), whose filters decide which events start work and which agent handles them. Schedules fire automations on a timer; direct requests skip this step and go straight to the foreman. +3. **The foreman** - The factory's coordinator holds one continuous conversation per work item, decides which stage the work needs next, dispatches the right agent, relays questions to the requester, and pauses at human checkpoints. See [factory agents](/factories/factory-agents/). +4. **Stage agents** - Triage scopes the request and gathers evidence, Spec writes product and technical specifications in a draft pull request (a human approves the spec by default), Implement writes the code with tests and visual evidence, and Review checks the result with fresh eyes and returns an advisory verdict. Review can send work back to Implement for revision, and the foreman skips stages the work doesn't need. +5. **Human handoff** - The factory presents the finished pull request with its evidence and posts results back at the source. Agents never merge; your repository permissions and branch protection govern who does. +6. **The factory definition** - Version-controlled files — `factory.yaml` plus `agents/`, `automations/`, `runners/`, and `skills/` directories — define the whole factory. Definitions are Warp-managed or live in a GitHub repository your team owns, where changes arrive as reviewed pull requests. See [definitions as code](/factories/factory-as-code/). +7. **Platform execution** - Every stage runs as a cloud agent run: in a Warp-hosted sandbox or on a [self-hosted worker](/platform/self-hosting/), with the workspace from the factory's repositories and compute from its [runners](/platform/runners/). Each role can use its own model and [harness](/platform/harnesses/) — the Warp Agent, Claude Code, or Codex. +8. **The factory dashboard** - The Warp Factories web app (the control room in the diagram) shows the factory's metrics (autonomy, PR cycle time, cost per PR), work items by stage, runs, costs, and definition files. See the [factory dashboard](/factories/factory-dashboard/). +9. **The outer loop** - [Scorers](/factories/measure-and-improve/) judge completed work against your criteria, benchmarks compare model, harness, and runner configurations, and Self-improvement turns repeated failures into follow-up pull requests against the application code or the factory definition itself. Nothing is adopted without your review. + +## 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 the three zones involved: your infrastructure, the Warp platform, and model providers. 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 and clients in customer infrastructure, the per-run sandbox and control plane on the Warp platform, and model providers](../../../assets/agent-platform/warp-hosted-data-boundaries.png) + +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 additionally 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, configuration, and other control-plane state. +4. **Execution secrets** - [Managed secrets](/platform/secrets/) are stored encrypted and injected into the sandbox at runtime, scoped by allowlist to the runs that need them. [Secret redaction](/support-and-community/privacy-and-security/secret-redaction/) at output boundaries is a backstop, not a substitute for narrow scopes and rotation. +5. **Inference credentials** - Model provider keys are used only at the inference boundary and are never injected into sandboxes. With [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/), inference routes through your own provider account, so billing and provider-side retention follow your contract. +6. **Repository identity** - Agents check out and push with scoped repository credentials, and pull requests are attributed to the creating user or to the agent itself 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 holds orchestration, session data, run records, and inference routing, and an optional customer-owned bucket can hold an exported copy of run data. + +![Self-hosted data security and boundaries diagram showing what stays in customer infrastructure, what Warp retains, and what transits Warp to model providers](../../../assets/agent-platform/data-security-boundaries.png) + +## 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. diff --git a/src/content/docs/platform/deployment-patterns.mdx b/src/content/docs/platform/deployment-patterns.mdx index 8ee707406..136b61f1f 100644 --- a/src/content/docs/platform/deployment-patterns.mdx +++ b/src/content/docs/platform/deployment-patterns.mdx @@ -10,6 +10,8 @@ import { VARS } from '@data/vars'; Teams adopt cloud agents in a few repeatable ways. This page outlines the most common architectures, what they're good for, and how they fit together. +![Deployment models diagram comparing Warp-hosted, managed self-hosted, and unmanaged self-hosted patterns by what runs on Warp versus customer infrastructure](../../../assets/agent-platform/deployment-models.png) + ## Quick mental model Cloud agent setups usually have four moving parts: @@ -64,7 +66,9 @@ Use this when you already have a system that schedules work (CI, dev boxes, inte Use this when you want the {VARS.WARP_AUTOMATION_PLATFORM} to run agent workloads on Warp-managed infrastructure, typically inside reproducible Docker environments, with built-in lifecycle management. -![Warp enterprise SaaS architecture showing customer infrastructure, isolated tenant sandboxes, Warp backend, and LLM providers](../../../assets/agent-platform/cloud-agents-infra.png) +![Warp-hosted execution architecture showing customer infrastructure, triggers and integrations, isolated tenant sandboxes, the Warp control plane, and LLM providers](../../../assets/agent-platform/cloud-agents-infra.png) + +The [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-lifecycle) reference walks through this architecture step by step. ### What it looks like diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index 2e0fe0882..086d791b8 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -78,6 +78,7 @@ Runs pick up your team's shared setup no matter what triggered them: [MCP server ## Where to go next +* [Architecture](/platform/architecture/) - reference diagrams of the stack, the run lifecycle, and data boundaries. * [Cloud agents](/platform/) - what cloud agents are, how they get triggered, and how to run them with or without the Warp app. * [Cloud agents quickstart](/platform/quickstart/) - run your first cloud agent in about ten minutes. * [Environments](/platform/environments/) - define the toolchain and repos a run executes against. diff --git a/src/content/docs/platform/self-hosting/index.mdx b/src/content/docs/platform/self-hosting/index.mdx index df73af7ad..38bd5e5e7 100644 --- a/src/content/docs/platform/self-hosting/index.mdx +++ b/src/content/docs/platform/self-hosting/index.mdx @@ -34,7 +34,7 @@ Self-hosting has two architectures. The core distinction is **who orchestrates a | **Automatic environment setup** | Yes (via Warp [environments](/platform/environments/)) | No (you manage it) | | **Session tracking and steering** | Yes | Yes | -The two architectures are not mutually exclusive. Some teams run managed workers for integration-triggered work and unmanaged agents in CI pipelines. +The two architectures are not mutually exclusive. Some teams run managed workers for integration-triggered work and unmanaged agents in CI pipelines. The deployment models diagram on [Deployment patterns](/platform/deployment-patterns/) compares what runs where in each model. ## How self-hosting works @@ -42,7 +42,9 @@ Warp uses a split-plane architecture: **execution happens on your infrastructure If your security requirement is "repository clones and execution must stay on our infrastructure," self-hosting is designed for that. If your requirement is "no code context can ever route through Warp or an external LLM provider," review [Security and networking](/platform/self-hosting/security-and-networking/) with your Warp account team before deploying. -![Self-hosted Oz architecture showing customer-managed execution with Oz orchestration](../../../../assets/agent-platform/customer-dedicated-saas.png) +![Self-hosted execution architecture showing the managed worker on customer infrastructure connecting outbound to the Warp control plane](../../../../assets/agent-platform/customer-dedicated-saas.png) + +The [self-hosted execution flow](/platform/architecture/#self-hosted-execution-flow) reference explains each numbered step in the diagram. With any self-hosted architecture: diff --git a/src/content/docs/platform/self-hosting/security-and-networking.mdx b/src/content/docs/platform/self-hosting/security-and-networking.mdx index 5b22cef4a..cc6c2fd63 100644 --- a/src/content/docs/platform/self-hosting/security-and-networking.mdx +++ b/src/content/docs/platform/self-hosting/security-and-networking.mdx @@ -38,6 +38,8 @@ Repositories are cloned and stored only on your infrastructure, but code content Self-hosted agents **do not require any network ingress**. They require outbound (egress) access to the following services: +![Self-hosted worker network egress diagram showing outbound-only connections from customer infrastructure to Warp backend endpoints, Docker Hub, Google Cloud Storage, and GitHub](../../../../assets/agent-platform/self-hosted-network-egress.png) + **Warp's backend (all architectures):** * `app.warp.dev` — port 443 @@ -111,6 +113,7 @@ LLM inference routes through Warp's backend. With Warp-managed inference, reques ## Related pages * [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and architecture decision guide. +* [Data security and boundaries](/platform/architecture/#data-security-and-boundaries) — Diagrams of where each class of data lives and travels. * [Security overview](/enterprise/security-and-compliance/security-overview/) — Warp's broader security model, including ZDR. * [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) — Route inference through your own cloud provider accounts. * [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config schema, including every security-relevant option. diff --git a/src/sidebar.ts b/src/sidebar.ts index 3a1ebed4a..b36e94f08 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -623,6 +623,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // 'Warp-hosted agents' under its own opposite. label: 'Deployment & hosting', items: [ + { slug: 'platform/architecture', label: 'Architecture' }, { slug: 'platform/deployment-patterns', label: 'Deployment patterns' }, { slug: 'platform/warp-hosting', label: 'Warp-hosted agents' }, // Qualified: a bare 'Overview'/'Quickstart' would now read as the