From 3ae3b29fac98fdc8e7f6bf2df517ad569b732698 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 11:18:30 -0600 Subject: [PATCH 01/46] docs: restructure factories documentation Co-Authored-By: Warp --- .../docs/agents/agent-memory/index.mdx | 4 +- .../capabilities/computer-use/index.mdx | 6 +- .../cli/oz-cli}/agent-profiles.mdx | 0 .../cli => agents/cli/oz-cli}/api-keys.mdx | 8 +- .../cli => agents/cli/oz-cli}/artifacts.mdx | 4 +- .../cli => agents/cli/oz-cli}/federate.mdx | 2 +- .../cli => agents/cli/oz-cli}/index.mdx | 36 +-- .../cli/oz-cli}/integration-setup.mdx | 10 +- .../cli => agents/cli/oz-cli}/mcp-servers.mdx | 2 +- .../cli => agents/cli/oz-cli}/quickstart.mdx | 18 +- .../cli => agents/cli/oz-cli}/skills.mdx | 0 .../cli/oz-cli}/troubleshooting.mdx | 14 +- .../cli => agents/cli/oz-cli}/warp-drive.mdx | 0 src/content/docs/agents/cli/quickstart.mdx | 2 +- src/content/docs/agents/cli/reference.mdx | 2 +- .../docs/agents/inference/model-choice.mdx | 2 +- src/content/docs/changelog/2025.mdx | 2 +- src/content/docs/changelog/2026.mdx | 2 +- .../enterprise-features/analytics-api.mdx | 6 +- .../architecture-and-deployment.mdx | 2 +- .../getting-started-enterprise.mdx | 2 +- .../team-management/admin-panel.mdx | 2 +- .../demo-sentry-monitoring-with-sdk.mdx | 0 .../api-and-sdk/index.mdx | 6 +- .../api-and-sdk/quickstart.mdx | 10 +- .../errors/agent-process-failed.mdx | 8 +- .../errors/authentication-required.mdx | 4 +- .../errors/budget-exceeded.mdx | 2 +- .../troubleshooting/errors/conflict.mdx | 4 +- .../errors/content-policy-violation.mdx | 2 +- .../errors/environment-setup-failed.mdx | 6 +- .../external-authentication-required.mdx | 6 +- .../errors/feature-not-available.mdx | 2 +- .../troubleshooting/errors/index.mdx | 40 ++-- .../errors/infrastructure-timeout.mdx | 4 +- .../errors/insufficient-credits.mdx | 2 +- .../errors/integration-disabled.mdx | 2 +- .../errors/integration-not-configured.mdx | 2 +- .../troubleshooting/errors/internal-error.mdx | 2 +- .../errors/invalid-request.mdx | 6 +- .../troubleshooting/errors/not-authorized.mdx | 4 +- .../errors/operation-not-supported.mdx | 6 +- .../errors/resource-not-found.mdx | 2 +- .../errors/resource-unavailable.mdx | 6 +- .../api-and-sdk/troubleshooting/index.mdx | 2 +- .../deployment-patterns.mdx | 6 +- .../docs/factories/developer-tools.mdx | 32 +++ src/content/docs/factories/factory-api.mdx | 6 +- .../docs/factories/factory-as-code.mdx | 4 +- src/content/docs/factories/factory-mcp.mdx | 2 +- src/content/docs/factories/index.mdx | 2 +- .../factories/infrastructure-and-security.mdx | 22 +- .../docs/{platform => factories}/runners.mdx | 6 +- .../docs/factories/self-hosting/index.mdx | 55 +++++ .../self-hosting/managed-direct.mdx | 20 +- .../self-hosting/managed-docker.mdx | 20 +- .../self-hosting/managed-kubernetes.mdx | 24 +- .../self-hosting/monitoring.mdx | 12 +- .../self-hosting/quickstart.mdx | 18 +- .../self-hosting/reference.mdx | 22 +- .../self-hosting/troubleshooting.mdx | 16 +- .../{platform => factories}/warp-hosting.mdx | 2 +- .../agent-workflows/build-a-triage-agent.mdx | 4 +- .../how-to-run-unattended-agents.mdx | 8 +- .../run-a-software-factory-in-the-cloud.mdx | 8 +- ...ld-a-mattermost-bot-for-warp-factories.mdx | 6 +- .../using-mcp-servers-with-warp.mdx | 6 +- src/content/docs/index.mdx | 131 ++-------- src/content/docs/platform/agents.mdx | 16 +- src/content/docs/platform/environments.mdx | 8 +- .../environments/configuring-environments.mdx | 2 +- .../troubleshooting-environments.mdx | 6 +- ...-networking.mdx => execution-security.mdx} | 6 +- src/content/docs/platform/faqs.mdx | 12 +- .../docs/platform/handoff/snapshots.mdx | 10 +- .../docs/platform/harnesses/claude-code.mdx | 2 +- src/content/docs/platform/harnesses/codex.mdx | 2 +- src/content/docs/platform/harnesses/index.mdx | 2 +- .../docs/platform/harnesses/warp-agent.mdx | 2 +- src/content/docs/platform/index.mdx | 16 +- .../platform/integrations/azure-devops.mdx | 2 +- .../docs/platform/integrations/bitbucket.mdx | 2 +- .../platform/integrations/cloud-providers.mdx | 2 +- .../platform/integrations/github-actions.mdx | 4 +- .../docs/platform/integrations/github.mdx | 6 +- .../docs/platform/integrations/index.mdx | 2 +- .../docs/platform/integrations/jira.mdx | 2 +- .../docs/platform/integrations/linear.mdx | 10 +- .../quickstart-github-actions.mdx | 2 +- .../docs/platform/integrations/quickstart.mdx | 6 +- .../docs/platform/integrations/slack.mdx | 10 +- .../docs/platform/managing-cloud-agents.mdx | 6 +- src/content/docs/platform/mcp.mdx | 4 +- .../docs/platform/orchestration/index.mdx | 10 +- .../orchestration/multi-agent-runs.mdx | 10 +- src/content/docs/platform/overview.mdx | 14 +- src/content/docs/platform/oz-web-app.mdx | 8 +- src/content/docs/platform/quickstart.mdx | 10 +- src/content/docs/platform/secrets.mdx | 2 +- .../docs/platform/self-hosting/index.mdx | 226 ------------------ .../docs/platform/skills-as-agents.mdx | 10 +- .../team-access-billing-and-identity.mdx | 12 +- src/content/docs/platform/triggers/index.mdx | 4 +- .../platform/triggers/scheduled-agents.mdx | 6 +- .../unmanaged.mdx => unmanaged-execution.mdx} | 14 +- .../platform/viewing-cloud-agent-runs.mdx | 4 +- src/content/docs/reference/index.mdx | 26 -- .../plans-and-billing/pricing-faqs.mdx | 2 +- src/sidebar.ts | 148 +++--------- vercel.json | 85 +++++++ 110 files changed, 593 insertions(+), 826 deletions(-) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/agent-profiles.mdx (100%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/api-keys.mdx (95%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/artifacts.mdx (95%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/federate.mdx (97%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/index.mdx (94%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/integration-setup.mdx (96%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/mcp-servers.mdx (99%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/quickstart.mdx (77%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/skills.mdx (100%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/troubleshooting.mdx (92%) rename src/content/docs/{reference/cli => agents/cli/oz-cli}/warp-drive.mdx (100%) rename src/content/docs/{reference => factories}/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx (100%) rename src/content/docs/{reference => factories}/api-and-sdk/index.mdx (93%) rename src/content/docs/{reference => factories}/api-and-sdk/quickstart.mdx (92%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx (89%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/authentication-required.mdx (92%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx (95%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/conflict.mdx (91%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx (96%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx (92%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx (95%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/feature-not-available.mdx (96%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/index.mdx (77%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx (94%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx (98%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/integration-disabled.mdx (95%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx (96%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/internal-error.mdx (96%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/invalid-request.mdx (89%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/not-authorized.mdx (92%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx (88%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/resource-not-found.mdx (96%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx (90%) rename src/content/docs/{reference => factories}/api-and-sdk/troubleshooting/index.mdx (90%) rename src/content/docs/{platform => factories}/deployment-patterns.mdx (92%) create mode 100644 src/content/docs/factories/developer-tools.mdx rename src/content/docs/{platform => factories}/runners.mdx (94%) create mode 100644 src/content/docs/factories/self-hosting/index.mdx rename src/content/docs/{platform => factories}/self-hosting/managed-direct.mdx (77%) rename src/content/docs/{platform => factories}/self-hosting/managed-docker.mdx (84%) rename src/content/docs/{platform => factories}/self-hosting/managed-kubernetes.mdx (86%) rename src/content/docs/{platform => factories}/self-hosting/monitoring.mdx (92%) rename src/content/docs/{platform => factories}/self-hosting/quickstart.mdx (73%) rename src/content/docs/{platform => factories}/self-hosting/reference.mdx (83%) rename src/content/docs/{platform => factories}/self-hosting/troubleshooting.mdx (86%) rename src/content/docs/{platform => factories}/warp-hosting.mdx (94%) rename src/content/docs/platform/{self-hosting/security-and-networking.mdx => execution-security.mdx} (94%) delete mode 100644 src/content/docs/platform/self-hosting/index.mdx rename src/content/docs/platform/{self-hosting/unmanaged.mdx => unmanaged-execution.mdx} (89%) delete mode 100644 src/content/docs/reference/index.mdx diff --git a/src/content/docs/agents/agent-memory/index.mdx b/src/content/docs/agents/agent-memory/index.mdx index 76227aaf6..1f63001e3 100644 --- a/src/content/docs/agents/agent-memory/index.mdx +++ b/src/content/docs/agents/agent-memory/index.mdx @@ -85,8 +85,8 @@ Attach stores to agents with read-only or read-write access. Each attachment inc These capabilities aren't part of the research preview yet, but they're on the way: -* **Programmatic API access** - Read and manage memories and stores through the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), in addition to managing them in the {VARS.WEB_APP}. -* **Self-hosting support** - Run Agent Memory on a [self-hosted {VARS.WARP_AUTOMATION_PLATFORM}](/platform/self-hosting/) instance to meet security, privacy, and compliance requirements. +* **Programmatic API access** - Read and manage memories and stores through the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/), in addition to managing them in the {VARS.WEB_APP}. +* **Self-hosting support** - Run Agent Memory on a [self-hosted {VARS.WARP_AUTOMATION_PLATFORM}](/factories/self-hosting/) instance to meet security, privacy, and compliance requirements. ## Join the waitlist diff --git a/src/content/docs/agents/capabilities/computer-use/index.mdx b/src/content/docs/agents/capabilities/computer-use/index.mdx index 3cbd73ae2..4f3a915be 100644 --- a/src/content/docs/agents/capabilities/computer-use/index.mdx +++ b/src/content/docs/agents/capabilities/computer-use/index.mdx @@ -44,7 +44,7 @@ Runs started from the Warp app don't use the server default: they always follow ### CLI -When running cloud agents with the [{VARS.WARP_AGENT_CLI}](/reference/cli/), use flags to control Computer Use per run: +When running cloud agents with the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), use flags to control Computer Use per run: ```bash oz agent run-cloud --computer-use --prompt "" @@ -53,7 +53,7 @@ oz agent run-cloud --no-computer-use --prompt "" ### API -When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp's built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run: +When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp's built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run: ```json { @@ -65,7 +65,7 @@ When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/reference/api-an } ``` -For full API documentation, see the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) reference. +For full API documentation, see the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) reference. ### Web app diff --git a/src/content/docs/reference/cli/agent-profiles.mdx b/src/content/docs/agents/cli/oz-cli/agent-profiles.mdx similarity index 100% rename from src/content/docs/reference/cli/agent-profiles.mdx rename to src/content/docs/agents/cli/oz-cli/agent-profiles.mdx diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/agents/cli/oz-cli/api-keys.mdx similarity index 95% rename from src/content/docs/reference/cli/api-keys.mdx rename to src/content/docs/agents/cli/oz-cli/api-keys.mdx index 6e3862617..240b02a53 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/agents/cli/oz-cli/api-keys.mdx @@ -46,7 +46,7 @@ You can create an API key in either the -![API key management interface in Warp settings](../../../../assets/reference/api-key-management.png) +![API key management interface in Warp settings](../../../../../assets/reference/api-key-management.png)
API key management interface in Warp settings.
@@ -86,7 +86,7 @@ $ oz agent run --api-key "wk-xxx..." --prompt "analyze this codebase" ``` :::note -API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be [invalid or from an older format](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be [invalid or from an older format](/factories/api-and-sdk/troubleshooting/errors/authentication-required/). ::: ## Managing API keys @@ -107,11 +107,11 @@ The Warp app also shows additional metadata that isn't surfaced in the {VARS.WEB To delete an API key, find it in either the {VARS.WEB_APP} or the Warp app's API Keys list and click the delete icon next to the key. -Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access and may return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access and may return an [`authentication_required` error](/factories/api-and-sdk/troubleshooting/errors/authentication-required/). ## Manage API keys from the CLI -In addition to the web and Warp app surfaces, you can manage API keys directly with the [{VARS.WARP_AGENT_CLI}](/reference/cli/). These commands are useful for scripting key rotation and for headless environments. +In addition to the web and Warp app surfaces, you can manage API keys directly with the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/). These commands are useful for scripting key rotation and for headless environments. ### List keys diff --git a/src/content/docs/reference/cli/artifacts.mdx b/src/content/docs/agents/cli/oz-cli/artifacts.mdx similarity index 95% rename from src/content/docs/reference/cli/artifacts.mdx rename to src/content/docs/agents/cli/oz-cli/artifacts.mdx index de7bb6f6d..7d36ce629 100644 --- a/src/content/docs/reference/cli/artifacts.mdx +++ b/src/content/docs/agents/cli/oz-cli/artifacts.mdx @@ -22,7 +22,7 @@ Use artifacts when you need to retrieve files an agent produced after a run comp * **Local inspection** - Pull a generated file (HTML, image, CSV) onto your laptop to review. * **CI integration** - Fetch an agent-produced build artifact from a pipeline step that runs after the agent finishes. -Artifacts are referenced by an artifact UID. You can find UIDs in the agent's run detail view, in the JSON returned by [`oz run get`](/reference/cli/), or in the response from the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). +Artifacts are referenced by an artifact UID. You can find UIDs in the agent's run detail view, in the JSON returned by [`oz run get`](/agents/cli/oz-cli/), or in the response from the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/). ## `oz artifact get` @@ -78,5 +78,5 @@ oz artifact download "$ARTIFACT_UID" --out ./latest-report.html ## Related -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - retrieve artifacts programmatically over HTTP. +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - retrieve artifacts programmatically over HTTP. * [Scheduled cloud agents](/platform/triggers/scheduled-agents/) - common producer of recurring artifacts that downstream tooling consumes. diff --git a/src/content/docs/reference/cli/federate.mdx b/src/content/docs/agents/cli/oz-cli/federate.mdx similarity index 97% rename from src/content/docs/reference/cli/federate.mdx rename to src/content/docs/agents/cli/oz-cli/federate.mdx index a2bda5c55..03da8aaa7 100644 --- a/src/content/docs/reference/cli/federate.mdx +++ b/src/content/docs/agents/cli/oz-cli/federate.mdx @@ -94,7 +94,7 @@ A typical AWS flow: A typical GCP flow: 1. Run `oz federate issue-token` to get the OIDC JWT. -2. Call the [Security Token Service `token` endpoint](https://cloud.google.com/iam/docs/reference/sts/rest/v1/TopLevel/token) to exchange the JWT for a federated access token. +2. Call the [Security Token Service `token` endpoint](https://cloud.google.com/iam/docs/factories/developer-tools/sts/rest/v1/TopLevel/token) to exchange the JWT for a federated access token. 3. Optionally impersonate a service account for the final credentials. ## Related diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/agents/cli/oz-cli/index.mdx similarity index 94% rename from src/content/docs/reference/cli/index.mdx rename to src/content/docs/agents/cli/oz-cli/index.mdx index e301e9259..f58f2c61b 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/agents/cli/oz-cli/index.mdx @@ -18,7 +18,7 @@ The {VARS.WARP_AGENT_CLI} is the command-line tool for running and managing Warp The {VARS.WARP_AGENT_CLI} is the command-line tool that lets you run [Cloud Agents](/platform/) from anywhere, including terminals, scripts, automated systems, or services. -It's the standard runtime entry point that turns a **prompt** plus **configuration** into an **executable agent task** that runs on either a **Warp-hosted or [self-hosted](/platform/self-hosting/) runner**. +It's the standard runtime entry point that turns a **prompt** plus **configuration** into an **executable agent task** that runs on either a **Warp-hosted or [self-hosted](/factories/self-hosting/) runner**. With the {VARS.WARP_AGENT_CLI}, you can: @@ -189,7 +189,7 @@ If you weren't logged in, the command prints `You are not logged in.` and exits. Use an API key when the environment must authenticate on its own, such as CI pipelines, headless servers, VMs, Codespaces, or containers. API keys let the CLI authenticate non-interactively. -For detailed instructions on creating, managing, and using API keys, see [API Keys](/reference/cli/api-keys/). +For detailed instructions on creating, managing, and using API keys, see [API Keys](/agents/cli/oz-cli/api-keys/). **Quickstart:** @@ -230,10 +230,10 @@ oz agent run --prompt "set up a new Rust crate named warp-cli" * `--cwd ` (`-C`) — run from a different directory. * `--name ` (`-n`) — label the run for grouping and traceability. -* `--share` — share the session with teammates (see [Collaboration](/reference/cli/#collaboration)). -* `--profile ` — use a specific agent profile (see [Using Agent Profiles](/reference/cli/#using-agent-profiles)). +* `--share` — share the session with teammates (see [Collaboration](/agents/cli/oz-cli/#collaboration)). +* `--profile ` — use a specific agent profile (see [Using Agent Profiles](/agents/cli/oz-cli/#using-agent-profiles)). * `--model ` — override the default model (see [Model Choice](/agents/inference/model-choice/)). -* `--skill ` — use a skill as the base prompt (see [Using Skills](/reference/cli/#using-skills)). +* `--skill ` — use a skill as the base prompt (see [Using Skills](/agents/cli/oz-cli/#using-skills)). * `--mcp ` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated. * `--environment ` (`-e`) — run in a specific cloud environment. * `--file ` (`-f`) — load run configuration from a YAML or JSON file. @@ -263,13 +263,13 @@ oz agent run-cloud \ * `--environment ` (`-e`) — select the environment to run in. * `--no-environment` — run without an environment (not recommended). * `--open` — view the agent's session in Warp once it's available. -* `--name ` (`-n`) — label the run for grouping and traceability (see [Naming runs](/reference/cli/#naming-runs) below). -* `--title ` — set the title shown for the run and its conversation (see [Titling runs](/reference/cli/#titling-runs) below). -* `--parent-run-id <RUN_ID>` — start the run as an orchestration child of an existing run (see [Starting a run as an orchestration child](/reference/cli/#starting-a-run-as-an-orchestration-child) below). -* `--agent <UID>` — run as a saved [named agent](/platform/agents/), applying its configuration (skills, secrets, base model, and default environment) and attributing credit usage to it (see [Managing named agents](/reference/cli/#managing-named-agents) below). +* `--name <NAME>` (`-n`) — label the run for grouping and traceability (see [Naming runs](/agents/cli/oz-cli/#naming-runs) below). +* `--title <TITLE>` — set the title shown for the run and its conversation (see [Titling runs](/agents/cli/oz-cli/#titling-runs) below). +* `--parent-run-id <RUN_ID>` — start the run as an orchestration child of an existing run (see [Starting a run as an orchestration child](/agents/cli/oz-cli/#starting-a-run-as-an-orchestration-child) below). +* `--agent <UID>` — run as a saved [named agent](/platform/agents/), applying its configuration (skills, secrets, base model, and default environment) and attributing credit usage to it (see [Managing named agents](/agents/cli/oz-cli/#managing-named-agents) below). * `--mcp <SPEC>` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated. * `--model <MODEL_ID>` — override the default model. -* `--skill <SPEC>` — use a skill from the environment's repository as the base prompt (see [Using Skills](/reference/cli/#using-skills)). +* `--skill <SPEC>` — use a skill from the environment's repository as the base prompt (see [Using Skills](/agents/cli/oz-cli/#using-skills)). * `--host <WORKER_ID>` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. * `--attach <PATH>` — attach an image file to the agent query. Can be repeated (maximum 5). * `--computer-use` / `--no-computer-use` — enable or disable [Computer Use](/agents/capabilities/computer-use/) for this run. @@ -306,7 +306,7 @@ The `--name` flag assigns a config name to the run. Use it to group related runs **Why naming matters:** -When your team runs many agents across schedules, integrations, and ad-hoc triggers, `name` lets you answer questions like "how many distinct workflows are we running?" and "how often does this particular workflow run?" You can filter runs by name using the `name` query parameter on `GET /agent/runs` in the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). +When your team runs many agents across schedules, integrations, and ad-hoc triggers, `name` lets you answer questions like "how many distinct workflows are we running?" and "how often does this particular workflow run?" You can filter runs by name using the `name` query parameter on `GET /agent/runs` in the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/). **Examples:** @@ -359,7 +359,7 @@ Pass the run ID of the run doing the spawning. Omit the flag for ordinary standa #### Reusing saved prompts and Warp Drive objects -You can reuse saved prompts with `--saved-prompt`, and reference notebooks, workflows, and rules inline in any `--prompt` string. See [Referencing Warp Drive objects](/reference/cli/warp-drive/) for details. +You can reuse saved prompts with `--saved-prompt`, and reference notebooks, workflows, and rules inline in any `--prompt` string. See [Referencing Warp Drive objects](/agents/cli/oz-cli/warp-drive/) for details. #### Choosing an execution harness @@ -379,19 +379,19 @@ Create the auth secret first with `oz secret create claude api-key <SECRET_NAME> Agent profiles control what the agent can do, how it behaves, and where it can act. Use the `--profile` flag with `oz agent run` to apply a specific profile. -See [Agent profiles](/reference/cli/agent-profiles/) for how to find profile IDs and apply them. +See [Agent profiles](/agents/cli/oz-cli/agent-profiles/) for how to find profile IDs and apply them. ## Using MCP servers MCP servers connect agents to external systems like GitHub, Linear, or Sentry. Use the `--mcp` flag with any of three formats: a Warp MCP server UUID, inline JSON, or a path to a JSON config file. -See [MCP Servers](/reference/cli/mcp-servers/) for full details, including how to find UUIDs, combine multiple servers, and handle environment variables on remote machines. +See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) for full details, including how to find UUIDs, combine multiple servers, and handle environment variables on remote machines. ## Using skills [Skills](/agents/capabilities/skills/) are reusable instruction sets that teach agents how to perform specific tasks. Use the `--skill` flag to run an agent from a skill stored in a repository. -See [Skills](/reference/cli/skills/) for supported spec formats and examples for both local and cloud agent runs. +See [Skills](/agents/cli/oz-cli/skills/) for supported spec formats and examples for both local and cloud agent runs. ## Collaboration @@ -557,14 +557,14 @@ oz environment image list ### `oz artifact get` / `oz artifact download` -Inspect and retrieve files an agent produced during a run. See [Artifacts](/reference/cli/artifacts/) for details. +Inspect and retrieve files an agent produced during a run. See [Artifacts](/agents/cli/oz-cli/artifacts/) for details. ### `oz federate issue-token` -Issue a short-lived OIDC identity token from inside a running agent to authenticate to cloud providers without long-lived credentials. See [Federated identity tokens](/reference/cli/federate/) for details. +Issue a short-lived OIDC identity token from inside a running agent to authenticate to cloud providers without long-lived credentials. See [Federated identity tokens](/agents/cli/oz-cli/federate/) for details. --- ## Troubleshooting -For built-in CLI help commands and solutions to common errors — including authentication issues, agent failures, environment problems, and Docker image issues — see [Troubleshooting](/reference/cli/troubleshooting/). +For built-in CLI help commands and solutions to common errors — including authentication issues, agent failures, environment problems, and Docker image issues — see [Troubleshooting](/agents/cli/oz-cli/troubleshooting/). diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/agents/cli/oz-cli/integration-setup.mdx similarity index 96% rename from src/content/docs/reference/cli/integration-setup.mdx rename to src/content/docs/agents/cli/oz-cli/integration-setup.mdx index e158952da..5cc68e8e6 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/agents/cli/oz-cli/integration-setup.mdx @@ -60,9 +60,9 @@ Setting up an integration consists of three steps. :::tip If setup fails, use the returned error code to narrow the fix. Common errors include: -* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) (environment initialization issues) -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or external-service authorization) -* [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) (incomplete integration setup) +* [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) (environment initialization issues) +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or external-service authorization) +* [`integration_not_configured`](/factories/api-and-sdk/troubleshooting/errors/integration-not-configured/) (incomplete integration setup) ::: --- @@ -191,7 +191,7 @@ You typically only need to handle this once per team, unless your repo access ch #### Team-level GitHub authorization -For automated workflows that use an [agent API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Warp Factories GitHub App instead of an individual's personal token. +For automated workflows that use an [agent API key](/agents/cli/oz-cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Warp Factories GitHub App instead of an individual's personal token. This requires a Warp team admin to enable the GitHub organization in the Admin Panel (**Settings** > **Admin Panel** > **Platform**). Once configured, tasks initiated with an agent API key can clone repos and open pull requests using the GitHub App installation token. @@ -309,4 +309,4 @@ You now have everything needed to trigger agents from your team's tools. From he * [Cloud Agents Overview](/platform/) * [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) * [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), [GitHub](/platform/integrations/github/), and [GitHub Actions](/platform/integrations/github-actions/) integrations -* [Troubleshooting](/reference/cli/troubleshooting/) +* [Troubleshooting](/agents/cli/oz-cli/troubleshooting/) diff --git a/src/content/docs/reference/cli/mcp-servers.mdx b/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx similarity index 99% rename from src/content/docs/reference/cli/mcp-servers.mdx rename to src/content/docs/agents/cli/oz-cli/mcp-servers.mdx index 4e32feca0..6b109e612 100644 --- a/src/content/docs/reference/cli/mcp-servers.mdx +++ b/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx @@ -49,7 +49,7 @@ $ oz mcp list Alternatively, copy the UUID from Warp in **Settings** > **Agents** > **MCP servers**. <figure style={{ maxWidth: "375px" }}> -![MCP servers page, showing a server with its UUID](../../../../assets/reference/mcp-server-id.png) +![MCP servers page, showing a server with its UUID](../../../../../assets/reference/mcp-server-id.png) <figcaption>MCP servers page, showing a server with its UUID.</figcaption> </figure> diff --git a/src/content/docs/reference/cli/quickstart.mdx b/src/content/docs/agents/cli/oz-cli/quickstart.mdx similarity index 77% rename from src/content/docs/reference/cli/quickstart.mdx rename to src/content/docs/agents/cli/oz-cli/quickstart.mdx index 2303b2535..3198f28c1 100644 --- a/src/content/docs/reference/cli/quickstart.mdx +++ b/src/content/docs/agents/cli/oz-cli/quickstart.mdx @@ -21,7 +21,7 @@ Watch this short demo of the {VARS.WARP_AGENT_CLI} workflow: If you already have the [Warp desktop app installed](/getting-started/quickstart/installation-and-setup/), the **CLI is included** and available in Warp. -If not, see [Installing the CLI](/reference/cli/#installing-the-cli) for installation options for all platforms. +If not, see [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli) for installation options for all platforms. ## 2. Authenticate @@ -44,7 +44,7 @@ Interactive login works on both **local** and **remote** machines, and does not export WARP_API_KEY="wk-..." ``` -Create an API key in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. See [API Keys](/reference/cli/api-keys/) for guidance on personal vs. [agent keys](/platform/agents/) and on security best practices. +Create an API key in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. See [API Keys](/agents/cli/oz-cli/api-keys/) for guidance on personal vs. [agent keys](/platform/agents/) and on security best practices. ::: ## 3. Run an agent @@ -83,17 +83,17 @@ You can connect MCP servers to give the agent access to external tools like GitH oz agent run --mcp '{"github": {"url": "https://api.githubcopilot.com/mcp/"}}' --prompt "Open a pull request that fixes TODOs in this repo" ``` -See [MCP Servers](/reference/cli/mcp-servers/) for all supported formats, including UUID references and multi-server configurations. +See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) for all supported formats, including UUID references and multi-server configurations. ## Next steps Once you've successfully set up and run your agent, explore other configurations and workflows with the {VARS.WARP_AGENT_CLI}: -* Customize behavior with [agent profiles](/reference/cli/agent-profiles/). -* [Reuse prompts](/reference/cli/warp-drive/) with `--saved-prompt`. -* Connect agents to external systems using [MCP Servers](/reference/cli/mcp-servers/). -* Authenticate with [API keys](/reference/cli/api-keys/) for automated environments or workflows. -* Get up-to-date information about the {VARS.WARP_AGENT_CLI} using the [`oz help` command](/reference/cli/troubleshooting/#getting-help). +* Customize behavior with [agent profiles](/agents/cli/oz-cli/agent-profiles/). +* [Reuse prompts](/agents/cli/oz-cli/warp-drive/) with `--saved-prompt`. +* Connect agents to external systems using [MCP Servers](/agents/cli/oz-cli/mcp-servers/). +* Authenticate with [API keys](/agents/cli/oz-cli/api-keys/) for automated environments or workflows. +* Get up-to-date information about the {VARS.WARP_AGENT_CLI} using the [`oz help` command](/agents/cli/oz-cli/troubleshooting/#getting-help). * Run agents in CI with the [GitHub Actions quickstart](/platform/integrations/quickstart-github-actions/). -Continue reading the [{VARS.WARP_AGENT_CLI} reference](/reference/cli/) to learn how to install the CLI on different platforms, authenticate in different environments, and configure agents for real-world workflows. +Continue reading the [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/) to learn how to install the CLI on different platforms, authenticate in different environments, and configure agents for real-world workflows. diff --git a/src/content/docs/reference/cli/skills.mdx b/src/content/docs/agents/cli/oz-cli/skills.mdx similarity index 100% rename from src/content/docs/reference/cli/skills.mdx rename to src/content/docs/agents/cli/oz-cli/skills.mdx diff --git a/src/content/docs/reference/cli/troubleshooting.mdx b/src/content/docs/agents/cli/oz-cli/troubleshooting.mdx similarity index 92% rename from src/content/docs/reference/cli/troubleshooting.mdx rename to src/content/docs/agents/cli/oz-cli/troubleshooting.mdx index 3fa5130a0..1d0cbac60 100644 --- a/src/content/docs/reference/cli/troubleshooting.mdx +++ b/src/content/docs/agents/cli/oz-cli/troubleshooting.mdx @@ -39,10 +39,10 @@ oz --version **Authentication issues** * Interactive login: ensure you've completed the browser-based flow with `oz login`. -* API keys: confirm the key is valid, not expired, and exported correctly. Invalid, expired, or missing keys can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +* API keys: confirm the key is valid, not expired, and exported correctly. Invalid, expired, or missing keys can return an [`authentication_required` error](/factories/api-and-sdk/troubleshooting/errors/authentication-required/). **Agent or MCP errors**\ -Ensure your agent profile and [MCP servers](/agents/capabilities/mcp/) are configured properly, with correct permissions. See [MCP Servers](/reference/cli/mcp-servers/) and [Agent profiles](/reference/cli/agent-profiles/) for details. +Ensure your agent profile and [MCP servers](/agents/capabilities/mcp/) are configured properly, with correct permissions. See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) and [Agent profiles](/agents/cli/oz-cli/agent-profiles/) for details. --- @@ -118,7 +118,7 @@ oz environment delete <ID> Add `--force` to skip confirmation checks for environments used by integrations. -Only do this once you've confirmed no active integrations are relying on that environment. If an integration points to a deleted environment, requests from Slack/Linear will fail with a [`resource_not_found` error](/reference/api-and-sdk/troubleshooting/errors/resource-not-found/) until you create a new integration with a valid environment. +Only do this once you've confirmed no active integrations are relying on that environment. If an integration points to a deleted environment, requests from Slack/Linear will fail with a [`resource_not_found` error](/factories/api-and-sdk/troubleshooting/errors/resource-not-found/) until you create a new integration with a valid environment. ### Integrations @@ -149,7 +149,7 @@ This happens when: * You add a repo that Warp doesn’t have access to yet, or * You personally haven’t granted the Warp GitHub app permissions for that repo. -Follow the GitHub popup flow to install/adjust the Warp GitHub app. Missing external authorization can return an [`external_authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +Follow the GitHub popup flow to install/adjust the Warp GitHub app. Missing external authorization can return an [`external_authentication_required` error](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/). #### **The agent can’t open PRs or push changes to my repo** @@ -160,7 +160,7 @@ Check the following: 2. **Warp GitHub app has access to that repo** 1. In GitHub’s settings, confirm the Warp app is installed and that the repo is selected. 3. **You have write access** - 1. The agent inherits your GitHub permissions. If you only have read access, Warp can’t open PRs or push branches on your behalf, and the run may return a [`not_authorized` error](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). + 1. The agent inherits your GitHub permissions. If you only have read access, Warp can’t open PRs or push branches on your behalf, and the run may return a [`not_authorized` error](/factories/api-and-sdk/troubleshooting/errors/not-authorized/). ### Docker image & environment failures @@ -172,7 +172,7 @@ Check: 2. The image is public on Docker Hub. 3. You can pull it locally: `docker pull <image_name>` -If local docker pull fails, fix the image visibility/name first, then recreate or update the environment with a working image. Image pull and setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). +If local docker pull fails, fix the image visibility/name first, then recreate or update the environment with a working image. Image pull and setup failures can surface as [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/). #### **The agent can’t find tools or runtimes inside the environment** @@ -183,7 +183,7 @@ This usually means the Docker image is missing required dependencies. Fix by eit #### **I see "VM failed before the agent could run. This is likely an issue with your Docker image"** -This typically means your Docker image uses musl libc instead of glibc. Alpine Linux and other musl-based images are not compatible with the agent runtime, and this can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). +This typically means your Docker image uses musl libc instead of glibc. Alpine Linux and other musl-based images are not compatible with the agent runtime, and this can surface as [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/). Fix: diff --git a/src/content/docs/reference/cli/warp-drive.mdx b/src/content/docs/agents/cli/oz-cli/warp-drive.mdx similarity index 100% rename from src/content/docs/reference/cli/warp-drive.mdx rename to src/content/docs/agents/cli/oz-cli/warp-drive.mdx diff --git a/src/content/docs/agents/cli/quickstart.mdx b/src/content/docs/agents/cli/quickstart.mdx index 13b369e84..389a9e094 100644 --- a/src/content/docs/agents/cli/quickstart.mdx +++ b/src/content/docs/agents/cli/quickstart.mdx @@ -80,7 +80,7 @@ When login completes, the CLI shows its start screen with the version, a short " WARP_API_KEY=YOUR_API_KEY warp ``` -You can also pass the `--api-key` flag, but prefer the environment variable. Command-line arguments can be captured in shell history and process listings. See [API keys](/reference/cli/api-keys/) to learn how to create one. +You can also pass the `--api-key` flag, but prefer the environment variable. Command-line arguments can be captured in shell history and process listings. See [API keys](/agents/cli/oz-cli/api-keys/) to learn how to create one. ::: ## 3. Run your first prompt diff --git a/src/content/docs/agents/cli/reference.mdx b/src/content/docs/agents/cli/reference.mdx index 79f770b25..bbd1ccd5e 100644 --- a/src/content/docs/agents/cli/reference.mdx +++ b/src/content/docs/agents/cli/reference.mdx @@ -32,7 +32,7 @@ warp --api-key YOUR_API_KEY Command-line arguments can be captured in shell history and process listings. Prefer the `WARP_API_KEY` environment variable, ideally populated from a secret manager. ::: -Create a key in the Warp app under **Settings** > **Cloud platform** > **API keys**. See the [API keys reference](/reference/cli/api-keys/) for details. +Create a key in the Warp app under **Settings** > **Cloud platform** > **API keys**. See the [API keys reference](/agents/cli/oz-cli/api-keys/) for details. ### `--auto-approve` diff --git a/src/content/docs/agents/inference/model-choice.mdx b/src/content/docs/agents/inference/model-choice.mdx index 44addc041..3c3bca0b6 100644 --- a/src/content/docs/agents/inference/model-choice.mdx +++ b/src/content/docs/agents/inference/model-choice.mdx @@ -16,7 +16,7 @@ Warp lets you choose from a curated set of large language models (LLMs) to power **Warp supports the following models.** -The `model_id` values shown below can be used when configuring models via the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) or [CLI](/reference/cli/). +The `model_id` values shown below can be used when configuring models via the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) or [CLI](/agents/cli/oz-cli/). ### Auto models diff --git a/src/content/docs/changelog/2025.mdx b/src/content/docs/changelog/2025.mdx index a87fa2fa0..118869e0f 100644 --- a/src/content/docs/changelog/2025.mdx +++ b/src/content/docs/changelog/2025.mdx @@ -192,7 +192,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd **New Features** -* Warp agents are now available via the command line. See the [CLI reference](https://docs.warp.dev/reference/cli). +* Warp agents are now available via the command line. See the [CLI reference](https://docs.warp.dev/agents/cli/oz-cli). * Added support for custom Regex names in Enterprise Secret Redaction. **Improvements** diff --git a/src/content/docs/changelog/2026.mdx b/src/content/docs/changelog/2026.mdx index 136430e66..b52f9e911 100644 --- a/src/content/docs/changelog/2026.mdx +++ b/src/content/docs/changelog/2026.mdx @@ -1673,7 +1673,7 @@ Oz is Warp's orchestration platform for cloud agents: launch parallel agents, au * **Cloud environments for consistent execution** — configure Docker-based environments (unlimited repos + setup commands) and run agents in isolated cloud sandboxes. [Environments docs →](https://docs.warp.dev/platform/environments) * **Track agents from the web** — manage runs, create schedules, configure environments, and set up integrations from any browser in the <a href="https://oz.warp.dev">Oz web app</a>. * **Schedule agents based on Skills** — run agents automatically on a cron schedule for code cleanup, dependency updates, and issue triage. See [Scheduled Agents](/platform/triggers/scheduled-agents/). -* **Programmable by default** — orchestrate agents via the CLI and integrate Oz into tools and services via the [API and CLI reference](/reference/). +* **Programmable by default** — orchestrate agents via the CLI and integrate Oz into tools and services via the [API and CLI reference](/factories/developer-tools/). #### Warp Upgrades diff --git a/src/content/docs/enterprise/enterprise-features/analytics-api.mdx b/src/content/docs/enterprise/enterprise-features/analytics-api.mdx index 3dae9cf28..11f3a801d 100644 --- a/src/content/docs/enterprise/enterprise-features/analytics-api.mdx +++ b/src/content/docs/enterprise/enterprise-features/analytics-api.mdx @@ -29,7 +29,7 @@ Before you can call the API, your team must satisfy all of the following: * **Enterprise plan** - The Analytics API is available to all enterprise teams during Early Access; no separate enrollment is required. * **Admin role on the team** - Calls are rejected unless the authenticated user has admin-level permissions on the enterprise team. See [Roles and permissions](/enterprise/team-management/roles-and-permissions/). -* **A personal Warp API key** - Authenticate requests with a key from **Settings** > **Cloud platform** > **API keys** in the Warp app. See [API Keys](/reference/cli/api-keys/) for step-by-step instructions. Agent API keys (including legacy team keys) are not accepted by these endpoints — only personal API keys belonging to a team admin work. +* **A personal Warp API key** - Authenticate requests with a key from **Settings** > **Cloud platform** > **API keys** in the Warp app. See [API Keys](/agents/cli/oz-cli/api-keys/) for step-by-step instructions. Agent API keys (including legacy team keys) are not accepted by these endpoints — only personal API keys belonging to a team admin work. * **Enterprise Usage Reporting toggle enabled** - In the Warp app, go to **Admin Panel** > **Privacy** and turn on **Enterprise Usage Reporting (Early Access)**. Until this toggle is on, no usage data is recorded for your team and the endpoints will return empty datasets even if every other prerequisite is met. :::caution @@ -297,7 +297,7 @@ Any authenticated user with admin-level permissions on an enterprise team. Calls ### What kind of API key works? -Only **personal** Warp API keys created by an admin from **Settings** > **Cloud platform** > **API keys**. Agent API keys (including legacy team keys) are explicitly rejected by these endpoints. See [API Keys](/reference/cli/api-keys/) for how to create one. +Only **personal** Warp API keys created by an admin from **Settings** > **Cloud platform** > **API keys**. Agent API keys (including legacy team keys) are explicitly rejected by these endpoints. See [API Keys](/agents/cli/oz-cli/api-keys/) for how to create one. ### Are these calls billed? @@ -309,7 +309,7 @@ The `events` endpoint enforces a hard 365-day window between `start_date` and `e ## Related resources -* [API Keys](/reference/cli/api-keys/) - Create and manage personal Warp API keys. +* [API Keys](/agents/cli/oz-cli/api-keys/) - Create and manage personal Warp API keys. * [Admin Panel](/enterprise/team-management/admin-panel/) - Manage team settings, including the **Privacy** section. * [Roles and permissions](/enterprise/team-management/roles-and-permissions/) - Required admin role for Analytics API access. * [Architecture and deployment](/enterprise/enterprise-features/architecture-and-deployment/) - Where enterprise data is stored and how it transits Warp's infrastructure. 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 b516e1313..2cbcf52d3 100644 --- a/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx +++ b/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx @@ -157,7 +157,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 +* [Deployment Patterns](/factories/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 * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure agent policies and security settings diff --git a/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx b/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx index c21fb46bc..25e380115 100644 --- a/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx +++ b/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx @@ -164,7 +164,7 @@ Once your team is set up: * **BYOLLM** - Set up [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through your cloud infrastructure for data locality and cost control * **Team-managed API keys and endpoints** - Configure [shared provider API keys and custom endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) for your team in the Admin Panel, available in both interactive sessions and cloud agents * **Monitor usage** - Review usage analytics in the Admin Panel to track adoption and measure engineering productivity gains -* **Self-hosting** - Run agents on your own infrastructure to control where agents run and keep repository clones on your own machines. See [Self-hosting](/platform/self-hosting/) for setup instructions +* **Self-hosting** - Run agents on your own infrastructure to control where agents run and keep repository clones on your own machines. See [Self-hosting](/factories/self-hosting/) for setup instructions ## Troubleshooting diff --git a/src/content/docs/enterprise/team-management/admin-panel.mdx b/src/content/docs/enterprise/team-management/admin-panel.mdx index 896571486..c225b9f8c 100644 --- a/src/content/docs/enterprise/team-management/admin-panel.mdx +++ b/src/content/docs/enterprise/team-management/admin-panel.mdx @@ -269,7 +269,7 @@ Controls how screenshots and video recordings captured with [Computer Use](/agen **Enabled GitHub Orgs** -The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations. That association does two things: it lets cloud agents initiated with an [agent API key](/reference/cli/api-keys/) clone repositories and open pull requests using the Warp Factories GitHub App, and it tells Warp which team owns runs started from the [GitHub integration](/platform/integrations/github/) when someone mentions `@warp-agent` in those repositories. +The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations. That association does two things: it lets cloud agents initiated with an [agent API key](/agents/cli/oz-cli/api-keys/) clone repositories and open pull requests using the Warp Factories GitHub App, and it tells Warp which team owns runs started from the [GitHub integration](/platform/integrations/github/) when someone mentions `@warp-agent` in those repositories. To configure: diff --git a/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx similarity index 100% rename from src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx rename to src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx diff --git a/src/content/docs/reference/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx similarity index 93% rename from src/content/docs/reference/api-and-sdk/index.mdx rename to src/content/docs/factories/api-and-sdk/index.mdx index 2815e592d..f60d954a6 100644 --- a/src/content/docs/reference/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -12,7 +12,7 @@ import { VARS } from '@data/vars'; The {VARS.API_SDK_NAME} lets you create, monitor, and inspect cloud agent runs programmatically. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling. The SDKs are ideal for CI pipelines, internal tools, and custom integrations. :::note -Some examples in this reference and the [CLI reference](/reference/cli/) use `oz` commands (for example, `oz environment list`) from the {VARS.WARP_AGENT_CLI}. Those commands remain supported through the end of September 2026. The [Warp Agent CLI reference](/agents/cli/reference/) does not yet document a `warp` equivalent. +Some examples in this reference and the [CLI reference](/agents/cli/oz-cli/) use `oz` commands (for example, `oz environment list`) from the {VARS.WARP_AGENT_CLI}. Those commands remain supported through the end of September 2026. The [Warp Agent CLI reference](/agents/cli/reference/) does not yet document a `warp` equivalent. ::: ### API overview @@ -39,7 +39,7 @@ Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and * **Typed requests and responses** (editor autocomplete, fewer schema mistakes) * **Built-in retries and timeouts** (with per-request overrides) -* [**Consistent error types**](/reference/api-and-sdk/troubleshooting/errors/) that map to API status codes +* [**Consistent error types**](/factories/api-and-sdk/troubleshooting/errors/) that map to API status codes * **Helpers for raw responses** when you need headers/status or custom parsing If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. @@ -118,7 +118,7 @@ See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**Type Cancel a run that is currently queued or in progress. Returns the ID of the cancelled run. -All endpoint semantics, query parameters, and [error codes](/reference/api-and-sdk/troubleshooting/errors/) are documented on the [Agents API Reference](/api). +All endpoint semantics, query parameters, and [error codes](/factories/api-and-sdk/troubleshooting/errors/) are documented on the [Agents API Reference](/api). --- diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/factories/api-and-sdk/quickstart.mdx similarity index 92% rename from src/content/docs/reference/api-and-sdk/quickstart.mdx rename to src/content/docs/factories/api-and-sdk/quickstart.mdx index 00107985e..f500af542 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/factories/api-and-sdk/quickstart.mdx @@ -18,7 +18,7 @@ Watch this short demo of how the REST API can power agent-backed apps like [Powe ## Prerequisites -* **A Warp API key** - Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](/platform/agents/). See [API Keys](/reference/cli/api-keys/) for the full flow. +* **A Warp API key** - Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](/platform/agents/). See [API Keys](/agents/cli/oz-cli/api-keys/) for the full flow. * **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/platform/quickstart/) first. --- @@ -71,9 +71,9 @@ The `state` has the following possible values: * `QUEUED` - The run is waiting to start. * `INPROGRESS` - The agent is actively running. * `SUCCEEDED` - The run completed successfully. -* `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret the error code. +* `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/factories/api-and-sdk/troubleshooting/errors/) to interpret the error code. -These are the most common states. See the [full API reference](/reference/api-and-sdk/) for all possible values. +These are the most common states. See the [full API reference](/factories/api-and-sdk/) for all possible values. To list all recent runs: @@ -92,7 +92,7 @@ You can also view and manage all runs in the <a href={`${VARS.WEB_APP_URL}/runs` ## Next steps -* **Read the full API reference** - [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) documents all endpoint parameters, query filters, and response schemas. +* **Read the full API reference** - [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) documents all endpoint parameters, query filters, and response schemas. * **Explore the SDKs** - [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) include typed request/response models, retries, and error handling. -* **See a real-world example** - [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors. +* **See a real-world example** - [Demo: Sentry monitoring with SDK](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors. * **Schedule and automate** - See [Scheduled Agents Quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or [Integrations Quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear. diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx similarity index 89% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx index 41b8898b0..421899ce4 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx @@ -8,7 +8,7 @@ description: >- The `agent_process_failed` error occurs when the agent process exits unexpectedly after environment setup has completed, before the task reaches a normal terminal state. :::note -This is classified as a **platform error** (task state → ERROR) rather than a user error. It differs from [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/), which covers failures that happen while initializing the environment (cloning the repo, running setup commands, starting MCP servers). `agent_process_failed` covers failures that happen during the agent's active execution phase. +This is classified as a **platform error** (task state → ERROR) rather than a user error. It differs from [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/), which covers failures that happen while initializing the environment (cloning the repo, running setup commands, starting MCP servers). `agent_process_failed` covers failures that happen during the agent's active execution phase. ::: --- @@ -35,7 +35,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/", + "type": "/factories/api-and-sdk/troubleshooting/errors/agent-process-failed/", "title": "The agent process exited unexpectedly.", "status": 500, "instance": "/api/v1/agent/tasks", @@ -58,5 +58,5 @@ This error is returned when: ## Related * [Cloud Agents Overview](/platform/) — How cloud agent tasks work -* [environment_setup_failed](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Errors during environment setup -* [internal_error](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Catch-all for unexpected server-side errors +* [environment_setup_failed](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Errors during environment setup +* [internal_error](/factories/api-and-sdk/troubleshooting/errors/internal-error/) — Catch-all for unexpected server-side errors diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/authentication-required.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx similarity index 92% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/authentication-required.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx index 37e3adcd9..c8c026b82 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/authentication-required.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx @@ -36,7 +36,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/authentication-required/", + "type": "/factories/api-and-sdk/troubleshooting/errors/authentication-required/", "title": "Your API key is invalid or has expired. Please generate a new key and try again.", "status": 401, "instance": "/api/v1/agent/tasks", @@ -57,5 +57,5 @@ This error is returned when: ## Related -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API authentication +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API authentication * [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) — API key management diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx similarity index 95% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx index f483a50b5..b9e7e7cb8 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx @@ -32,7 +32,7 @@ The `title` field in the response will describe the specific budget constraint. ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/", + "type": "/factories/api-and-sdk/troubleshooting/errors/budget-exceeded/", "title": "Monthly spending budget of $50 has been reached.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/conflict.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx similarity index 91% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/conflict.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx index 489a0620a..c45972875 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/conflict.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx @@ -34,7 +34,7 @@ The operation can typically succeed once the resource transitions to the expecte ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/conflict/", + "type": "/factories/api-and-sdk/troubleshooting/errors/conflict/", "title": "Pending agent runs cannot be cancelled, retry after a moment.", "status": 409, "instance": "/api/v1/agent/tasks/abc123/cancel", @@ -57,4 +57,4 @@ For task cancellation specifically, wait until the task moves from **pending** t ## Related * [Managing Cloud Agents](/platform/managing-cloud-agents/) — Viewing and managing agent tasks -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API reference for managing agent tasks +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API reference for managing agent tasks diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx similarity index 96% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx index 3b6480de1..ebc168b31 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx @@ -35,7 +35,7 @@ For security reasons, the error message is intentionally generic and does not de ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/content-policy-violation/", + "type": "/factories/api-and-sdk/troubleshooting/errors/content-policy-violation/", "title": "Unable to start cloud agent. Please try again or contact support if the issue persists.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx similarity index 92% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx index b356fc21e..eb36310d0 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx @@ -38,7 +38,7 @@ The `title` field in the response will describe the specific setup failure. ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/", + "type": "/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/", "title": "Failed to clone repository: branch 'main' not found in acme/backend", "status": 500, "instance": "/api/v1/agent/tasks", @@ -54,7 +54,7 @@ The `title` field in the response will describe the specific setup failure. 1. **Check repository configuration** — Verify the repository URL and branch name in your [environment settings](/platform/environments/). Ensure the repository exists and is accessible. 2. **Check setup commands** — Run the setup commands locally to confirm they work. Look for missing dependencies, incorrect paths, or syntax errors. 3. **Check working directory** — Ensure the working directory path exists relative to the cloned repository root. -4. **Check MCP server configuration** — Verify MCP server startup commands and that any required dependencies or credentials are available. See [MCP Servers for Agents](/reference/cli/mcp-servers/). +4. **Check MCP server configuration** — Verify MCP server startup commands and that any required dependencies or credentials are available. See [MCP Servers for Agents](/agents/cli/oz-cli/mcp-servers/). 5. **Check secrets** — If setup commands reference environment variables from [secrets](/platform/secrets/), verify the secrets are configured and in scope. --- @@ -63,4 +63,4 @@ The `title` field in the response will describe the specific setup failure. * [Environments](/platform/environments/) — Configuring cloud agent environments * [Secrets](/platform/secrets/) — Managing credentials for agent environments -* [MCP Servers for Agents](/reference/cli/mcp-servers/) — Configuring MCP servers +* [MCP Servers for Agents](/agents/cli/oz-cli/mcp-servers/) — Configuring MCP servers diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx similarity index 95% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx index 82872f987..d1847c5bb 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx @@ -43,7 +43,7 @@ This error includes extra fields beyond the standard response format: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", + "type": "/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/", "title": "User is not connected to GitHub", "status": 401, "instance": "/api/v1/agent/tasks", @@ -58,7 +58,7 @@ This error includes extra fields beyond the standard response format: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", + "type": "/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/", "title": "User does not have access to the following repositories in the environment: acme/backend", "status": 401, "detail": "inaccessible repos: acme/backend", @@ -75,7 +75,7 @@ This error includes extra fields beyond the standard response format: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", + "type": "/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/", "title": "Unable to locate your Warp account", "status": 401, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/feature-not-available.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx similarity index 96% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/feature-not-available.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx index 1d255c180..e911b9e14 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/feature-not-available.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx @@ -32,7 +32,7 @@ The `title` field in the response will describe the specific feature that is una ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/feature-not-available/", + "type": "/factories/api-and-sdk/troubleshooting/errors/feature-not-available/", "title": "Slack integration requires a Build plan or higher.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx similarity index 77% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx index af4046131..16dc9b825 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx @@ -17,7 +17,7 @@ All error responses share this structure: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/invalid-request/", + "type": "/factories/api-and-sdk/troubleshooting/errors/invalid-request/", "title": "The request contains invalid or missing parameters.", "status": 400, "detail": "schedule_id is required", @@ -53,29 +53,29 @@ Errors are split into two categories based on what caused the failure: These indicate something the caller needs to fix. When a cloud agent task encounters a user error, the task transitions to the **FAILED** state. -* [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) — Team has no remaining add-on credits -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) — Feature not included in your current plan -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) — External service authorization needed -* [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/) — Insufficient permissions for the operation -* [`invalid_request`](/reference/api-and-sdk/troubleshooting/errors/invalid-request/) — Malformed request or invalid parameters -* [`resource_not_found`](/reference/api-and-sdk/troubleshooting/errors/resource-not-found/) — Referenced resource does not exist -* [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/) — Spending budget limit reached -* [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/) — Integration is disabled -* [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) — Integration setup is incomplete -* [`operation_not_supported`](/reference/api-and-sdk/troubleshooting/errors/operation-not-supported/) — Operation not supported for this resource or state -* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Cloud agent environment failed to initialize -* [`content_policy_violation`](/reference/api-and-sdk/troubleshooting/errors/content-policy-violation/) — Task flagged by content policy checks -* [`conflict`](/reference/api-and-sdk/troubleshooting/errors/conflict/) — Request conflicts with the current resource state (retryable) +* [`insufficient_credits`](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/) — Team has no remaining add-on credits +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) — Feature not included in your current plan +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) — External service authorization needed +* [`not_authorized`](/factories/api-and-sdk/troubleshooting/errors/not-authorized/) — Insufficient permissions for the operation +* [`invalid_request`](/factories/api-and-sdk/troubleshooting/errors/invalid-request/) — Malformed request or invalid parameters +* [`resource_not_found`](/factories/api-and-sdk/troubleshooting/errors/resource-not-found/) — Referenced resource does not exist +* [`budget_exceeded`](/factories/api-and-sdk/troubleshooting/errors/budget-exceeded/) — Spending budget limit reached +* [`integration_disabled`](/factories/api-and-sdk/troubleshooting/errors/integration-disabled/) — Integration is disabled +* [`integration_not_configured`](/factories/api-and-sdk/troubleshooting/errors/integration-not-configured/) — Integration setup is incomplete +* [`operation_not_supported`](/factories/api-and-sdk/troubleshooting/errors/operation-not-supported/) — Operation not supported for this resource or state +* [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Cloud agent environment failed to initialize +* [`content_policy_violation`](/factories/api-and-sdk/troubleshooting/errors/content-policy-violation/) — Task flagged by content policy checks +* [`conflict`](/factories/api-and-sdk/troubleshooting/errors/conflict/) — Request conflicts with the current resource state (retryable) ### Platform errors These indicate a Warp-side issue. When a cloud agent task encounters a platform error, the task transitions to the **ERROR** state. Retryable errors are automatically retried before the task is marked as failed. -* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) — Invalid or expired API key -* [`resource_unavailable`](/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/) — Transient infrastructure issue (retryable) -* [`internal_error`](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Unexpected server-side error (retryable) -* [`infrastructure_timeout`](/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/) — Task terminated after exceeding the maximum allowed runtime -* [`agent_process_failed`](/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/) — Agent process exited unexpectedly during task execution +* [`authentication_required`](/factories/api-and-sdk/troubleshooting/errors/authentication-required/) — Invalid or expired API key +* [`resource_unavailable`](/factories/api-and-sdk/troubleshooting/errors/resource-unavailable/) — Transient infrastructure issue (retryable) +* [`internal_error`](/factories/api-and-sdk/troubleshooting/errors/internal-error/) — Unexpected server-side error (retryable) +* [`infrastructure_timeout`](/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout/) — Task terminated after exceeding the maximum allowed runtime +* [`agent_process_failed`](/factories/api-and-sdk/troubleshooting/errors/agent-process-failed/) — Agent process exited unexpectedly during task execution --- @@ -87,6 +87,6 @@ When an error response includes a `trace_id`, you can include it when [contactin ## Related -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API reference for creating and managing agent tasks +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API reference for creating and managing agent tasks * [Cloud Agents Overview](/platform/) — How cloud agents work * [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Plan requirements and billing details diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx similarity index 94% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx index fff2a0222..e96660122 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx @@ -35,7 +35,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", + "type": "/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", "title": "The task exceeded the maximum allowed runtime and was terminated.", "status": 500, "instance": "/api/v1/agent/tasks", @@ -58,5 +58,5 @@ This error is returned when: ## Related * [Cloud Agents Overview](/platform/) — How cloud agent tasks work -* [internal_error](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Other platform-level errors +* [internal_error](/factories/api-and-sdk/troubleshooting/errors/internal-error/) — Other platform-level errors * [Cloud Agents FAQs](/platform/faqs/) — Common questions about cloud agents diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx similarity index 98% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx index 1a0f262fd..3eef34f85 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx @@ -40,7 +40,7 @@ For the full waterfall, see [How are cloud agent runs on team plans billed when ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/", + "type": "/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/", "title": "The principal billed for this run has no remaining credits. Purchase add-on credits or raise the team-wide spend cap to continue.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-disabled.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx similarity index 95% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-disabled.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx index 91cdccec5..aeff2a424 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-disabled.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx @@ -31,7 +31,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/integration-disabled/", + "type": "/factories/api-and-sdk/troubleshooting/errors/integration-disabled/", "title": "This integration is disabled. Please enable it in Oz.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx similarity index 96% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx index 24b249f9f..775be7f26 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx @@ -41,7 +41,7 @@ This error includes extra fields beyond the standard response format: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/", + "type": "/factories/api-and-sdk/troubleshooting/errors/integration-not-configured/", "title": "Slack integration is not configured", "status": 400, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/internal-error.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx similarity index 96% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/internal-error.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx index 2dd683a7d..1afacfd24 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/internal-error.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx @@ -31,7 +31,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/internal-error/", + "type": "/factories/api-and-sdk/troubleshooting/errors/internal-error/", "title": "An unexpected error occurred. Please try again later. If the issue persists, contact support.", "status": 500, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx similarity index 89% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx index dc807a2fd..ce6c6ec9f 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx @@ -36,7 +36,7 @@ The `detail` field in the response will describe the specific validation issue. ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/invalid-request/", + "type": "/factories/api-and-sdk/troubleshooting/errors/invalid-request/", "title": "The request contains invalid or missing parameters.", "status": 400, "detail": "schedule_id is required", @@ -51,11 +51,11 @@ The `detail` field in the response will describe the specific validation issue. ## How to resolve 1. Check the `detail` field for the specific validation issue. -2. Correct the request parameters according to the [API documentation](/reference/api-and-sdk/). +2. Correct the request parameters according to the [API documentation](/factories/api-and-sdk/). 3. Retry the request. --- ## Related -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API request format and parameters +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API request format and parameters diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/not-authorized.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx similarity index 92% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/not-authorized.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx index 964bbfc17..a1870fea8 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/not-authorized.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx @@ -33,7 +33,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/not-authorized/", + "type": "/factories/api-and-sdk/troubleshooting/errors/not-authorized/", "title": "You do not have permission for this operation.", "status": 403, "detail": "user is not a member of the team", @@ -56,4 +56,4 @@ This error is returned when: ## Related * [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Permission model and identity -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API authentication and authorization +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API authentication and authorization diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx similarity index 88% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx index eaabaa540..f57a68f50 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx @@ -32,7 +32,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/operation-not-supported/", + "type": "/factories/api-and-sdk/troubleshooting/errors/operation-not-supported/", "title": "Self-hosted agent runs cannot be cancelled with the API.", "status": 422, "instance": "/api/v1/agent/tasks/abc123/cancel", @@ -56,5 +56,5 @@ This error is returned when: ## Related * [Cloud Agents Overview](/platform/) — How cloud agent tasks work -* [Self-hosting](/platform/self-hosting/) — Self-hosted agent configuration -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API reference for managing agent tasks +* [Self-hosting](/factories/self-hosting/) — Self-hosted agent configuration +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API reference for managing agent tasks diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-not-found.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx similarity index 96% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-not-found.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx index e3f7f36f3..30feb59af 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-not-found.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx @@ -34,7 +34,7 @@ The `detail` field in the response will describe which resource was not found. ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/resource-not-found/", + "type": "/factories/api-and-sdk/troubleshooting/errors/resource-not-found/", "title": "The requested resource was not found.", "status": 404, "detail": "environment abc123 not found", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx similarity index 90% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx index 69f5b63c3..0e721a0c1 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx @@ -32,7 +32,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/", + "type": "/factories/api-and-sdk/troubleshooting/errors/resource-unavailable/", "title": "Agent capacity is temporarily full. Your task will be retried automatically, or you can try again later.", "status": 429, "instance": "/api/v1/agent/tasks", @@ -46,7 +46,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/", + "type": "/factories/api-and-sdk/troubleshooting/errors/resource-unavailable/", "title": "Failed to create a sandbox instance for your agent. This is typically a transient issue — your task will be retried automatically.", "status": 500, "instance": "/api/v1/agent/tasks", @@ -72,4 +72,4 @@ If the error persists after retries: ## Related * [Cloud Agents Overview](/platform/) — How cloud agent execution works -* [Deployment Patterns](/platform/deployment-patterns/) — Execution models and infrastructure +* [Deployment Patterns](/factories/deployment-patterns/) — Execution models and infrastructure diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx similarity index 90% rename from src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx index 097333f4f..ee151f68c 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx @@ -10,4 +10,4 @@ When the {VARS.API_SDK_NAME} encounters an error, it returns a structured respon ## Resources -* [**Errors**](/reference/api-and-sdk/troubleshooting/errors/) — Full reference for all API error codes, including causes, example responses, and resolution steps +* [**Errors**](/factories/api-and-sdk/troubleshooting/errors/) — Full reference for all API error codes, including causes, example responses, and resolution steps diff --git a/src/content/docs/platform/deployment-patterns.mdx b/src/content/docs/factories/deployment-patterns.mdx similarity index 92% rename from src/content/docs/platform/deployment-patterns.mdx rename to src/content/docs/factories/deployment-patterns.mdx index 5f35d060a..e8adae12e 100644 --- a/src/content/docs/platform/deployment-patterns.mdx +++ b/src/content/docs/factories/deployment-patterns.mdx @@ -127,8 +127,8 @@ Think of self-hosted execution as **customer-hosted execution with Warp-hosted o Self-hosting has two architectures that differ on **who orchestrates agent runs** (both keep code and execution on your infrastructure): -* **[Managed](/platform/self-hosting/#managed-architecture)** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates. You run the `oz-agent-worker` daemon; the {VARS.WARP_AUTOMATION_PLATFORM} routes runs to it from Slack, Linear, schedules, the API, or `oz agent run-cloud`. Tasks execute in Docker containers, Kubernetes Jobs, or directly on the host. -* **[Unmanaged](/platform/self-hosting/unmanaged/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment. Warp provides session tracking and observability; it does not start or stop agents. +* **[Managed](/factories/self-hosting/#managed-architecture)** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates. You run the `oz-agent-worker` daemon; the {VARS.WARP_AUTOMATION_PLATFORM} routes runs to it from Slack, Linear, schedules, the API, or `oz agent run-cloud`. Tasks execute in Docker containers, Kubernetes Jobs, or directly on the host. +* **[Unmanaged](/platform/unmanaged-execution/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment. Warp provides session tracking and observability; it does not start or stop agents. Why teams choose self-hosted execution: @@ -136,4 +136,4 @@ Why teams choose self-hosted execution: * Agents need to access services behind a VPN or self-hosted SCMs like GitLab or Bitbucket. Warp-hosted agents can also access GitLab and Bitbucket over the public internet — see the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides. * Your environments (multi-service stacks, heavy resource requirements) don't fit in a single Docker container. -For setup, decision guides, and a quickstart, start with [Self-hosting](/platform/self-hosting/). +For setup, decision guides, and a quickstart, start with [Self-hosting](/factories/self-hosting/). diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx new file mode 100644 index 000000000..85518d073 --- /dev/null +++ b/src/content/docs/factories/developer-tools.mdx @@ -0,0 +1,32 @@ +--- +title: Developer tools for Warp Factories +description: >- + Use APIs, SDKs, webhooks, and MCP to integrate Warp Factories with your + services, tools, and development workflows. +sidebar: + label: "Developer tools" +--- +import { VARS } from '@data/vars'; + +Warp Factories provides programmatic interfaces for sending work to a factory, integrating external systems, and inspecting the runs a factory produces. + +## Choose an interface + +* **[Factory API](/factories/factory-api/)** - Find a factory and send work to it by UID from your own application or service. +* **[{VARS.API_SDK_NAME}](/factories/api-and-sdk/)** - Create, monitor, and manage cloud agent runs from scripts, CI, and backend services. +* **[API reference](/api)** - Look up the full HTTP API schema, parameters, and responses. +* **[Factory MCP](/factories/factory-mcp/)** - Exchange work between a factory and a connected coding agent or MCP client. +* **[Webhooks](/factories/webhooks/)** - Receive events from systems that can send JSON and route matching deliveries into factory automations. + +## Use the API and SDK + + +# Use the API and SDK +es/webhooks/)** - Receive events from syfor typed requests, retries, and error handling. Start with the [Aes/webhooks/)** - Recei/factories/api-and-sdk/quickstart/) to create and inspect a run, or use the [Sentry monitoring example](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) to connect an external event source. +es/webhooks/)** - Recrequests, see [API troubleshooting](/factories/api-and-sdk/troubleshooting/) and the [API error reference](/factories/api-and-sdk/troubleshooting/errors/). + +## Related pages + +* [Connect your factory](/factories/connect-your-factory/) - Choose an integration or direct intake path. +* [Factory automations](/factories/automations/) - Route events and schedules to factory agents. +* [Factory dashboard](/factories/factory-dashboard/) - Inspect work items, runs, and factory settings. diff --git a/src/content/docs/factories/factory-api.mdx b/src/content/docs/factories/factory-api.mdx index 141f3b200..40a03c247 100644 --- a/src/content/docs/factories/factory-api.mdx +++ b/src/content/docs/factories/factory-api.mdx @@ -20,7 +20,7 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ * `GET /factory/{uid}` - get one factory by UID. * `POST /factory/{uid}/runs` - dispatch a run to the factory's foreman agent. Pass a `prompt`; the server resolves the foreman for you. -A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [Agent API](/reference/api-and-sdk/) you'd use for any run. +A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [Agent API](/factories/api-and-sdk/) you'd use for any run. ## When to use the factory API vs the Agent API @@ -119,12 +119,12 @@ Content-Type: application/json } ``` -See [key endpoints](/reference/api-and-sdk/#key-endpoints) for the full set of run-management operations, including cancellation. +See [key endpoints](/factories/api-and-sdk/#key-endpoints) for the full set of run-management operations, including cancellation. ## Related pages * [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the factory API alongside Slack, GitHub, and Factory MCP. * [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) - A worked example that discovers a factory and dispatches and continues a task from a custom chat integration. * [Factory MCP](/factories/factory-mcp/) - Connect a local coding agent to a factory instead of calling the REST API directly. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying Agent API. +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying Agent API. * [How Warp Factories work](/factories/how-factories-work/) - The stages a dispatched task moves through after the foreman picks it up. diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index b0eb0f94e..a7296832f 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -291,7 +291,7 @@ MCP servers for agents that don't declare their own, in the same form as [`mcpSe ### `agentDefaults.workerHost` -Where runs execute: `warp` for Warp-hosted compute, or the ID of a connected worker in the [managed self-hosting architecture](/platform/self-hosting/#managed-architecture). Configure the worker's Docker, Kubernetes, or Direct backend on the worker itself; the factory definition selects the worker and a compatible runner. +Where runs execute: `warp` for Warp-hosted compute, or the ID of a connected [self-hosted worker](/factories/self-hosting/). Configure the worker's Docker, Kubernetes, or Direct backend on the worker itself; the factory definition selects the worker and a compatible runner. ### `agentDefaults.computerUseModel` @@ -443,7 +443,7 @@ An automation may also declare `model` or `harness`, `runner`, `environmentId`, ## `runners/<name>.yaml` -Optional. Each file defines a runner: the compute a run executes on. The runner's name comes from the file name, and agents and automations select it by that name. See [cloud agent runners](/platform/runners/) for how runners behave. For three runners selected per agent, including a macOS runner, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr). +Optional. Each file defines a runner: the compute a run executes on. The runner's name comes from the file name, and agents and automations select it by that name. See [cloud agent runners](/factories/runners/) for how runners behave. For three runners selected per agent, including a macOS runner, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr). ```yaml title="runners/linux-build.yaml" description: Linux runner for payments builds and tests diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 73d922586..96338c571 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -74,7 +74,7 @@ In clients that use the `mcpServers` JSON format, such as Cursor: For Codex and other clients, follow the [client's own remote-server instructions](https://developers.openai.com/codex/mcp/#connect-codex-to-an-mcp-server) with the same URL. -Automation that runs without a person present, such as a CI pipeline or a headless server, can't complete the browser sign-in. For those cases, authenticate with an [agent API key](/reference/cli/api-keys/) instead, passed as a bearer token: +Automation that runs without a person present, such as a CI pipeline or a headless server, can't complete the browser sign-in. For those cases, authenticate with an [agent API key](/agents/cli/oz-cli/api-keys/) instead, passed as a bearer token: ```json { diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 06fb556ff..88cd98f45 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -69,7 +69,7 @@ Warp Factories is designed for engineering teams with repeatable work that exten Warp Factories is built on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/), Warp's programmable system for running and coordinating agents at scale. A factory doesn't replace the platform; it assembles the platform's primitives into one standing workflow, so what you already know about cloud agents carries over: * **Runs** - Every factory agent executes as a [cloud agent run](/platform/), with the same run records and [session sharing](/platform/viewing-cloud-agent-runs/) as any other cloud agent. -* **Execution** - [Runners](/platform/runners/) provide the compute each agent works on, and eligible Enterprise teams can route execution to [managed self-hosted workers](/platform/self-hosting/). +* **Execution** - [Runners](/factories/runners/) provide the compute each agent works on, and eligible Enterprise teams can route execution to [managed self-hosted workers](/factories/self-hosting/). * **Agent configuration** - Each agent runs on a supported [harness](/platform/harnesses/) and model, with [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/) scoping what it can reach. * **Billing** - A factory's runs consume [platform credits](/support-and-community/plans-and-billing/platform-credits/) the same way as any other cloud agent run. diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index 049ce2780..d373db11e 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -27,7 +27,7 @@ flowchart LR C --> D["Warp-managed storage"] ``` -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. +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](/factories/deployment-patterns/) and [self-hosting security and networking](/platform/execution-security/) for the broader data model. 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. @@ -35,15 +35,15 @@ The diagram below maps those boundaries for self-hosted execution; factory runs ## Runners -A runner defines the operating system, architecture, sandbox image, and instance shape (vCPUs and memory) for a factory agent. The factory's [definition](/factories/factory-as-code/) supplies its repositories, setup commands, and secrets; the execution host determines whether that runner uses Warp-hosted or self-hosted compute. +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](/factories/runners/) for the available compute options. Declare runners as `runners/*.yaml` files. Every agent inherits `agentDefaults.runner`, and an agent or automation can override it. A self-hosted runner must match the worker's operating system and architecture. Warp provisions hosted runners within your plan limits; your team provisions and operates self-hosted compute. -See [cloud agent runner compute options](/platform/runners/) and [factory runner syntax](/factories/factory-as-code/#runnersnameyaml). +See [cloud agent runner compute options](/factories/runners/) and [factory runner syntax](/factories/factory-as-code/#runnersnameyaml). ## Choose an execution host -A factory runs its work on one of two execution hosts: Warp-hosted compute or a worker in the [managed self-hosting architecture](/platform/self-hosting/#managed-architecture). +A factory runs its work on one of two execution hosts: Warp-hosted compute or a worker in the [managed self-hosting architecture](/factories/self-hosting/#managed-architecture). | Decision area | Warp-hosted | Managed self-hosted | | --- | --- | --- | @@ -56,7 +56,7 @@ A factory runs its work on one of two execution hosts: Warp-hosted compute or a To route factory work to a managed self-hosted worker (an Enterprise feature): -1. **Deploy a worker** - Use the [self-hosting overview](/platform/self-hosting/) to choose a managed backend and review its requirements, then connect a worker that authenticates to Warp with an agent API key. Workers run on `linux/amd64` and `linux/arm64`, and the worker's platform determines which workloads it can run. +1. **Deploy a worker** - Review the [self-hosting requirements](/factories/self-hosting/), then connect a worker that authenticates to Warp with an agent API key. Workers run on `linux/amd64` and `linux/arm64`, and the worker's platform determines which workloads it can run. 2. **Pair it with a compatible runner** - Choose a runner that matches the worker's platform. 3. **Select the worker in the factory definition** - Set [`workerHost`](/factories/factory-as-code/) so the factory routes work to it. @@ -70,9 +70,9 @@ Factories use managed self-hosting, so Warp still orchestrates their runs. The w | Structure | How factory runs execute | What your team operates | Use it when | | --- | --- | --- | --- | -| **[Docker](/platform/self-hosting/managed-docker/)** (default) | In a separate Docker container on the worker host | The worker daemon, host, Docker daemon, images, capacity, and container policy | Docker is available and you want per-run container isolation without Kubernetes | -| **[Kubernetes](/platform/self-hosting/managed-kubernetes/)** | As a Kubernetes Job in the worker's namespace | The worker deployment, cluster, namespace RBAC, scheduling, admission policy, and capacity | Your team already operates Kubernetes or needs cluster-native policy and scheduling | -| **[Direct](/platform/self-hosting/managed-direct/)** | In a separate workspace directly on the worker host, sharing its OS and kernel | The worker daemon, host security, dependencies, capacity, and cleanup | A container runtime isn't available or runs need direct access to host resources | +| **[Docker](/factories/self-hosting/managed-docker/)** (default) | In a separate Docker container on the worker host | The worker daemon, host, Docker daemon, images, capacity, and container policy | Docker is available and you want per-run container isolation without Kubernetes | +| **[Kubernetes](/factories/self-hosting/managed-kubernetes/)** | As a Kubernetes Job in the worker's namespace | The worker deployment, cluster, namespace RBAC, scheduling, admission policy, and capacity | Your team already operates Kubernetes or needs cluster-native policy and scheduling | +| **[Direct](/factories/self-hosting/managed-direct/)** | In a separate workspace directly on the worker host, sharing its OS and kernel | The worker daemon, host security, dependencies, capacity, and cleanup | A container runtime isn't available or runs need direct access to host resources | All three structures keep execution on your infrastructure while Warp operates the control plane. @@ -124,8 +124,8 @@ Warp meters hosted compute, Warp-provided inference, and platform services. Mana ## Related pages -* [**Deployment patterns**](/platform/deployment-patterns/) - Compare Warp-hosted, managed self-hosted, and CLI-only execution. -* [**Self-hosting overview**](/platform/self-hosting/) - Choose a managed worker backend and follow its setup guide. -* [**Self-hosting security and networking**](/platform/self-hosting/security-and-networking/) - Review data boundaries, network egress, and backend-specific controls. +* [**Deployment patterns**](/factories/deployment-patterns/) - Compare Warp-hosted, managed self-hosted, and CLI-only execution. +* [**Managed self-hosting**](/factories/self-hosting/) - Choose a worker backend and follow its setup guide. +* [**Execution security**](/platform/execution-security/) - Review data boundaries, network egress, and backend-specific controls. * [**Bring Your Own LLM**](/enterprise/enterprise-features/bring-your-own-llm/) - Compare customer-owned inference options and provider support. * [**Enterprise security overview**](/enterprise/security-and-compliance/security-overview/) - Review data handling, ZDR, compliance, and access controls across Warp. diff --git a/src/content/docs/platform/runners.mdx b/src/content/docs/factories/runners.mdx similarity index 94% rename from src/content/docs/platform/runners.mdx rename to src/content/docs/factories/runners.mdx index 6692e4a06..c51a1c92f 100644 --- a/src/content/docs/platform/runners.mdx +++ b/src/content/docs/factories/runners.mdx @@ -32,7 +32,7 @@ A runner is the compute layer for a cloud agent run. When a run starts, Warp pro * **Environment** – Defines the workspace: Docker image, repositories, and setup commands. See [Environments](/platform/environments/). * **Runner** – Defines the compute: OS, architecture, instance shape (vCPUs and memory), and sandbox image. -* **Host** – Determines where execution happens (Warp-hosted or [self-hosted](/platform/self-hosting/) infrastructure). +* **Host** – Determines where execution happens (Warp-hosted or [self-hosted](/factories/self-hosting/) infrastructure). Each environment has a default runner. Specifying a runner for a run overrides that default for that run only. @@ -64,7 +64,7 @@ Each environment has a default runner. Specifying a runner for a run overrides t ## Managing runners with the CLI -Use the [{VARS.WARP_AGENT_CLI}](/reference/cli/) to create, list, update, and delete runners. Runner commands require an authenticated CLI—see the [CLI quickstart](/reference/cli/quickstart/) to get set up. +Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) to create, list, update, and delete runners. Runner commands require an authenticated CLI—see the [CLI quickstart](/agents/cli/oz-cli/quickstart/) to get set up. ### Create a runner @@ -145,4 +145,4 @@ You can also select a runner when [running orchestrated agents](/platform/orches * [Environments](/platform/environments/) – Define the repos, image, and setup commands an agent works with. * [Managing cloud agents](/platform/managing-cloud-agents/) – Start, monitor, and manage cloud agent runs. -* [{VARS.WARP_AGENT_CLI} reference](/reference/cli/) – Full command-line reference for runners and every other cloud agent command. +* [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/) – Full command-line reference for runners and every other cloud agent command. diff --git a/src/content/docs/factories/self-hosting/index.mdx b/src/content/docs/factories/self-hosting/index.mdx new file mode 100644 index 000000000..1883bffd8 --- /dev/null +++ b/src/content/docs/factories/self-hosting/index.mdx @@ -0,0 +1,55 @@ +--- +title: Managed self-hosting for Warp Factories +description: >- + Run Warp Factories on your own infrastructure with a managed worker for + Docker, Kubernetes, or direct-host execution. +sidebar: + label: "Managed self-hosting" +--- +import { VARS } from '@data/vars'; + +Managed self-hosting runs factory work on infrastructure you control. A worker connects to Warp, receives work from your factory, and executes it in Docker containers, Kubernetes Jobs, or directly on the worker host. Repository clones, build artifacts, and execution workspaces stay on your infrastructure. + +:::note +Managed self-hosting is available to Enterprise teams. [Contact sales](https://www.warp.dev/contact-sales) to enable it for your team. +::: + +<a id="managed-architecture"></a> + +## How managed self-hosting works + +Run the `oz-agent-worker` daemon on infrastructure that can reach your repositories and internal services. The worker connects outbound to the {VARS.WARP_AUTOMATION_PLATFORM}, waits for factory work, and runs each task using the backend you configure. + +A managed worker is the self-hosted execution option for a factory. [Unmanaged execution](/platform/unmanaged-execution/) runs `oz agent run` directly from your own CI or infrastructure, but it cannot run factory work. + +<a id="choosing-a-managed-backend"></a> + +## Choose a backend + +* **Docker** - Run each factory task in an isolated container. Start with the [Docker quickstart](/factories/self-hosting/quickstart/) or see the [Docker backend](/factories/self-hosting/managed-docker/) for registries, volumes, and runtime configuration. +* **Kubernetes** - Run each task as a Kubernetes Job in your cluster. See the [Kubernetes backend](/factories/self-hosting/managed-kubernetes/) for Helm installation, RBAC, and pod configuration. +* **Direct** - Run tasks directly on the worker host when a container runtime is not available. See the [Direct backend](/factories/self-hosting/managed-direct/) for isolation and workspace requirements. + +## Data and network boundaries + +Managed self-hosting moves execution to your infrastructure. Warp still provides the service that coordinates runs, stores session data, and routes inference requests. Review [execution security](/platform/execution-security/) before connecting a worker to internal repositories or services. + +The worker requires outbound HTTPS access to Warp and any repositories, registries, and services that its tasks use. It does not require inbound firewall access. + +<a id="routing-runs-to-self-hosted-workers"></a> + +## Configure a factory to use a worker + +Define the worker host and a compatible runner in your [factory definition](/factories/factory-as-code/). The factory dashboard shows each configured runner and the worker that executes its work. Use the [worker reference](/factories/self-hosting/reference/) to configure the worker process and the [Factory dashboard](/factories/factory-dashboard/) to inspect its runs. + +## Monitor and troubleshoot workers + +[Worker monitoring](/factories/self-hosting/monitoring/) exports OpenTelemetry metrics for worker health, capacity, and task throughput. If a worker cannot connect or tasks remain queued, use [self-hosting troubleshooting](/factories/self-hosting/troubleshooting/). + +## Related pages + +* [Docker quickstart](/factories/self-hosting/quickstart/) - Start a managed worker with Docker. +* [Factory runners](/factories/runners/) - Choose the compute configuration for factory work. +* [Infrastructure and security](/factories/infrastructure-and-security/) - Configure execution, inference, storage, and credentials. +* [Worker reference](/factories/self-hosting/reference/) - Look up worker flags and configuration fields. +* [Execution security](/platform/execution-security/) - Review data boundaries and network requirements. diff --git a/src/content/docs/platform/self-hosting/managed-direct.mdx b/src/content/docs/factories/self-hosting/managed-direct.mdx similarity index 77% rename from src/content/docs/platform/self-hosting/managed-direct.mdx rename to src/content/docs/factories/self-hosting/managed-direct.mdx index 555c668c0..47e9917d9 100644 --- a/src/content/docs/platform/self-hosting/managed-direct.mdx +++ b/src/content/docs/factories/self-hosting/managed-direct.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Run the `oz-agent-worker` daemon with the **Direct backend** — tasks execute directly on the worker host without Docker or Kubernetes. The {VARS.WARP_AUTOMATION_PLATFORM} still orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); the worker just runs the agent in a per-task workspace on its own filesystem. :::note -This page covers the [managed architecture](/platform/self-hosting/#managed-architecture) with the Direct backend. For container-based task isolation, see [Managed: Docker](/platform/self-hosting/managed-docker/) or [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/). For invocation-driven use cases, see [Unmanaged](/platform/self-hosting/unmanaged/). +This page covers the [managed architecture](/factories/self-hosting/#managed-architecture) with the Direct backend. For container-based task isolation, see [Managed: Docker](/factories/self-hosting/managed-docker/) or [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/). For invocation-driven use cases, see [Unmanaged](/platform/unmanaged-execution/). ::: ## When to use the Direct backend @@ -39,9 +39,9 @@ The Direct backend does not provide per-task container isolation. Each task runs * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). -* **The `oz-agent-worker` binary** installed on the worker host. The Direct backend runs the worker itself on the host rather than in a container, so install it via [Homebrew or a prebuilt binary](/platform/self-hosting/managed-docker/#install-and-run-the-worker). -* **The {VARS.WARP_AGENT_CLI}** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). -* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **The `oz-agent-worker` binary** installed on the worker host. The Direct backend runs the worker itself on the host rather than in a container, so install it via [Homebrew or a prebuilt binary](/factories/self-hosting/managed-docker/#install-and-run-the-worker). +* **The {VARS.WARP_AGENT_CLI}** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli). +* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. --- @@ -63,7 +63,7 @@ Pass `--backend direct`: oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" --backend direct ``` -Or with a [config file](/platform/self-hosting/reference/#config-file): +Or with a [config file](/factories/self-hosting/reference/#config-file): ```yaml worker_id: "my-worker" @@ -125,8 +125,8 @@ backend: ## Related pages -* [Self-hosted worker reference](/platform/self-hosting/reference/#direct-backend-config) — Full config schema for the Direct backend. -* [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and the backend decision guide. -* [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries and security considerations for the Direct backend. -* [Troubleshooting](/platform/self-hosting/troubleshooting/#direct-backend) — Common Direct-backend issues. +* [Self-hosted worker reference](/factories/self-hosting/reference/#direct-backend-config) — Full config schema for the Direct backend. +* [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and the backend decision guide. +* [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. +* [Security and networking](/platform/execution-security/) — Data boundaries and security considerations for the Direct backend. +* [Troubleshooting](/factories/self-hosting/troubleshooting/#direct-backend) — Common Direct-backend issues. diff --git a/src/content/docs/platform/self-hosting/managed-docker.mdx b/src/content/docs/factories/self-hosting/managed-docker.mdx similarity index 84% rename from src/content/docs/platform/self-hosting/managed-docker.mdx rename to src/content/docs/factories/self-hosting/managed-docker.mdx index 2ee278a35..436be6b59 100644 --- a/src/content/docs/platform/self-hosting/managed-docker.mdx +++ b/src/content/docs/factories/self-hosting/managed-docker.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Run the `oz-agent-worker` daemon with the **Docker backend** — the default managed path. Each agent task runs in an isolated Docker container spawned from the worker, with full orchestration by the {VARS.WARP_AUTOMATION_PLATFORM} (Slack, Linear, schedules, API, `oz agent run-cloud`). :::note -This page covers the [managed architecture](/platform/self-hosting/#managed-architecture) with the Docker backend. For the Kubernetes backend, see [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/). For host execution without a container runtime, see [Managed: Direct](/platform/self-hosting/managed-direct/). If you'd rather invoke agents yourself, see [Unmanaged](/platform/self-hosting/unmanaged/). +This page covers the [managed architecture](/factories/self-hosting/#managed-architecture) with the Docker backend. For the Kubernetes backend, see [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/). For host execution without a container runtime, see [Managed: Direct](/factories/self-hosting/managed-direct/). If you'd rather invoke agents yourself, see [Unmanaged](/platform/unmanaged-execution/). ::: ## When to use the Docker backend @@ -27,7 +27,7 @@ This page covers the [managed architecture](/platform/self-hosting/#managed-arch * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. -* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. :::caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. @@ -59,7 +59,7 @@ The `oz-agent-worker` is open source. See the [oz-agent-worker repository](https There are three ways to install and run the worker: as a Docker container, via Homebrew, or as a prebuilt binary from GitHub Releases. Docker is the recommended default. -The worker can be configured entirely via CLI flags, or via a YAML [config file](/platform/self-hosting/reference/#config-file) for more complex setups. +The worker can be configured entirely via CLI flags, or via a YAML [config file](/factories/self-hosting/reference/#config-file) for more complex setups. ### Option 1: Docker (recommended) @@ -104,7 +104,7 @@ You can run multiple workers with the same `--worker-id` for redundancy — the ## Docker backend configuration -The worker can take configuration either via CLI flags or via a YAML [config file](/platform/self-hosting/reference/#config-file). CLI flags take precedence over config file values. +The worker can take configuration either via CLI flags or via a YAML [config file](/factories/self-hosting/reference/#config-file). CLI flags take precedence over config file values. **Common CLI flags:** @@ -152,7 +152,7 @@ backend: - name: GITHUB_TOKEN # inherits from host environment ``` -Pass it with `--config-file config.yaml`. See the [self-hosted worker reference](/platform/self-hosting/reference/) for the full flag and config schema. +Pass it with `--config-file config.yaml`. See the [self-hosted worker reference](/factories/self-hosting/reference/) for the full flag and config schema. --- @@ -212,14 +212,14 @@ Sidecar images (the `oz` binary and dependencies) are pulled from public registr ## Routing runs to this worker -Once your Docker worker is connected, route tasks to it with `--host "<your-worker-id>"`. Routing is the same across all managed backends — see [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) for CLI, scheduled, integration, API, and web UI examples. +Once your Docker worker is connected, route tasks to it with `--host "<your-worker-id>"`. Routing is the same across all managed backends — see [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) for CLI, scheduled, integration, API, and web UI examples. --- ## Related pages -* [Self-hosting quickstart](/platform/self-hosting/quickstart/) — ~10-minute path to a running Docker worker. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — Full CLI flag and config file schema. +* [Self-hosting quickstart](/factories/self-hosting/quickstart/) — ~10-minute path to a running Docker worker. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — Full CLI flag and config file schema. * [Environments](/platform/environments/) — Define the Docker image, repos, and setup commands for tasks. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries, egress, and Docker socket considerations. -* [Troubleshooting](/platform/self-hosting/troubleshooting/) — Common issues with the Docker backend. +* [Security and networking](/platform/execution-security/) — Data boundaries, egress, and Docker socket considerations. +* [Troubleshooting](/factories/self-hosting/troubleshooting/) — Common issues with the Docker backend. diff --git a/src/content/docs/platform/self-hosting/managed-kubernetes.mdx b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx similarity index 86% rename from src/content/docs/platform/self-hosting/managed-kubernetes.mdx rename to src/content/docs/factories/self-hosting/managed-kubernetes.mdx index f13bb13b3..f1659e7ee 100644 --- a/src/content/docs/platform/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Deploy the `oz-agent-worker` daemon into a Kubernetes cluster using the included Helm chart. Each agent task runs as a **Kubernetes Job** in your cluster. The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); your cluster provides the compute, scheduling, and policy enforcement. :::note -This page covers the [managed architecture](/platform/self-hosting/#managed-architecture) with the Kubernetes backend. For the default Docker backend, see [Managed: Docker](/platform/self-hosting/managed-docker/). For host execution without a container runtime, see [Managed: Direct](/platform/self-hosting/managed-direct/). To route runs to a connected worker, see [Routing runs to this worker](/platform/self-hosting/managed-docker/#routing-runs-to-this-worker). +This page covers the [managed architecture](/factories/self-hosting/#managed-architecture) with the Kubernetes backend. For the default Docker backend, see [Managed: Docker](/factories/self-hosting/managed-docker/). For host execution without a container runtime, see [Managed: Direct](/factories/self-hosting/managed-direct/). To route runs to a connected worker, see [Routing runs to this worker](/factories/self-hosting/managed-docker/#routing-runs-to-this-worker). ::: ## When to use the Kubernetes backend @@ -39,7 +39,7 @@ This page covers the [managed architecture](/platform/self-hosting/#managed-arch * Allow the worker's namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. -* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. --- @@ -134,7 +134,7 @@ To scale horizontally, deploy multiple Helm releases with distinct worker IDs ra * `kubernetesBackend.extraAnnotations` — Additional annotations for task Jobs and Pods. * `kubernetesBackend.activeDeadlineSeconds` — Maximum task Job lifetime. * `kubernetesBackend.workspaceSizeLimit` — Size limit for workspace `emptyDir` volume. -* `kubernetesBackend.podTemplate` — Raw PodSpec YAML for task Jobs (same as `backend.kubernetes.pod_template` in the [config file](/platform/self-hosting/reference/#config-file)). +* `kubernetesBackend.podTemplate` — Raw PodSpec YAML for task Jobs (same as `backend.kubernetes.pod_template` in the [config file](/factories/self-hosting/reference/#config-file)). **API key Secret:** @@ -143,7 +143,7 @@ To scale horizontally, deploy multiple Helm releases with distinct worker IDs ra * `warp.apiKeySecret.name` — Name of the Secret containing `WARP_API_KEY`. Defaults to `oz-agent-worker`. * `warp.apiKeySecret.key` — Key within the Secret. Defaults to `WARP_API_KEY`. -See the [self-hosted worker reference](/platform/self-hosting/reference/#kubernetes-backend-config) for the full config file schema. +See the [self-hosted worker reference](/factories/self-hosting/reference/#kubernetes-backend-config) for the full config file schema. --- @@ -230,7 +230,7 @@ If your organization uses an external secrets manager (HashiCorp Vault, AWS Secr ## Setup and teardown commands -Use `kubernetesBackend.setupCommand` (Helm value) or `backend.kubernetes.setup_command` ([config file](/platform/self-hosting/reference/#kubernetes-backend-config)) to run a shell command before each task. Use `teardownCommand` / `teardown_command` for cleanup after the task finishes. These run inside the task Pod and are useful for workspace bootstrapping or post-run reporting. +Use `kubernetesBackend.setupCommand` (Helm value) or `backend.kubernetes.setup_command` ([config file](/factories/self-hosting/reference/#kubernetes-backend-config)) to run a shell command before each task. Use `teardownCommand` / `teardown_command` for cleanup after the task finishes. These run inside the task Pod and are useful for workspace bootstrapping or post-run reporting. --- @@ -250,7 +250,7 @@ With the default `metrics.exporter=prometheus`, the chart creates a `Service` wi To push metrics to an OTLP collector instead, set `metrics.exporter=otlp` and configure the endpoint via `metrics.extraEnv`. -See [Monitoring](/platform/self-hosting/monitoring/) for the full list of Helm values, the metric catalog, and sample PromQL queries. +See [Monitoring](/factories/self-hosting/monitoring/) for the full list of Helm values, the metric catalog, and sample PromQL queries. --- @@ -266,10 +266,10 @@ See [Monitoring](/platform/self-hosting/monitoring/) for the full list of Helm v ## Related pages -* [Self-hosted worker reference](/platform/self-hosting/reference/) — Full CLI flag and config file schema, including every Kubernetes backend field. -* [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and the backend decision guide. -* [Routing runs to this worker](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — Full CLI flag and config file schema, including every Kubernetes backend field. +* [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and the backend decision guide. +* [Routing runs to this worker](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. * [Environments](/platform/environments/) — Define the task image, repos, and setup commands. -* [Monitoring](/platform/self-hosting/monitoring/) — OpenTelemetry metrics, including Helm chart metrics values. -* [Security and networking](/platform/self-hosting/security-and-networking/) — RBAC, admission policies, and data boundaries. -* [Troubleshooting](/platform/self-hosting/troubleshooting/#kubernetes-backend) — Common Kubernetes-backend issues. +* [Monitoring](/factories/self-hosting/monitoring/) — OpenTelemetry metrics, including Helm chart metrics values. +* [Security and networking](/platform/execution-security/) — RBAC, admission policies, and data boundaries. +* [Troubleshooting](/factories/self-hosting/troubleshooting/#kubernetes-backend) — Common Kubernetes-backend issues. diff --git a/src/content/docs/platform/self-hosting/monitoring.mdx b/src/content/docs/factories/self-hosting/monitoring.mdx similarity index 92% rename from src/content/docs/platform/self-hosting/monitoring.mdx rename to src/content/docs/factories/self-hosting/monitoring.mdx index d9263e2bf..b479e1e28 100644 --- a/src/content/docs/platform/self-hosting/monitoring.mdx +++ b/src/content/docs/factories/self-hosting/monitoring.mdx @@ -78,7 +78,7 @@ The worker pushes metrics at the SDK's default interval. Configure the collector ## Helm chart configuration -The [Helm chart](/platform/self-hosting/managed-kubernetes/) includes built-in support for metrics. Enable metrics with `metrics.enabled=true`: +The [Helm chart](/factories/self-hosting/managed-kubernetes/) includes built-in support for metrics. Enable metrics with `metrics.enabled=true`: ```bash helm install oz-agent-worker ./charts/oz-agent-worker \ @@ -219,8 +219,8 @@ metrics: ## Related pages -* [Self-hosting overview](/platform/self-hosting/) — Architecture, decision guide, and Enterprise requirements. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags, config file schema, and metrics environment variables. -* [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Helm chart deployment, including metrics values. -* [Troubleshooting](/platform/self-hosting/troubleshooting/) — Diagnostics for metrics issues and other common problems. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Network egress and data boundaries. +* [Self-hosting overview](/factories/self-hosting/) — Architecture, decision guide, and Enterprise requirements. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags, config file schema, and metrics environment variables. +* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Helm chart deployment, including metrics values. +* [Troubleshooting](/factories/self-hosting/troubleshooting/) — Diagnostics for metrics issues and other common problems. +* [Security and networking](/platform/execution-security/) — Network egress and data boundaries. diff --git a/src/content/docs/platform/self-hosting/quickstart.mdx b/src/content/docs/factories/self-hosting/quickstart.mdx similarity index 73% rename from src/content/docs/platform/self-hosting/quickstart.mdx rename to src/content/docs/factories/self-hosting/quickstart.mdx index 67deebce4..f30a91205 100644 --- a/src/content/docs/platform/self-hosting/quickstart.mdx +++ b/src/content/docs/factories/self-hosting/quickstart.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Run your first cloud agent on your own infrastructure in ~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting. :::note -This quickstart sets up the [managed architecture](/platform/self-hosting/#managed-architecture), where the {VARS.WARP_AUTOMATION_PLATFORM} orchestrates the agent and your worker provides the compute. **Prefer a CLI-only path with no Docker requirement?** Jump to the [Unmanaged quickstart](/platform/self-hosting/unmanaged/#unmanaged-quickstart) to run `oz agent run` directly on any host. +This quickstart sets up the [managed architecture](/factories/self-hosting/#managed-architecture), where the {VARS.WARP_AUTOMATION_PLATFORM} orchestrates the agent and your worker provides the compute. **Prefer a CLI-only path with no Docker requirement?** Jump to the [Unmanaged quickstart](/platform/unmanaged-execution/#unmanaged-quickstart) to run `oz agent run` directly on any host. ::: --- @@ -20,8 +20,8 @@ This quickstart sets up the [managed architecture](/platform/self-hosting/#manag * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. -* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. -* **The {VARS.WARP_AGENT_CLI}** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). +* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. +* **The {VARS.WARP_AGENT_CLI}** (for routing a test run) — See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli). --- @@ -71,12 +71,12 @@ Open the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>, find the new task, and ## Next steps -* [Unmanaged quickstart](/platform/self-hosting/unmanaged/#unmanaged-quickstart) — ~5-minute CLI-only path: run `oz agent run` in your CI, Kubernetes pod, or dev box with no worker daemon and no Docker requirement. -* [Managed: Docker](/platform/self-hosting/managed-docker/) — Full Docker backend setup, including private registries, volume mounts, and runtime configuration. +* [Unmanaged quickstart](/platform/unmanaged-execution/#unmanaged-quickstart) — ~5-minute CLI-only path: run `oz agent run` in your CI, Kubernetes pod, or dev box with no worker daemon and no Docker requirement. +* [Managed: Docker](/factories/self-hosting/managed-docker/) — Full Docker backend setup, including private registries, volume mounts, and runtime configuration. * [Environments](/platform/environments/) — Define a repository, Docker image, and setup commands so agents have a reproducible workspace for every run. -* [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to route tasks from schedules, integrations (Slack, Linear), the API, and the {VARS.WEB_APP}. -* [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Deploy workers into a Kubernetes cluster with Helm. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — All CLI flags and config file options. +* [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to route tasks from schedules, integrations (Slack, Linear), the API, and the {VARS.WEB_APP}. +* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Deploy workers into a Kubernetes cluster with Helm. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — All CLI flags and config file options. ## Troubleshooting @@ -89,4 +89,4 @@ Verify your API key has team scope. Ensure the machine has outbound internet acc **Task stays queued and never runs**\ Confirm the `--host` value you passed to `oz agent run-cloud` matches your `--worker-id` exactly (case-sensitive). Check that the worker's team matches the team creating the task. -For more, see [Troubleshooting](/platform/self-hosting/troubleshooting/). +For more, see [Troubleshooting](/factories/self-hosting/troubleshooting/). diff --git a/src/content/docs/platform/self-hosting/reference.mdx b/src/content/docs/factories/self-hosting/reference.mdx similarity index 83% rename from src/content/docs/platform/self-hosting/reference.mdx rename to src/content/docs/factories/self-hosting/reference.mdx index c5ced7a2d..ae0e017a2 100644 --- a/src/content/docs/platform/self-hosting/reference.mdx +++ b/src/content/docs/factories/self-hosting/reference.mdx @@ -5,10 +5,10 @@ description: >- file schema for the Docker, Kubernetes, and Direct backends. --- -Reference for the `oz-agent-worker` daemon: CLI flags and the full YAML config-file schema for all three [managed backends](/platform/self-hosting/#managed-architecture) — Docker, Kubernetes, and Direct. For installation instructions, see [Install and run the worker](/platform/self-hosting/managed-docker/#install-and-run-the-worker). +Reference for the `oz-agent-worker` daemon: CLI flags and the full YAML config-file schema for all three [managed backends](/factories/self-hosting/#managed-architecture) — Docker, Kubernetes, and Direct. For installation instructions, see [Install and run the worker](/factories/self-hosting/managed-docker/#install-and-run-the-worker). :::note -This page documents every flag and config option. For installation and backend-specific setup walkthroughs, see [Managed: Docker](/platform/self-hosting/managed-docker/), [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/), or [Managed: Direct](/platform/self-hosting/managed-direct/). This reference applies to the managed architecture only; the [unmanaged architecture](/platform/self-hosting/unmanaged/) uses `oz agent run` instead. +This page documents every flag and config option. For installation and backend-specific setup walkthroughs, see [Managed: Docker](/factories/self-hosting/managed-docker/), [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/), or [Managed: Direct](/factories/self-hosting/managed-direct/). This reference applies to the managed architecture only; the [unmanaged architecture](/platform/unmanaged-execution/) uses `oz agent run` instead. ::: --- @@ -25,7 +25,7 @@ The following flags are available when starting the worker. ### Optional * `--config-file` — Path to a YAML [config file](#config-file). CLI flags take precedence over config file values. -* `--backend` — Backend type: `docker` (default), `kubernetes`, or `direct`. See [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) and [Managed: Direct](/platform/self-hosting/managed-direct/) for backend-specific setup. +* `--backend` — Backend type: `docker` (default), `kubernetes`, or `direct`. See [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) and [Managed: Direct](/factories/self-hosting/managed-direct/) for backend-specific setup. * `--log-level` — Log verbosity. One of `debug`, `info`, `warn`, `error`. Defaults to `info`. * `--no-cleanup` — Keep task containers, Kubernetes Jobs, or workspace directories after execution instead of removing them. Useful for debugging failed tasks. * `-v` / `--volumes` — Mount host directories into task containers (Docker backend only). Format: `HOST_PATH:CONTAINER_PATH` or `HOST_PATH:CONTAINER_PATH:MODE` (where MODE is `ro` or `rw`). Can be specified multiple times. @@ -185,22 +185,22 @@ The worker exports metrics over OpenTelemetry when configured. Exporter selectio * `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP collector endpoint (e.g., `http://otel-collector.observability.svc:4318`). * `OTEL_EXPORTER_OTLP_PROTOCOL` — OTLP protocol: `http/protobuf` (default) or `grpc`. -When deploying with the Helm chart, use the `metrics.*` values instead of setting these variables manually. See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide, metric catalog, Helm values, and sample PromQL queries. +When deploying with the Helm chart, use the `metrics.*` values instead of setting these variables manually. See [Monitoring](/factories/self-hosting/monitoring/) for the full setup guide, metric catalog, Helm values, and sample PromQL queries. --- ## Routing runs to self-hosted workers -Once a worker is running, route cloud agent runs to it with the `--host` flag or its equivalents. See [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) for examples across the CLI, schedules, integrations, the API, and the web UI. +Once a worker is running, route cloud agent runs to it with the `--host` flag or its equivalents. See [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) for examples across the CLI, schedules, integrations, the API, and the web UI. --- ## Related pages -* [Managed: Docker](/platform/self-hosting/managed-docker/) — Docker backend setup, connectivity, and private registries. -* [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Kubernetes backend setup, Helm chart, pod template, and operational notes. -* [Managed: Direct](/platform/self-hosting/managed-direct/) — Direct backend setup and workspace model. -* [Self-hosting overview](/platform/self-hosting/) — Architecture, decision guide, and Enterprise requirements. +* [Managed: Docker](/factories/self-hosting/managed-docker/) — Docker backend setup, connectivity, and private registries. +* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Kubernetes backend setup, Helm chart, pod template, and operational notes. +* [Managed: Direct](/factories/self-hosting/managed-direct/) — Direct backend setup and workspace model. +* [Self-hosting overview](/factories/self-hosting/) — Architecture, decision guide, and Enterprise requirements. * [Environments](/platform/environments/) — Define the Docker image, repos, and setup commands used by task containers. -* [Monitoring](/platform/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. -* [Troubleshooting](/platform/self-hosting/troubleshooting/) — Worker and task failure diagnostics. +* [Monitoring](/factories/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. +* [Troubleshooting](/factories/self-hosting/troubleshooting/) — Worker and task failure diagnostics. diff --git a/src/content/docs/platform/self-hosting/troubleshooting.mdx b/src/content/docs/factories/self-hosting/troubleshooting.mdx similarity index 86% rename from src/content/docs/platform/self-hosting/troubleshooting.mdx rename to src/content/docs/factories/self-hosting/troubleshooting.mdx index 2a53f2b64..e19638b85 100644 --- a/src/content/docs/platform/self-hosting/troubleshooting.mdx +++ b/src/content/docs/factories/self-hosting/troubleshooting.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Diagnostic guides for the `oz-agent-worker` daemon and its task execution. Use this page when a worker won't start, won't connect, tasks stay queued, or tasks fail. :::note -The steps below apply to the [managed architecture](/platform/self-hosting/#managed-architecture) (`oz-agent-worker` daemon). For [unmanaged](/platform/self-hosting/unmanaged/) deployments, refer to the documentation for the environment running `oz agent run` (e.g., GitHub Actions, Kubernetes). +The steps below apply to the [managed architecture](/factories/self-hosting/#managed-architecture) (`oz-agent-worker` daemon). For [unmanaged](/platform/unmanaged-execution/) deployments, refer to the documentation for the environment running `oz agent run` (e.g., GitHub Actions, Kubernetes). ::: --- @@ -46,7 +46,7 @@ The steps below apply to the [managed architecture](/platform/self-hosting/#mana **Fix:** -1. Install the {VARS.WARP_AGENT_CLI} on the worker host. See [Installing the CLI](/reference/cli/#installing-the-cli). +1. Install the {VARS.WARP_AGENT_CLI} on the worker host. See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli). 2. If the CLI isn't on `PATH`, set `oz_path` in the config file to the absolute path of the `oz` binary. --- @@ -63,7 +63,7 @@ The steps below apply to the [managed architecture](/platform/self-hosting/#mana 4. Check that no firewall rules are blocking WebSocket connections to `wss://oz.warp.dev`. 5. Increase log verbosity with `--log-level debug` to see connection details. -See [Security and networking](/platform/self-hosting/security-and-networking/#network-requirements) for the full list of outbound endpoints the worker needs. +See [Security and networking](/platform/execution-security/#network-requirements) for the full list of outbound endpoints the worker needs. --- @@ -93,7 +93,7 @@ See [Security and networking](/platform/self-hosting/security-and-networking/#ne 6. If using `metrics.podMonitor.create=true`, verify the `monitoring.coreos.com` CRDs are installed in the cluster. The `PodMonitor` resource requires the Prometheus Operator. 7. Restart the worker with `--log-level debug` and look for metrics-related error messages at startup. -See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide. +See [Monitoring](/factories/self-hosting/monitoring/) for the full setup guide. --- @@ -133,7 +133,7 @@ See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide. ### Docker backend (image pull) -1. If using a private registry, ensure Docker credentials are available to the worker. See [Private Docker registries](/platform/self-hosting/managed-docker/#private-docker-registries). +1. If using a private registry, ensure Docker credentials are available to the worker. See [Private Docker registries](/factories/self-hosting/managed-docker/#private-docker-registries). 2. Try pulling the image manually on the worker host: `docker pull <image>`. ### Kubernetes backend (image pull) @@ -150,7 +150,7 @@ See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide. ## Related pages -* [Self-hosting overview](/platform/self-hosting/) — Architecture and decision guide. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config schema, including every flag mentioned here. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Outbound endpoints the worker needs. +* [Self-hosting overview](/factories/self-hosting/) — Architecture and decision guide. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags and config schema, including every flag mentioned here. +* [Security and networking](/platform/execution-security/) — Outbound endpoints the worker needs. * [Agent Session Sharing](/agents/local-agents/session-sharing/) — Attach to running tasks to debug interactively. diff --git a/src/content/docs/platform/warp-hosting.mdx b/src/content/docs/factories/warp-hosting.mdx similarity index 94% rename from src/content/docs/platform/warp-hosting.mdx rename to src/content/docs/factories/warp-hosting.mdx index 3b7ee8010..11bc60b6c 100644 --- a/src/content/docs/platform/warp-hosting.mdx +++ b/src/content/docs/factories/warp-hosting.mdx @@ -52,4 +52,4 @@ Warp's hosted agents have network egress enabled by default. Outgoing requests m ## Related pages * [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) - Learn how Warp-hosted agents fit into the {VARS.WARP_AUTOMATION_PLATFORM}. -* [Self-hosting](/platform/self-hosting/) - Run agents on infrastructure you manage when execution must stay inside your network. +* [Self-hosting](/factories/self-hosting/) - Run agents on infrastructure you manage when execution must stay inside your network. diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index 6287a6f7d..af83db49c 100644 --- a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -18,7 +18,7 @@ Learn how to use the {VARS.WARP_AUTOMATION_PLATFORM} to build a triage agent tha * A Warp account ([sign up at warp.dev](https://www.warp.dev)) * A GitHub repository with Issues enabled * A cloud environment with access to your repository ([create one](/platform/environments/configuring-environments/#create-an-environment-with-guided-setup)) -* A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/reference/cli/api-keys/#from-the-web-app-recommended)) +* A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/agents/cli/oz-cli/api-keys/#from-the-web-app-recommended)) ## 1. Define your triage criteria @@ -71,7 +71,7 @@ oz agent run \ The `--share` flag generates a session link your team can use to inspect what the agent did. Review the session output to confirm that the labels and comments are what you expect. If something is wrong, refine the skill file and run again. -For the full reference of `oz agent run` flags, see the [{VARS.WARP_AGENT_CLI} reference](/reference/cli/). +For the full reference of `oz agent run` flags, see the [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/). ## 4. Deploy with GitHub Actions diff --git a/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx index 55234b5f7..b41efbb88 100644 --- a/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx @@ -28,8 +28,8 @@ Use this table to decide where an unattended agent should start. | Linear | An issue, comment, or assignment should start the agent. | [Linear integration](/platform/integrations/linear/) | Linear issue updates, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and the shared run session | | GitHub | Someone should delegate work by mentioning `@warp-agent` on an issue, pull request, or review comment. | [GitHub integration](/platform/integrations/github/) | GitHub thread comments, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and the shared run session | | GitHub Actions | A repository event, PR workflow, issue workflow, or CI failure should start the agent. | [GitHub Actions](/platform/integrations/github-actions/) | GitHub Actions logs, PR or issue comments, {VARS.WEB_APP}, and cloud agent runs | -| {VARS.WARP_AGENT_CLI} | You want to start a named cloud run from a terminal, script, or local automation. | [{VARS.WARP_AGENT_CLI}](/reference/cli/#running-agents-remotely-oz-agent-run-cloud) | CLI output, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and cloud agent session links | -| {VARS.API_SDK_NAME} | Your internal system should create, query, or monitor runs programmatically. | [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) | Your system, API results, {VARS.WEB_APP}, and run sessions | +| {VARS.WARP_AGENT_CLI} | You want to start a named cloud run from a terminal, script, or local automation. | [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/#running-agents-remotely-oz-agent-run-cloud) | CLI output, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and cloud agent session links | +| {VARS.API_SDK_NAME} | Your internal system should create, query, or monitor runs programmatically. | [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) | Your system, API results, {VARS.WEB_APP}, and run sessions | ## Choose a workflow pattern @@ -82,7 +82,7 @@ The GitHub Action can pass event data, prior step output, and repository context ### Start runs from scripts or internal systems -Use the [{VARS.WARP_AGENT_CLI}](/reference/cli/#running-agents-remotely-oz-agent-run-cloud) for scripts and terminal workflows. Use the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) when another service should create or monitor runs. This is useful for: +Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/#running-agents-remotely-oz-agent-run-cloud) for scripts and terminal workflows. Use the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) when another service should create or monitor runs. This is useful for: * internal dashboards * custom webhooks @@ -112,7 +112,7 @@ Unattended does not mean invisible. Use these surfaces to review what happened: * [{VARS.WEB_APP}](/platform/oz-web-app/) - View runs, schedules, run metadata, and session transcripts from a browser or mobile device. * [Managing cloud agents](/platform/managing-cloud-agents/) - Filter runs by source, status, day, creator, or trigger. * [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) - Inspect the prompt, plan, commands, logs, output, and follow-up messages where available. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - Query runs and build internal monitoring around status, runtime, or outcomes. +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Query runs and build internal monitoring around status, runtime, or outcomes. When a run creates a PR, include the cloud run link in the PR description or a comment. See [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) for a template. diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx index 6167264f4..55588cff3 100644 --- a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -31,7 +31,7 @@ The practical difference: * **Team visibility** — Any teammate can open a run in the {VARS.WEB_APP} to inspect the session transcript, steer a stuck agent, or pick up where the agent left off. * **Scale without contention** — Multiple triage runs can execute in parallel without fighting over a shared dev box, local git checkouts, or CPU. -See [Deployment patterns](/platform/deployment-patterns) for a full comparison of {VARS.WARP_AUTOMATION_PLATFORM}-hosted, CLI-based, and self-hosted execution patterns. +See [Deployment patterns](/factories/deployment-patterns) for a full comparison of {VARS.WARP_AUTOMATION_PLATFORM}-hosted, CLI-based, and self-hosted execution patterns. ## 1. Set up a cloud environment @@ -67,7 +67,7 @@ With GitHub Actions, your factory already has event-based triggers. The {VARS.WA * **Slack** — Teammates can kick off a run by mentioning `@warp` in a Slack thread. Useful for one-off requests that don't need the full label workflow. See [Slack integration](/platform/integrations/slack). * **Linear** — When an issue in Linear reaches a specific status, a cloud agent run starts automatically. Useful for teams that track work in Linear rather than GitHub Issues. See [Linear integration](/platform/integrations/linear). * **Scheduled agents** — For the outer improvement loop (which runs on a cadence rather than an event), use a scheduled cloud agent. See [Scheduled agents](/platform/triggers/scheduled-agents). -* **{VARS.API_SDK_NAME}** — For custom triggers — webhooks, internal dashboards, other events — use the [{VARS.API_SDK_NAME}](/reference/api-and-sdk) to start runs programmatically. +* **{VARS.API_SDK_NAME}** — For custom triggers — webhooks, internal dashboards, other events — use the [{VARS.API_SDK_NAME}](/factories/api-and-sdk) to start runs programmatically. ## 4. Monitor factory runs @@ -100,5 +100,5 @@ See [Multi-agent orchestration](/platform/orchestration) for fan-out, sharding, * [Infrastructure and security](/factories/infrastructure-and-security/) — The environment, runner, and credential model behind the concerns you configured by hand here. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop on a schedule. * [Environments](/platform/environments) — Full reference for cloud agent environments. -* [Deployment patterns](/platform/deployment-patterns) — Choose the right architecture for your team. -* [Self-hosting](/platform/self-hosting) — Run cloud agent workers on your own infrastructure when code must stay on-premises. +* [Deployment patterns](/factories/deployment-patterns) — Choose the right architecture for your team. +* [Self-hosting](/factories/self-hosting) — Run cloud agent workers on your own infrastructure when code must stay on-premises. diff --git a/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx b/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx index b2eaa33d0..c15261df9 100644 --- a/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx +++ b/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx @@ -13,8 +13,8 @@ Build a Mattermost bot that sends work to a [Warp factory](/factories/) and post ## Prerequisites * **A Warp Factories factory** - [Set up a factory](/factories/quickstart/) before starting; this guide dispatches work to an existing factory rather than creating one. -* **A Warp API key** - Create an [agent API key](/reference/cli/api-keys/#personal-vs-agent-keys) rather than a personal key, so the bot's requests aren't tied to your individual account. -* **A Mattermost bot account and access token** - Create one from your Mattermost System Console under **Integrations** > **Bot Accounts**, and generate a personal access token for it. Mattermost's own [bot accounts documentation](https://developers.mattermost.com/integrate/reference/bot-accounts/) covers the exact steps, since they vary by Mattermost version and hosting setup. +* **A Warp API key** - Create an [agent API key](/agents/cli/oz-cli/api-keys/#personal-vs-agent-keys) rather than a personal key, so the bot's requests aren't tied to your individual account. +* **A Mattermost bot account and access token** - Create one from your Mattermost System Console under **Integrations** > **Bot Accounts**, and generate a personal access token for it. Mattermost's own [bot accounts documentation](https://developers.mattermost.com/integrate/factories/developer-tools/bot-accounts/) covers the exact steps, since they vary by Mattermost version and hosting setup. * **The {VARS.API_SDK_NAME} Python SDK** - Install it with `pip install oz-agent-sdk`. If you're working in another language, the [factory API page](/factories/factory-api/) shows the equivalent REST calls. ## 1. Store your credentials @@ -169,4 +169,4 @@ You've built a Mattermost bot that discovers a factory by name, dispatches tasks * [Use the factory API](/factories/factory-api/) - The full discover-and-dispatch reference this guide builds on. * [Connect your factory](/factories/connect-your-factory/) - Compare this custom integration against Warp's built-in intake sources. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - Full endpoint reference for run status, follow-ups, and cancellation. +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Full endpoint reference for run status, follow-ups, and cancellation. diff --git a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx index 44546dac6..818a9132a 100644 --- a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx +++ b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx @@ -30,7 +30,7 @@ Use this guide to choose the right setup path, then jump to the source docs for | Local Warp agent | You are working interactively in Warp and want the agent to use tools from your machine or desktop-authenticated services. | Warp MCP settings, Warp Drive MCP servers, `.warp/.mcp.json`, or provider config files. | [Model Context Protocol (MCP)](/agents/capabilities/mcp/) | | Third-party CLI agent in Warp | You run Claude Code, Codex, OpenCode, or another CLI agent in Warp and want shared MCP config across tools. | File-based MCP config that Warp can detect and approve. | [File-based MCP servers](/agents/capabilities/mcp/#file-based-mcp-servers) | | Cloud agent run | The agent runs in a cloud environment from Slack, Linear, schedules, GitHub Actions, the CLI, or the API. | `--mcp`, an agent config file, or a Warp-shared MCP UUID. | [MCP Servers for cloud agents](/platform/mcp/) | -| Repeatable automation | You need the same MCP tools every time a scheduled agent, integration, or CI workflow runs. | Agent config files plus [Agent Secrets](/platform/secrets/) for credentials. | [MCP servers (CLI reference)](/reference/cli/mcp-servers/) | +| Repeatable automation | You need the same MCP tools every time a scheduled agent, integration, or CI workflow runs. | Agent config files plus [Agent Secrets](/platform/secrets/) for credentials. | [MCP servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) | ## Common MCP workflows @@ -80,7 +80,7 @@ Then pass the UUID to an agent run: oz agent run-cloud --mcp "<MCP_SERVER_UUID>" --prompt "Summarize the latest production incidents" ``` -See [MCP servers (CLI reference)](/reference/cli/mcp-servers/) for all `--mcp` formats. +See [MCP servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) for all `--mcp` formats. ## Local MCP setup paths @@ -136,5 +136,5 @@ Before giving an agent tool access through MCP: * [Model Context Protocol (MCP)](/agents/capabilities/mcp/) - Configure MCP servers for local agents in the Warp app. * [MCP Servers for cloud agents](/platform/mcp/) - Configure MCP servers for cloud runs and automation. -* [MCP servers (CLI reference)](/reference/cli/mcp-servers/) - Use `--mcp` with UUIDs, inline JSON, or files. +* [MCP servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) - Use `--mcp` with UUIDs, inline JSON, or files. * [Agent Secrets](/platform/secrets/) - Store credentials for cloud agent runs. \ No newline at end of file diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 8565714d8..d7ae36460 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,129 +1,48 @@ --- -title: Getting started with Warp +title: Warp products description: >- - Get started with Warp, the Agentic Development Environment, and the - {{WARP_AUTOMATION_PLATFORM}}, which orchestrates cloud agents at scale. + Warp combines a modern terminal, coding agents, cloud automation, and + software factories for teams that build and ship software. sidebar: - label: Getting started with Warp + label: Warp products --- import { VARS } from '@data/vars'; -import VideoEmbed from '@components/VideoEmbed.astro'; -Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that combines a modern, high-performance terminal with powerful agents to help you build, test, deploy, and debug code. Agents in Warp are powered by the **{VARS.WARP_AUTOMATION_PLATFORM}**, which orchestrates agents locally or in the cloud at scale. - -<figure> -![Two panels side by side: Warp, a modern terminal built for coding with agents, and Warp Factories, open infrastructure for building cloud software factories](../../assets/terminal/warp-factories-welcome.png) -<figcaption>Warp and Warp Factories in the Agentic Development Environment.</figcaption> -</figure> - ---- +Warp is an [open source](https://github.com/warpdotdev/warp) development environment for working in the terminal and with coding agents. Use Warp for interactive coding, run the Warp Agent from any terminal, automate recurring work in the cloud, or connect a team workflow to Warp Factories. ## Warp -Warp is where you work — a fast, modern terminal built for coding with agents. - -**Key capabilities:** - -* [**Terminal and Agent modes**](/agents/local-agents/interacting-with-agents/terminal-and-agent-modes/): Switch between a clean terminal for commands and a dedicated conversation view for multi-turn agent workflows. -* [**Modern terminal UX**](/terminal/editor/): Cursor movement, block-based navigation, multi-line editing, syntax highlighting, and rich completions. Built with Rust for high performance. -* [**Code editor**](/code/overview/): File tree, code editor with LSP support, and interactive code review experience. -* [**Third-party CLI agents**](/agents/cli-agents/overview/): Run third-party CLI agents like Claude Code, Codex, and OpenCode with the agent toolbelt — rich input, code review, notifications, and more. - -<VideoEmbed url="https://www.youtube.com/watch?v=xhkoXsE9Wqc" title="Deep dive into Warp's core features" /> - ---- - -## Three ways to use the Warp Agent - -The **Warp Agent** writes and edits code, debugs issues, runs commands, and works through multi-step tasks. You reach the same agent three ways, and your account, rules, skills, and model access carry across all of them. - -### In the Warp app - -Real-time, interactive coding assistance alongside your terminal. - -* Write and refactor code across your codebase -* Debug issues and fix errors -* Run commands and interpret results -* Plan and execute multi-step tasks - -You stay in control. Review changes, steer the agent mid-task, and approve actions before they execute. - -→ [Get started with agents in Warp](/agents/) - -### In any terminal, with the Warp Agent CLI - -The Warp Agent CLI is a standalone terminal program that runs the same agent without the Warp app. Run the `warp` command to start a conversation in whichever terminal you already use, over SSH, or on a machine where Warp isn't installed. - -→ [Get started with the Warp Agent CLI](/agents/cli/quickstart/) - -### In the cloud, as a cloud agent - -Cloud agents run in the background on Warp's infrastructure (or your own) for automation at scale. - -* **Triggers**: React to events from Slack, Linear, GitHub, or custom webhooks -* **Schedules**: Run recurring tasks like dependency updates or dead code removal -* **Parallelism**: Run many agents concurrently across repos or tasks -* **Observability**: Every run is tracked, auditable, and shareable with your team +Warp is the desktop terminal for running commands, editing code, and working with agents in a local checkout. -Cloud agents are ideal for work that doesn't need your immediate attention, like PR reviews, issue triage, routine maintenance, and integration-driven workflows. +* [Modern terminal editing](/terminal/editor/) - Edit commands, navigate blocks, manage tabs, and customize your terminal. +* [Code](/code/overview/) - Review agent changes and edit files alongside your terminal. +* [Agents](/agents/) - Start and steer coding agents in the Warp app. -→ [Learn about cloud agents](/platform/) +## Warp Agent -### The platform behind them +The Warp Agent helps you investigate issues, edit code, run commands, and complete multi-step work. Use it in the Warp app or from the [Warp Agent CLI](/agents/cli/), which runs the same agent in any terminal. -The **{VARS.WARP_AUTOMATION_PLATFORM}** is Warp's programmable system for running and coordinating agents at scale. It provides the environments, triggers, integrations, orchestration, and observability that cloud agents run on, plus a CLI, API, and SDK. +## Automation Platform -→ [Learn about the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) +The {VARS.WARP_AUTOMATION_PLATFORM} runs cloud agents from triggers, schedules, integrations, and APIs. Use it for background work such as issue triage, pull request review, and recurring maintenance. ---- - -## Repeatable development workflows with Warp Factories - -A single cloud agent handles one task. **Warp Factories**, now in Early Access, lets your team run a software factory: a repeatable process where cloud agents triage, spec, implement, review, and verify work, and humans approve key decisions. - -→ [Learn about Warp Factories](/factories/) or [request access](https://www.warp.dev/factories/request-access) - ---- +* [Cloud agents](/platform/) - Run background agent work in the cloud. +* [Automation Platform](/platform/overview/) - Configure environments, integrations, orchestration, and shared agent settings. -## How they work together +## Warp Factories -Warp and the {VARS.WARP_AUTOMATION_PLATFORM} provide a unified experience across local and cloud development: +Warp Factories is available in Early Access. A factory turns incoming engineering work into a repeatable, multi-stage workflow with specialized agents, review points, and measurable outcomes. -* **Same agent, anywhere**: Whether you're working in the Warp app, in another terminal through the Warp Agent CLI, or running agents in the cloud, you're using the same underlying agent capabilities. -* **Seamless handoff**: Start a task in the cloud and take over locally in Warp when you want hands-on control, without losing progress or context. -* **Shared context**: [Warp Drive](/knowledge-and-collaboration/warp-drive/), [Rules](/agents/capabilities/rules/), and [MCP servers](/agents/capabilities/mcp/) work across both local and cloud agents, so your team's knowledge and tools are always available. -* **Team collaboration**: Share agent sessions, review agents' actions, and steer running tasks, regardless of who started them. +* [Warp Factories overview](/factories/) - Learn how a factory receives, routes, and tracks work. +* [Factory quickstart](/factories/quickstart/) - Create a factory and send it its first work item. ---- - -## Multi-model support - -The {VARS.WARP_AUTOMATION_PLATFORM} is multi-model by design. You can [choose your preferred LLM](/agents/inference/model-choice/) from a curated set of top models. - ---- +## How the products work together -## Open source - -Warp's client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE-AGPL). The source lives at [`warpdotdev/warp`](https://github.com/warpdotdev/warp), where you can read the code, file issues, and contribute alongside the Warp team. Development happens in the open with an agent-first workflow managed by the {VARS.WARP_AUTOMATION_PLATFORM}. - -→ [Contributing to Warp](/support-and-community/community/contributing/) explains how to file issues, claim work, and ship code or themes. - ---- - -## Privacy and security - -Warp is **SOC 2 compliant** and has **Zero Data Retention** policies with all contracted LLM providers. No customer AI data is retained, stored, or used for training. - -Warp's AI features can be globally disabled in **Settings** > **Agents** > **Warp Agent**. - -→ [Read more about data privacy](https://www.warp.dev/privacy) - ---- +Use Warp and the Warp Agent for interactive development. Use the Automation Platform for background agents and shared cloud configuration. Use Warp Factories when your team needs a standing workflow to route, review, and improve work across repositories. ## Next steps -* [**Quickstart**](/quickstart/): Get Warp installed and start coding -* [**Agents overview**](/agents/): What the Warp Agent does, how to control it, and where to run it -* [**Warp Agent CLI**](/agents/cli/): Run the Warp Agent in any terminal -* [**Cloud Agents overview**](/platform/): Set up background automation -* [**{VARS.WARP_AUTOMATION_PLATFORM}**](/platform/overview/): Learn about the CLI, API, SDK, and infrastructure +* [Install Warp](/quickstart/) - Set up Warp and start coding. +* [Start an agent conversation](/agents/) - Work with the Warp Agent in a local checkout. +* [Run cloud agents](/platform/quickstart/) - Set up background automation. +* [Set up a factory](/factories/quickstart/) - Route engineering work through Warp Factories. diff --git a/src/content/docs/platform/agents.mdx b/src/content/docs/platform/agents.mdx index f0bd0cf38..7ac6aa772 100644 --- a/src/content/docs/platform/agents.mdx +++ b/src/content/docs/platform/agents.mdx @@ -14,22 +14,22 @@ Every team starts with a default cloud agent, which is what runs when an automat ## How cloud agents get triggered -A run executes as a cloud agent when it's authenticated with an [agent API key](/reference/cli/api-keys/) or when an agent is explicitly selected; otherwise it runs as the calling user. The triggers that can run as a cloud agent are: +A run executes as a cloud agent when it's authenticated with an [agent API key](/agents/cli/oz-cli/api-keys/) or when an agent is explicitly selected; otherwise it runs as the calling user. The triggers that can run as a cloud agent are: * **Schedules** — Cron-style recurring runs. See [Scheduled agents](/platform/triggers/scheduled-agents/). * **Integrations** — Slack mentions, Linear issue updates, GitHub Actions workflow steps. See [Integrations](/platform/integrations/). -* **API and SDK** — Programmatic runs from your own backend, scripts, or webhooks via the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). -* **CLI** — `oz agent run-cloud` from a developer machine, CI pipeline, or self-hosted worker. See the [{VARS.WARP_AGENT_CLI}](/reference/cli/). +* **API and SDK** — Programmatic runs from your own backend, scripts, or webhooks via the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/). +* **CLI** — `oz agent run-cloud` from a developer machine, CI pipeline, or self-hosted worker. See the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/). Each run is tracked in the <a href={`${VARS.WEB_APP_URL}/runs`}>{VARS.DASHBOARD}</a> with its trigger source, the environment it ran in, and the full transcript. ## Agent API keys -Most automation triggers authenticate using an **agent API key** — a credential that runs as a cloud agent on your team rather than as an individual user. See [API keys](/reference/cli/api-keys/) for how personal and agent keys differ, and how to create one. +Most automation triggers authenticate using an **agent API key** — a credential that runs as a cloud agent on your team rather than as an individual user. See [API keys](/agents/cli/oz-cli/api-keys/) for how personal and agent keys differ, and how to create one. ## Service accounts -In the CLI and REST API, a cloud agent is represented as a **service account**. `oz whoami` reports `service_account:<uid>` when the CLI is authenticated as a service account, and [`oz federate issue-token`](/reference/cli/federate/) emits the same form in OIDC token subjects. +In the CLI and REST API, a cloud agent is represented as a **service account**. `oz whoami` reports `service_account:<uid>` when the CLI is authenticated as a service account, and [`oz federate issue-token`](/agents/cli/oz-cli/federate/) emits the same form in OIDC token subjects. ## Managing cloud agents @@ -75,8 +75,8 @@ Cloud agents — and individual runs — can also be granted specific capabiliti * [Triggers](/platform/triggers/) - How schedules, integrations, and API calls invoke cloud agents. * [Environments](/platform/environments/) - The runtime context (Docker image, repos, setup commands) a cloud agent uses. * [Multi-agent orchestration](/platform/orchestration/) - Coordinate a parent cloud agent and its children across local and cloud runs. -* [API keys](/reference/cli/api-keys/) - Create personal and agent API keys. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - Programmatic access to the cloud agent endpoints. -* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run. +* [API keys](/agents/cli/oz-cli/api-keys/) - Create personal and agent API keys. +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Programmatic access to the cloud agent endpoints. +* [Federated identity tokens](/agents/cli/oz-cli/federate/) - Issue OIDC tokens from inside a run. * [{VARS.WEB_APP}](/platform/oz-web-app/) - Manage cloud agents and inspect their runs in the web UI. * [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls. diff --git a/src/content/docs/platform/environments.mdx b/src/content/docs/platform/environments.mdx index cf5f158c2..81f12d6d7 100644 --- a/src/content/docs/platform/environments.mdx +++ b/src/content/docs/platform/environments.mdx @@ -13,7 +13,7 @@ Environments describe _how_ an agent executes a task, not _what_ it does. They g An environment groups the runtime configuration for a cloud agent run: -* **Docker image** - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a [`default_image`](/platform/self-hosting/managed-kubernetes/) can run without a separate environment. +* **Docker image** - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a [`default_image`](/factories/self-hosting/managed-kubernetes/) can run without a separate environment. * **Repositories** - One or more repos that the agent clones into its workspace. * **Setup commands** - Commands that prepare the workspace, such as dependency installation, builds, or code generation. * **Environment variables** - Runtime values that you set in the Docker image or container configuration. @@ -25,7 +25,7 @@ Together, these settings create a fresh workspace for each run. Warp provides [p When the {VARS.WARP_AUTOMATION_PLATFORM} starts a cloud agent run, it combines the environment with a host, an agent profile, and task-specific context. Each part serves a distinct purpose: -* **Host** - Determines where the run executes. Choose [Warp-hosted](warp-hosting/) infrastructure or [self-hosted](/platform/self-hosting/) runners. +* **Host** - Determines where the run executes. Choose [Warp-hosted](/factories/warp-hosting/) infrastructure or [self-hosted](/factories/self-hosting/) runners. * **Agent Profiles** - Set the agent's permissions, model choice, and defaults. See [Agent Profiles](/agents/capabilities/agent-profiles-permissions/). * **Rules** - Provide instructions that guide agent responses and decisions. See [Rules](/agents/capabilities/rules/). * **MCP servers** - Connect agents to external tools and data. See [MCP servers](/platform/mcp/). @@ -52,5 +52,5 @@ Cloud agents run as a non-root user inside the container. See [configuring conta * [Configuring cloud agent environments](environments/configuring-environments/) to create, configure, and manage environments. * [Troubleshooting cloud agent environments](environments/troubleshooting-environments/) to fix setup, authorization, permissions, and image failures. -* [Runners](/platform/runners/) to configure the compute that hosts environments. -* [Deployment patterns](/platform/deployment-patterns/) to choose between Warp-hosted and self-hosted execution. +* [Runners](/factories/runners/) to configure the compute that hosts environments. +* [Deployment patterns](/factories/deployment-patterns/) to choose between Warp-hosted and self-hosted execution. diff --git a/src/content/docs/platform/environments/configuring-environments.mdx b/src/content/docs/platform/environments/configuring-environments.mdx index 1f20570ab..691e3686c 100644 --- a/src/content/docs/platform/environments/configuring-environments.mdx +++ b/src/content/docs/platform/environments/configuring-environments.mdx @@ -162,4 +162,4 @@ Add `--force` to skip confirmation checks for environments used by integrations. * [Cloud agent environments](/platform/environments/) for the conceptual overview. * [Troubleshooting cloud agent environments](troubleshooting-environments/) to resolve setup and runtime problems. -* [Integration setup](/reference/cli/integration-setup/) to configure end-to-end integration workflows. +* [Integration setup](/agents/cli/oz-cli/integration-setup/) to configure end-to-end integration workflows. diff --git a/src/content/docs/platform/environments/troubleshooting-environments.mdx b/src/content/docs/platform/environments/troubleshooting-environments.mdx index 2eab2ceea..fcf6e5f27 100644 --- a/src/content/docs/platform/environments/troubleshooting-environments.mdx +++ b/src/content/docs/platform/environments/troubleshooting-environments.mdx @@ -7,7 +7,7 @@ import { VARS } from '@data/vars'; ## Setup commands fail on a fresh container -Setup commands run in a new container on every cloud agent run. Commands that depend on existing directories, caches, or cloned repositories can fail with [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). +Setup commands run in a new container on every cloud agent run. Commands that depend on existing directories, caches, or cloned repositories can fail with [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/). 1. Update the setup commands so they work in a fresh container. For example, use `mkdir -p .cache` instead of `mkdir .cache`. 2. Use lockfile-based dependency commands such as `npm ci` when your project supports them. @@ -27,7 +27,7 @@ Cloud agents need GitHub authorization to clone private repositories. This error 1. Authorize GitHub for the user who starts the run. 2. For an automated workflow with an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). -3. Follow [GitHub authorization setup](/reference/cli/integration-setup/#how-github-authorization-works) for the full flow. +3. Follow [GitHub authorization setup](/agents/cli/oz-cli/integration-setup/#how-github-authorization-works) for the full flow. ## "VM failed before the agent could run" @@ -41,4 +41,4 @@ This error often means the Docker image is incompatible with the agent runtime. * [Cloud agent environments](/platform/environments/) for the environment model and when to use one. * [Configuring cloud agent environments](configuring-environments/) to create, update, and manage environments. -* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the API error reference. +* [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the API error reference. diff --git a/src/content/docs/platform/self-hosting/security-and-networking.mdx b/src/content/docs/platform/execution-security.mdx similarity index 94% rename from src/content/docs/platform/self-hosting/security-and-networking.mdx rename to src/content/docs/platform/execution-security.mdx index 8935cab8d..ae07b84dd 100644 --- a/src/content/docs/platform/self-hosting/security-and-networking.mdx +++ b/src/content/docs/platform/execution-security.mdx @@ -8,7 +8,7 @@ description: >- Self-hosting uses a split-plane architecture. Understanding which data stays on your infrastructure and which data routes through Warp is critical for security evaluation. This page summarizes the data model, network egress requirements, and backend-specific security considerations for self-hosted workers. :::note -This page applies to both the [managed](/platform/self-hosting/#managed-architecture) and [unmanaged](/platform/self-hosting/unmanaged/) architectures. Backend-specific notes call out Docker-, Kubernetes-, and Direct-only considerations. +This page applies to both the [managed](/factories/self-hosting/#managed-architecture) and [unmanaged](/platform/unmanaged-execution/) architectures. Backend-specific notes call out Docker-, Kubernetes-, and Direct-only considerations. ::: ## Data boundaries @@ -114,8 +114,8 @@ 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. +* [Managed self-hosting](/factories/self-hosting/) — Install and operate a managed worker for a factory. * [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. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags and config schema, including every security-relevant option. diff --git a/src/content/docs/platform/faqs.mdx b/src/content/docs/platform/faqs.mdx index ed1fe3d3e..1f3337094 100644 --- a/src/content/docs/platform/faqs.mdx +++ b/src/content/docs/platform/faqs.mdx @@ -61,7 +61,7 @@ No. By default, cloud agents run as a dedicated non-root `agent` user (UID/GID 1 The cloud agents platform supports self-hosting the **agent sandbox** (the execution environment) on your own infrastructure. The **control plane**—which handles orchestration, tracking, and auditability—remains Warp-managed and is not self-hosted. -Self-hosted execution is available on **Enterprise** plans. See [Self-hosting](/platform/self-hosting/) and [Deployment patterns](/platform/deployment-patterns/) for details. +Self-hosted execution is available on **Enterprise** plans. See [Self-hosting](/factories/self-hosting/) and [Deployment patterns](/factories/deployment-patterns/) for details. :::note Self-serve [Bring Your Own API Key (BYOK)](/agents/inference/bring-your-own-api-key/) does not apply to cloud agents. Keys you add yourself are stored locally on your device and can't be passed to cloud-hosted or self-hosted agent runs, so those runs consume [Warp credits](/support-and-community/plans-and-billing/credits/). @@ -209,11 +209,11 @@ With self-hosting, repositories are cloned and stored only on your infrastructur * **Execution plane (your infrastructure)** — Repository clones, build artifacts, runtime secrets, and container filesystem state stay on the machines you control. * **Control plane (Warp-hosted)** — Session transcripts (which include code context from agent interactions), orchestration metadata, and LLM inference route through Warp's backend under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or use it for model training. -See [Self-hosting](/platform/self-hosting/) for deployment options and [Security Overview](/enterprise/security-and-compliance/security-overview/) for full details. +See [Self-hosting](/factories/self-hosting/) for deployment options and [Security Overview](/enterprise/security-and-compliance/security-overview/) for full details. ### Can I use `oz agent run` in CI or existing runners? -Yes. The [unmanaged architecture](/platform/self-hosting/unmanaged/) is designed exactly for this. Run `oz agent run` in any environment where you can execute a CLI command — GitHub Actions, Jenkins, Buildkite, Kubernetes pods, or custom orchestrators. This is how the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) GitHub Action works. The agent runs locally on the runner and its session is tracked on Warp's backend for observability. +Yes. The [unmanaged architecture](/platform/unmanaged-execution/) is designed exactly for this. Run `oz agent run` in any environment where you can execute a CLI command — GitHub Actions, Jenkins, Buildkite, Kubernetes pods, or custom orchestrators. This is how the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) GitHub Action works. The agent runs locally on the runner and its session is tracked on Warp's backend for observability. ### Can self-hosted agents access services behind a VPN? @@ -221,7 +221,7 @@ Yes. Since self-hosted agents run on your infrastructure, they inherit your netw ### Does self-hosting work with GitLab or other non-GitHub SCMs? -Self-hosted agents can use any SCM accessible from your infrastructure. With the [unmanaged architecture](/platform/self-hosting/unmanaged/), agents run directly on your host and use whatever Git configuration and SCM access is already available. With the [managed architecture](/platform/self-hosting/#managed-architecture), automatic environment setup currently focuses on GitHub, but you can configure access to other SCMs via volume mounts, environment variables, setup commands, or Kubernetes Secrets (when using the [Kubernetes backend](/platform/self-hosting/managed-kubernetes/)). See the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides for step-by-step instructions. +Self-hosted agents can use any SCM accessible from your infrastructure. With the [unmanaged architecture](/platform/unmanaged-execution/), agents run directly on your host and use whatever Git configuration and SCM access is already available. With the [managed architecture](/factories/self-hosting/#managed-architecture), automatic environment setup currently focuses on GitHub, but you can configure access to other SCMs via volume mounts, environment variables, setup commands, or Kubernetes Secrets (when using the [Kubernetes backend](/factories/self-hosting/managed-kubernetes/)). See the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides for step-by-step instructions. ### Do LLM requests still go through Warp with self-hosting? @@ -229,10 +229,10 @@ Yes. LLM inference routes through Warp's backend, which has [Zero Data Retention ### What about large monorepos with long environment setup times? -The [unmanaged architecture](/platform/self-hosting/unmanaged/) is well-suited for large monorepos because agents run directly in your pre-provisioned environment — there is no Docker image build or repo cloning step. For the [managed architecture](/platform/self-hosting/#managed-architecture), the Docker backend supports volume mounts (`-v` flag) to mount a pre-existing repo checkout from the host into task containers. With the Kubernetes backend, use `pod_template` to configure persistent volume claims or pre-populated storage for the same purpose. +The [unmanaged architecture](/platform/unmanaged-execution/) is well-suited for large monorepos because agents run directly in your pre-provisioned environment — there is no Docker image build or repo cloning step. For the [managed architecture](/factories/self-hosting/#managed-architecture), the Docker backend supports volume mounts (`-v` flag) to mount a pre-existing repo checkout from the host into task containers. With the Kubernetes backend, use `pod_template` to configure persistent volume claims or pre-populated storage for the same purpose. :::note -The managed architecture supports three execution backends: **Docker** (default), **Kubernetes**, and **Direct** (no container runtime). The Kubernetes backend runs each task as a Kubernetes Job and includes a Helm chart for deployment. See [Self-hosting](/platform/self-hosting/#choosing-a-managed-backend) for details on choosing a backend. +The managed architecture supports three execution backends: **Docker** (default), **Kubernetes**, and **Direct** (no container runtime). The Kubernetes backend runs each task as a Kubernetes Job and includes a Helm chart for deployment. See [Self-hosting](/factories/self-hosting/#choose-a-backend) for details on choosing a backend. ::: ### Do Kubernetes pods provide enough sandboxing for self-hosted agents? diff --git a/src/content/docs/platform/handoff/snapshots.mdx b/src/content/docs/platform/handoff/snapshots.mdx index 5f6600006..a49bd96ab 100644 --- a/src/content/docs/platform/handoff/snapshots.mdx +++ b/src/content/docs/platform/handoff/snapshots.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Workspace snapshots are how [handoff](/platform/handoff/) carries repository changes and other workspace state across cloud agent runs. At the end of every cloud agent run, Warp asks a small declarations script which repositories and files to snapshot, then uploads the resulting git diffs and file contents so the next cloud agent run can apply them. -Warp's bundled cloud agent image ships with a declarations script that snapshots every Git repository under the agent's workspace, so most cloud agent runs need no configuration. This page is for the cases where you need to customize what gets snapshotted — for example, when running cloud agents in a custom Docker image, on a self-hosted [Direct backend](/platform/self-hosting/managed-direct/), or as an [unmanaged](/platform/self-hosting/unmanaged/) `oz agent run` in CI. +Warp's bundled cloud agent image ships with a declarations script that snapshots every Git repository under the agent's workspace, so most cloud agent runs need no configuration. This page is for the cases where you need to customize what gets snapshotted — for example, when running cloud agents in a custom Docker image, on a self-hosted [Direct backend](/factories/self-hosting/managed-direct/), or as an [unmanaged](/platform/unmanaged-execution/) `oz agent run` in CI. ## When to customize snapshots @@ -113,7 +113,7 @@ Then point Warp at it by exporting `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` in the envi export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh ``` -For a managed [Direct backend](/platform/self-hosting/managed-direct/) worker, set it via the worker's `environment` config so it's present when the agent process starts. +For a managed [Direct backend](/factories/self-hosting/managed-direct/) worker, set it via the worker's `environment` config so it's present when the agent process starts. ### The full bundled script @@ -229,6 +229,6 @@ Snapshotting is also skipped automatically when cloud conversations are disabled * [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Promote a local conversation to a cloud run; the workspace snapshot is what carries your uncommitted changes across. * [Handoff from cloud to cloud](/platform/handoff/cloud-to-cloud/) - Continue a finished cloud run; the prior session's workspace snapshot is what gets restored. -* [Self-hosting overview](/platform/self-hosting/) - Architecture decision guide for self-hosted workers, where customizing snapshots is most often needed. -* [Unmanaged architecture](/platform/self-hosting/unmanaged/) - Run `oz agent run` in CI, Kubernetes, or your dev environment outside the bundled image. -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) - Full reference for `oz agent run` and `oz agent run-cloud`. +* [Self-hosting overview](/factories/self-hosting/) - Architecture decision guide for self-hosted workers, where customizing snapshots is most often needed. +* [Unmanaged architecture](/platform/unmanaged-execution/) - Run `oz agent run` in CI, Kubernetes, or your dev environment outside the bundled image. +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) - Full reference for `oz agent run` and `oz agent run-cloud`. diff --git a/src/content/docs/platform/harnesses/claude-code.mdx b/src/content/docs/platform/harnesses/claude-code.mdx index eb8c70c8e..d929ad89f 100644 --- a/src/content/docs/platform/harnesses/claude-code.mdx +++ b/src/content/docs/platform/harnesses/claude-code.mdx @@ -45,7 +45,7 @@ For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/au * **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Claude Code**. * **{VARS.WEB_APP}** - On the new run or new schedule pane, choose **Claude Code** in the **Harness** field. A **Claude Code auth secret** field appears below it; pick one of your stored Anthropic secrets. -* **API and SDK** - Set the agent config `harness` to `claude` — the [harness identifier](/platform/harnesses/#harness-identifiers) is `claude`, not `claude-code` — and the Anthropic secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/). +* **API and SDK** - Set the agent config `harness` to `claude` — the [harness identifier](/platform/harnesses/#harness-identifiers) is `claude`, not `claude-code` — and the Anthropic secret name on the matching auth-secret field. See the [API reference](/factories/api-and-sdk/). ## Related pages diff --git a/src/content/docs/platform/harnesses/codex.mdx b/src/content/docs/platform/harnesses/codex.mdx index dadc3df16..569c729e4 100644 --- a/src/content/docs/platform/harnesses/codex.mdx +++ b/src/content/docs/platform/harnesses/codex.mdx @@ -45,7 +45,7 @@ For setup steps, see [Connecting Codex credentials](/platform/harnesses/authenti * **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Codex**. * **{VARS.WEB_APP}** - On the new run or new schedule pane, choose **Codex** in the **Harness** field. A **Codex auth secret** field appears below it; pick the OpenAI secret your team has stored. -* **API and SDK** - Set the agent config `harness` to `codex` and the OpenAI secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/). +* **API and SDK** - Set the agent config `harness` to `codex` and the OpenAI secret name on the matching auth-secret field. See the [API reference](/factories/api-and-sdk/). ## Related pages diff --git a/src/content/docs/platform/harnesses/index.mdx b/src/content/docs/platform/harnesses/index.mdx index 98a629bbd..8578dc4f8 100644 --- a/src/content/docs/platform/harnesses/index.mdx +++ b/src/content/docs/platform/harnesses/index.mdx @@ -54,7 +54,7 @@ On the new run or new schedule pane, choose the harness in the **Harness** field ### API and SDK -Set the `harness` field on the agent config to one of the [harness identifiers](#harness-identifiers) below. See the [API reference](/reference/api-and-sdk/) for the exact field names. +Set the `harness` field on the agent config to one of the [harness identifiers](#harness-identifiers) below. See the [API reference](/factories/api-and-sdk/) for the exact field names. ## Harness identifiers diff --git a/src/content/docs/platform/harnesses/warp-agent.mdx b/src/content/docs/platform/harnesses/warp-agent.mdx index 79165c57c..d1071c9c2 100644 --- a/src/content/docs/platform/harnesses/warp-agent.mdx +++ b/src/content/docs/platform/harnesses/warp-agent.mdx @@ -56,7 +56,7 @@ Warp Agent is the default, so there's nothing extra to configure. * **Warp app** - Start a cloud agent run from the input. The **Agent harness** dropdown defaults to **Warp Agent**. * **{VARS.WEB_APP}** - On a new run or new schedule pane, leave the **Harness** field set to **Warp Agent**. * **{VARS.WARP_AGENT_CLI}** - Run `oz agent run-cloud --prompt "..."` with no `--harness` flag, or pass `--harness oz` explicitly. -* **API and SDK** - Omit the `harness` field on the agent config, or set it to `oz`. See the [API reference](/reference/api-and-sdk/). +* **API and SDK** - Omit the `harness` field on the agent config, or set it to `oz`. See the [API reference](/factories/api-and-sdk/). For a complete walkthrough, see the [Cloud agents quickstart](/platform/quickstart/). diff --git a/src/content/docs/platform/index.mdx b/src/content/docs/platform/index.mdx index 27e991797..9bb57f234 100644 --- a/src/content/docs/platform/index.mdx +++ b/src/content/docs/platform/index.mdx @@ -68,9 +68,9 @@ Cloud agents run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/), * The **orchestrator creates** and tracks the task. * The agent **executes** on a host, optionally inside an [environment](/platform/environments/), with whatever [secrets](/platform/secrets/) and credentials it needs. -The exact way tasks are triggered and executed depends on your deployment model (for example CLI-only, Warp-hosted orchestration, or self-hosted execution). Those options are covered in the [Deployment Patterns](/platform/deployment-patterns/) pages. +The exact way tasks are triggered and executed depends on your deployment model (for example CLI-only, Warp-hosted orchestration, or self-hosted execution). Those options are covered in the [Deployment Patterns](/factories/deployment-patterns/) pages. -For teams that need execution to stay within their network boundary, self-hosting supports two architectures: a **managed** worker daemon that lets the {VARS.WARP_AUTOMATION_PLATFORM} orchestrate agents in Docker containers on your machines, and an **unmanaged** mode where you run `oz agent run` directly in your CI, Kubernetes, or dev environment. See [Self-hosting](/platform/self-hosting/) for details. +For teams that need execution to stay within their network boundary, self-hosting supports two architectures: a **managed** worker daemon that lets the {VARS.WARP_AUTOMATION_PLATFORM} orchestrate agents in Docker containers on your machines, and an **unmanaged** mode where you run `oz agent run` directly in your CI, Kubernetes, or dev environment. See [Self-hosting](/factories/self-hosting/) for details. ### What you get by default @@ -98,7 +98,7 @@ For details on configuring MCP servers for cloud agents, see [MCP Servers](/plat #### API access to tasks -The {VARS.WARP_AUTOMATION_PLATFORM} exposes task visibility via the [**{VARS.API_SDK_NAME}**](/reference/api-and-sdk/), so teams can: +The {VARS.WARP_AUTOMATION_PLATFORM} exposes task visibility via the [**{VARS.API_SDK_NAME}**](/factories/api-and-sdk/), so teams can: * Query which tasks are running or have run. * Fetch task metadata and outcomes. @@ -108,11 +108,11 @@ The {VARS.WARP_AUTOMATION_PLATFORM} exposes task visibility via the [**{VARS.API Cloud agents do not require the Warp app. Teams can deploy and operate them through the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) using: -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — run agents from scripts, CI, or the terminal +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — run agents from scripts, CI, or the terminal * [{VARS.WEB_APP}](/platform/oz-web-app/) — visual interface for managing runs, schedules, environments, and integrations (works on mobile) * [Agent Session Sharing](/agents/local-agents/session-sharing/) — attach to running tasks to monitor or steer * [Agent Management Panel](/platform/managing-cloud-agents/) — view agent activity and run history in the Warp app -* [APIs and SDKs](/reference/api-and-sdk/) — programmatic access for custom integrations +* [APIs and SDKs](/factories/api-and-sdk/) — programmatic access for custom integrations If your team also uses Warp's terminal, you get an additional workflow: tasks launched via the CLI can be handed off into an interactive session for review, edits, or continuation. @@ -161,10 +161,10 @@ If your credit balance reaches zero, cloud agent runs will not be able to execut * [Agents](/platform/agents/) — cloud agents that own and execute runs on your team. * [Multi-agent orchestration](/platform/orchestration/) — coordinate a parent agent and its child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows. * [Skills as Agents](/platform/skills-as-agents/) — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule. -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — shows how to run agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — shows how to run agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. * [Environments](/platform/environments/) — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. * [Agent Secrets](/platform/secrets/) — covers how to store, scope, and inject credentials into agent runs safely. * [MCP Servers](/platform/mcp/) — how to configure MCP servers for agent tool access and how MCP configuration is applied across runs. -* [Deployment Patterns](/platform/deployment-patterns/) (beta) — compares common ways to deploy cloud agents and when to use each. +* [Deployment Patterns](/factories/deployment-patterns/) (beta) — compares common ways to deploy cloud agents and when to use each. * [Access, Billing, and Identity Permissions](/platform/team-access-billing-and-identity/) — explains individual and team-level requirements, credit billing behavior, and the permission model for who can run, view, and steer cloud agent tasks. diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 777101633..99c2d0f9b 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -22,7 +22,7 @@ This approach works for both Azure DevOps Services (dev.azure.com) and Azure Dev * A Warp account (<a href={VARS.WEB_APP_URL}>create an account at {VARS.WEB_APP_URL}</a>) * A repository hosted on Azure DevOps (cloud or self-hosted) -* The [{VARS.WARP_AGENT_CLI}](/reference/cli/) installed and authenticated +* The [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) installed and authenticated --- diff --git a/src/content/docs/platform/integrations/bitbucket.mdx b/src/content/docs/platform/integrations/bitbucket.mdx index b2b8baad5..fb67db47b 100644 --- a/src/content/docs/platform/integrations/bitbucket.mdx +++ b/src/content/docs/platform/integrations/bitbucket.mdx @@ -25,7 +25,7 @@ Follow the section that matches your setup. * A Warp account (<a href={VARS.WEB_APP_URL}>create an account at {VARS.WEB_APP_URL}</a>) * A repository hosted on Bitbucket (Cloud or Data Center/Server) -* The [{VARS.WARP_AGENT_CLI}](/reference/cli/) installed and authenticated +* The [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) installed and authenticated --- diff --git a/src/content/docs/platform/integrations/cloud-providers.mdx b/src/content/docs/platform/integrations/cloud-providers.mdx index 5a7ae511a..19fb399b0 100644 --- a/src/content/docs/platform/integrations/cloud-providers.mdx +++ b/src/content/docs/platform/integrations/cloud-providers.mdx @@ -334,7 +334,7 @@ The following claims are derived from an agent run: * `environment`: the unique identifier for the agent's [Environment](/platform/environments/). * `agent_name`: the name of the [Skill](/platform/skills-as-agents/) that the agent was invoked with. * `skill_spec`: the canonical identifier for the skill, such as `github-org/github-repo:.warp/skills/skill-name/SKILL.md`. -* `host`: the execution host. This will either be `warp`, for Warp-hosted agents, or the worker ID if [self-hosting](/platform/self-hosting/). +* `host`: the execution host. This will either be `warp`, for Warp-hosted agents, or the worker ID if [self-hosting](/factories/self-hosting/). ### Example token diff --git a/src/content/docs/platform/integrations/github-actions.mdx b/src/content/docs/platform/integrations/github-actions.mdx index f519e47ad..fd17644cd 100644 --- a/src/content/docs/platform/integrations/github-actions.mdx +++ b/src/content/docs/platform/integrations/github-actions.mdx @@ -48,7 +48,7 @@ The `oz-agent-action` is a GitHub Action that wraps the {VARS.WARP_AGENT_CLI} an To use agents in GitHub Actions, you need: -* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to run as a [cloud agent](/platform/agents/) on your team. See [API keys](/reference/cli/api-keys/) for when to pick each. +* A [**Warp API Key**](/agents/cli/oz-cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to run as a [cloud agent](/platform/agents/) on your team. See [API keys](/agents/cli/oz-cli/api-keys/) for when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) @@ -73,7 +73,7 @@ You can specify a skill using the `skill` input parameter, either instead of or :::tip If the action fails, use the returned error code to narrow the fix. Common errors include: -* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) (missing, invalid, or expired `warp_api_key` secret) +* [`authentication_required`](/factories/api-and-sdk/troubleshooting/errors/authentication-required/) (missing, invalid, or expired `warp_api_key` secret) ::: #### Skill format options diff --git a/src/content/docs/platform/integrations/github.mdx b/src/content/docs/platform/integrations/github.mdx index 6c0231acf..88ff904e0 100644 --- a/src/content/docs/platform/integrations/github.mdx +++ b/src/content/docs/platform/integrations/github.mdx @@ -192,9 +192,9 @@ Your GitHub account is connected, but your Warp account isn't in a team with acc Use the error code in the thread's status comment to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) - The team's plan doesn't support integrations. -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) - GitHub authorization is missing or expired. -* [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) - The billed account has no credits available. +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) - The team's plan doesn't support integrations. +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) - GitHub authorization is missing or expired. +* [`insufficient_credits`](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/) - The billed account has no credits available. ### The agent finished but opened no pull request diff --git a/src/content/docs/platform/integrations/index.mdx b/src/content/docs/platform/integrations/index.mdx index bd981d9e3..bf2245a4c 100644 --- a/src/content/docs/platform/integrations/index.mdx +++ b/src/content/docs/platform/integrations/index.mdx @@ -31,7 +31,7 @@ Use the setup walkthrough below for a quick look at how environments connect to <VideoEmbed url="https://www.youtube.com/watch?v=ahFfInVD0HQ" title="Cloud agents integrations overview video" /> * [Integrations quickstart](/platform/integrations/quickstart/) - Trigger your first agent from Slack and watch the run from start to finish. -* [Integration setup](/reference/cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail. +* [Integration setup](/agents/cli/oz-cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail. * [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), and [Jira](/platform/integrations/jira/) - Trigger agents from team conversations, issues, and comments. * [GitHub](/platform/integrations/github/) - Mention `@warp-agent` on issues, pull requests, and review comments to start agents that reply in the thread. * [GitHub Actions](/platform/integrations/github-actions/) - Run agents from CI workflows and repository events. diff --git a/src/content/docs/platform/integrations/jira.mdx b/src/content/docs/platform/integrations/jira.mdx index 6363debb7..ab45559cd 100644 --- a/src/content/docs/platform/integrations/jira.mdx +++ b/src/content/docs/platform/integrations/jira.mdx @@ -16,7 +16,7 @@ The Jira integration lets your team kick off cloud agent runs directly from Jira * **Jira Cloud** - Jira Server and Data Center are not supported. * **Team membership** - The Jira integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. -* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/platform/self-hosting/) on their own infrastructure. +* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/factories/self-hosting/) on their own infrastructure. * **Jira site admin** - Installing the Warp app on your Jira site requires site admin permissions. --- diff --git a/src/content/docs/platform/integrations/linear.mdx b/src/content/docs/platform/integrations/linear.mdx index 5e631c8dc..8240072aa 100644 --- a/src/content/docs/platform/integrations/linear.mdx +++ b/src/content/docs/platform/integrations/linear.mdx @@ -70,7 +70,7 @@ Because PRs are created as _you_, this makes code review, auditing, and team col * **Team membership** - The Linear integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must have cloud agents enabled and credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. -* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/platform/self-hosting/) on their own infrastructure. +* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/factories/self-hosting/) on their own infrastructure. * **Identity** - The first time you trigger an agent, Warp prompts you to connect your Linear identity to your Warp account. * **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. * The repositories involved must be included in your environment and accessible to the Warp GitHub app. @@ -80,7 +80,7 @@ Because PRs are created as _you_, this makes code review, auditing, and team col ### How to configure the integration -Setup involves two steps powered by the [{VARS.WARP_AGENT_CLI}](/reference/cli/). For more instructions, see [Integrations Overview](/platform/integrations/). +Setup involves two steps powered by the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/). For more instructions, see [Integrations Overview](/platform/integrations/). #### 1. Create an environment @@ -116,8 +116,8 @@ The CLI will open a browser window prompting you to install the Warp app into yo :::tip If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Linear authorization) +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Linear authorization) ::: --- @@ -134,7 +134,7 @@ To remove the Warp app from Linear: <VideoEmbed url="https://www.loom.com/share/2f1648586d8148dc80561c00a09ca334" title="Uninstalling the Warp Linear integration video" /> -After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). +After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. Events for a disabled integration can return [`integration_disabled`](/factories/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting diff --git a/src/content/docs/platform/integrations/quickstart-github-actions.mdx b/src/content/docs/platform/integrations/quickstart-github-actions.mdx index 54830ef12..dee39ef26 100644 --- a/src/content/docs/platform/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/platform/integrations/quickstart-github-actions.mdx @@ -14,7 +14,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git ## Prerequisites -* **Warp API key** - Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. Use a personal key if the agent should commit as you, or an agent key (which runs as a [cloud agent](/platform/agents/) on your team) with [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **Warp API key** - Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. Use a personal key if the agent should commit as you, or an agent key (which runs as a [cloud agent](/platform/agents/) on your team) with [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. --- diff --git a/src/content/docs/platform/integrations/quickstart.mdx b/src/content/docs/platform/integrations/quickstart.mdx index 1db093854..7b1c1dc33 100644 --- a/src/content/docs/platform/integrations/quickstart.mdx +++ b/src/content/docs/platform/integrations/quickstart.mdx @@ -47,8 +47,8 @@ Replace `<ENV_ID>` with your environment ID (see [Environments](/platform/enviro :::tip If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) ::: To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag: @@ -85,5 +85,5 @@ When the task is complete, Warp posts a summary back to the original Slack threa ## Next steps * **Customize agent behavior** - Use a [skill](/platform/skills-as-agents/) as the base prompt for your integration to give agents consistent, reusable instructions across every run. -* **Trigger agents programmatically** - Use the [API & SDK](/reference/api-and-sdk/) to build custom automations and integrations on top of agents. +* **Trigger agents programmatically** - Use the [API & SDK](/factories/api-and-sdk/) to build custom automations and integrations on top of agents. * **Read the full Slack reference** - [Slack](/platform/integrations/slack/) covers identity mapping, team access, monitoring runs, troubleshooting, and uninstall instructions. diff --git a/src/content/docs/platform/integrations/slack.mdx b/src/content/docs/platform/integrations/slack.mdx index a89b0ea6f..275641de6 100644 --- a/src/content/docs/platform/integrations/slack.mdx +++ b/src/content/docs/platform/integrations/slack.mdx @@ -19,7 +19,7 @@ The Slack integration lets your team trigger cloud agents directly from Slack co 3. After installing, you're returned to the Integrations page to finish setup: choose the [environment](/platform/environments/) agents should use, which defines the repos, Docker image, and setup commands. 4. Start using Warp in Slack by mentioning **@Warp** with a task. -Alternatively, install via the [{VARS.WARP_AGENT_CLI}](/reference/cli/): +Alternatively, install via the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/): ``` oz integration create slack --environment <ENV_ID> @@ -31,7 +31,7 @@ The CLI opens a browser window to install the Warp app into your Slack workspace * **Team membership** - The Slack integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must have cloud agents enabled and credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. -* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/platform/self-hosting/) on their own infrastructure. +* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/factories/self-hosting/) on their own infrastructure. --- @@ -137,8 +137,8 @@ oz integration create slack \ :::tip If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) ::: ### Identity mapping and team access @@ -172,7 +172,7 @@ To remove the Warp app from your Slack workspace: ![Confirmation dialog to remove the Warp app from a Slack workspace.](../../../../assets/agent-platform/remove-slack-app.png) -Once removed, Slack will immediately disable the integration for all teammates. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). +Once removed, Slack will immediately disable the integration for all teammates. Events for a disabled integration can return [`integration_disabled`](/factories/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting diff --git a/src/content/docs/platform/managing-cloud-agents.mdx b/src/content/docs/platform/managing-cloud-agents.mdx index 46b1cdbc2..5bb605a3e 100644 --- a/src/content/docs/platform/managing-cloud-agents.mdx +++ b/src/content/docs/platform/managing-cloud-agents.mdx @@ -82,8 +82,8 @@ Each row represents a single item in the agents list (either an interactive conv Where the agent was launched from. Common sources include: * **Interactive:** an [agent conversation](/agents/) started in the Warp app -* **CLI**: a local run triggered by the [{VARS.WARP_AGENT_CLI}](/reference/cli/) -* **API**: a run triggered by [Warp's API](/reference/api-and-sdk/) +* **CLI**: a local run triggered by the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) +* **API**: a run triggered by [Warp's API](/factories/api-and-sdk/) * **Slack / Linear**: runs triggered by [integrations](/platform/integrations/) * **Scheduled**: runs triggered on a [cron schedule](/platform/triggers/scheduled-agents/) @@ -91,7 +91,7 @@ Where the agent was launched from. Common sources include: Warp uses a small set of statuses to help you quickly identify what needs attention: -<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td><p><em>(interactive only)</em></p><p><br />the conversation is waiting on user input or a required step</p></td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><a href="/reference/api-and-sdk/troubleshooting/errors/"><code>Failed / Errored</code></a></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table> +<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td><p><em>(interactive only)</em></p><p><br />the conversation is waiting on user input or a required step</p></td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><a href="/factories/api-and-sdk/troubleshooting/errors/"><code>Failed / Errored</code></a></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table> **Duration (for cloud agent tasks)** diff --git a/src/content/docs/platform/mcp.mdx b/src/content/docs/platform/mcp.mdx index 1105a7ce2..ad13551b4 100644 --- a/src/content/docs/platform/mcp.mdx +++ b/src/content/docs/platform/mcp.mdx @@ -24,7 +24,7 @@ The agent calls MCP tools automatically based on what the task requires, without You can supply MCP configuration in two ways: -* **At run time** — pass `--mcp` when calling `oz agent run` or `oz agent run-cloud`. See [MCP Servers](/reference/cli/mcp-servers/) in the CLI reference for the full syntax. +* **At run time** — pass `--mcp` when calling `oz agent run` or `oz agent run-cloud`. See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) in the CLI reference for the full syntax. * **In an agent config file** — define `mcp_servers` directly in a YAML or JSON agent config file (passed with `-f / --file`). This is the recommended approach for repeatable workflows. ## Configuration schema @@ -133,7 +133,7 @@ Token- or header-based authentication on a `url` server, `env`-based secrets on ## Learn more * [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/) — choose between local, cloud, and shared MCP setup paths -* [MCP Servers (CLI reference)](/reference/cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag +* [MCP Servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag * [Model Context Protocol (MCP)](/agents/capabilities/mcp/) — configuring MCP servers in Warp for local agents * [Environments](/platform/environments/) — set up the runtime context (repo, image, startup commands) for cloud agent tasks * [Secrets](/platform/secrets/) — store and inject credentials into agent runs safely diff --git a/src/content/docs/platform/orchestration/index.mdx b/src/content/docs/platform/orchestration/index.mdx index 753c2afd5..a0c97d2cd 100644 --- a/src/content/docs/platform/orchestration/index.mdx +++ b/src/content/docs/platform/orchestration/index.mdx @@ -7,7 +7,7 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent's output. The parent/child model works from the Warp app, the [{VARS.WARP_AGENT_CLI}](/reference/cli/), and the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), and supports local, cloud, and mixed execution. +Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent's output. The parent/child model works from the Warp app, the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), and the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/), and supports local, cloud, and mixed execution. Watch this walkthrough to see how a cloud agent can coordinate a team of agents in the cloud. @@ -24,7 +24,7 @@ An orchestrated workflow always has one **parent agent** and one or more **child * **Parent agent** - the agent that decides what work needs to be done, spawns child agents, and (optionally) merges their results. Any agent can become a parent the first time it spawns a child. * **Child agent** - an agent spawned by a parent with its own prompt, environment, and (optionally) a different model or agent runtime. A child runs its own work and reports back; it does not spawn its own children. -Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [{VARS.WEB_APP}](/platform/oz-web-app/), and the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. +Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [{VARS.WEB_APP}](/platform/oz-web-app/), and the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. ### Where parent and child agents can run @@ -124,13 +124,13 @@ Because every parent and child is tracked as its own conversation or run, the ex * **[Managing cloud agents](/platform/managing-cloud-agents/)** - in the Warp app, the orchestration pill bar above the agent view header lets you switch between the parent and each child while you're viewing the parent. Cloud children also appear as their own rows in the Agent Management Panel list. * **[{VARS.WEB_APP}](/platform/oz-web-app/)** - the Runs page groups cloud children under the parent's row, and the parent's detail pane adds a **Sub-agents** tab. -* **[{VARS.API_SDK_NAME}](/reference/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts). +* **[{VARS.API_SDK_NAME}](/factories/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts). * **[Agent notifications](/agents/capabilities/agent-notifications/)** - in-app notifications fire on the parent agent's conversation only. Use the pill bar or the **Sub-agents** tab to drill into a specific child. ## Related pages * [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) - how to start an orchestrated run from the CLI, slash command, web app, or API. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical guidance for splitting tasks, assigning worktrees, validating child output, and handing work off for review. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - REST endpoints for runs, conversations, and artifacts. +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - REST endpoints for runs, conversations, and artifacts. * [Cloud agents overview](/platform/) - what a cloud agent run is and how it fits into the {VARS.WARP_AUTOMATION_PLATFORM}. -* [Deployment patterns](/platform/deployment-patterns/) - higher-level deployment models that orchestration composes with. +* [Deployment patterns](/factories/deployment-patterns/) - higher-level deployment models that orchestration composes with. diff --git a/src/content/docs/platform/orchestration/multi-agent-runs.mdx b/src/content/docs/platform/orchestration/multi-agent-runs.mdx index 1b231cda8..efbf2e416 100644 --- a/src/content/docs/platform/orchestration/multi-agent-runs.mdx +++ b/src/content/docs/platform/orchestration/multi-agent-runs.mdx @@ -18,9 +18,9 @@ Watch this walkthrough to see how to start and inspect an orchestrated agent run Pick where the parent will run. Every orchestration starts with a single parent that spawns children: * **Parent in the Warp app** - use the `/orchestrate` or `/plan` slash command. This is the fastest way to try orchestration. -* **Parent in the cloud** - trigger the parent through the {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), any [integration](/platform/integrations/) such as [Slack](/platform/integrations/slack/) or [Linear](/platform/integrations/linear/), or a [schedule](/platform/triggers/scheduled-agents/). The parent runs in an environment and spawns children from there. +* **Parent in the cloud** - trigger the parent through the {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/), any [integration](/platform/integrations/) such as [Slack](/platform/integrations/slack/) or [Linear](/platform/integrations/linear/), or a [schedule](/platform/triggers/scheduled-agents/). The parent runs in an environment and spawns children from there. -Cloud parents that spawn cloud children need access to one or more [environments](/platform/environments/) the children can run in. To keep child execution on your own infrastructure, route those children to a [self-hosted worker](/platform/self-hosting/). +Cloud parents that spawn cloud children need access to one or more [environments](/platform/environments/) the children can run in. To keep child execution on your own infrastructure, route those children to a [self-hosted worker](/factories/self-hosting/). ## Starting an orchestrated run from Warp @@ -193,10 +193,10 @@ Self-hosted, local, and GitHub Action runs cannot be cancelled through this endp * [Multi-agent orchestration](/platform/orchestration/) - parent/child model, run state transitions, and common patterns. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical task decomposition, worktree ownership, validation, and review handoff guidance. -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) - command reference for `oz agent run-cloud` and `oz run`. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - full HTTP reference and typed SDKs. +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) - command reference for `oz agent run-cloud` and `oz run`. +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - full HTTP reference and typed SDKs. * [Managing cloud agents](/platform/managing-cloud-agents/) - how parent and child runs appear in the Agent Management Panel in the Warp app and the Runs page in the {VARS.WEB_APP}. * [Scheduled agents](/platform/triggers/scheduled-agents/) - start a recurring cloud parent that fans out children on a cron cadence. -* [Self-hosting](/platform/self-hosting/) - keep parent or child execution on your infrastructure while Warp tracks the runs. +* [Self-hosting](/factories/self-hosting/) - keep parent or child execution on your infrastructure while Warp tracks the runs. * [Handoff between local and cloud agents](/platform/handoff/) - promote a local parent to the cloud, or continue a finished cloud parent with a follow-up. * [Environments](/platform/environments/) - configure the runtime context cloud children execute in. diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index eee34d36b..5d87dc41b 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -36,13 +36,13 @@ Every run follows the same path, whatever starts it: ## Integrations and triggers -Every run starts with a trigger. [Integrations](/platform/integrations/) turn events in other tools into runs: mention @warp in [Slack](/platform/integrations/slack/) and the agent gets the message and its thread, or run agents inside your [GitHub Actions](/platform/integrations/github-actions/) workflows with your CI context. [Scheduled agents](/platform/triggers/scheduled-agents/) start runs on a cron schedule. For event sources Warp doesn't cover, receive the event in your own system and start the run through the [API](/reference/api-and-sdk/); it becomes a normal, fully tracked task. +Every run starts with a trigger. [Integrations](/platform/integrations/) turn events in other tools into runs: mention @warp in [Slack](/platform/integrations/slack/) and the agent gets the message and its thread, or run agents inside your [GitHub Actions](/platform/integrations/github-actions/) workflows with your CI context. [Scheduled agents](/platform/triggers/scheduled-agents/) start runs on a cron schedule. For event sources Warp doesn't cover, receive the event in your own system and start the run through the [API](/factories/api-and-sdk/); it becomes a normal, fully tracked task. -Set up a first-party integration with `oz integration create` on the {VARS.WARP_AGENT_CLI}; the [integration setup guide](/reference/cli/integration-setup/) covers it end to end. +Set up a first-party integration with `oz integration create` on the {VARS.WARP_AGENT_CLI}; the [integration setup guide](/agents/cli/oz-cli/integration-setup/) covers it end to end. ## Tasks and tracking -Warp tracks every run as a task: its status, transcript, and outputs stay available after the run finishes. Watch or steer a live run with [session sharing](/agents/local-agents/session-sharing/), browse history in the [management UI](/platform/managing-cloud-agents/), or query it from the [{VARS.WARP_AGENT_CLI}](/reference/cli/) and the [API](/reference/api-and-sdk/). Access control decides who can run, view, or intervene in tasks. +Warp tracks every run as a task: its status, transcript, and outputs stay available after the run finishes. Watch or steer a live run with [session sharing](/agents/local-agents/session-sharing/), browse history in the [management UI](/platform/managing-cloud-agents/), or query it from the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) and the [API](/factories/api-and-sdk/). Access control decides who can run, view, or intervene in tasks. To fan work out across parent and child agents, see [multi-agent orchestration](/platform/orchestration/). @@ -52,17 +52,17 @@ An [environment](/platform/environments/) defines what a run needs: a Docker ima ## Hosts -A host is where the agent executes. By default runs execute on [Warp-hosted infrastructure](/platform/warp-hosting/), with nothing to set up. On Enterprise plans, [self-hosted runners](/platform/self-hosting/) keep code and execution inside your own network while Warp still tracks the runs. +A host is where the agent executes. By default runs execute on [Warp-hosted infrastructure](/factories/warp-hosting/), with nothing to set up. On Enterprise plans, [self-hosted runners](/factories/self-hosting/) keep code and execution inside your own network while Warp still tracks the runs. ![Architecture diagram: Warp-designed and customer-defined triggers create an agent task, which is routed to agent runners on Warp or customer infrastructure](../../../assets/agent-platform/platform-architecture.png) ## The CLI -The [{VARS.WARP_AGENT_CLI}](/reference/cli/) starts and manages runs where there's no UI: CI jobs, scripts, and remote servers. Start a run with `oz agent run`, and it reports progress to Warp like any other task, so work that starts on a CI runner shows up alongside everything else your team runs. For interactive sessions, use [agents in the Warp app](/agents/). +The [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) starts and manages runs where there's no UI: CI jobs, scripts, and remote servers. Start a run with `oz agent run`, and it reports progress to Warp like any other task, so work that starts on a CI runner shows up alongside everything else your team runs. For interactive sessions, use [agents in the Warp app](/agents/). ## API and SDKs -The [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) creates and inspects tasks over HTTP: submit a prompt with optional configuration, poll status, and fetch results with full provenance. Teams use it to start agents from incident tooling and internal systems, build dashboards over run history, and coordinate large batches of runs. Official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs add typed requests and responses, built-in retries, and consistent errors. Start with an SDK unless you need full control over your HTTP client. +The [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) creates and inspects tasks over HTTP: submit a prompt with optional configuration, poll status, and fetch results with full provenance. Teams use it to start agents from incident tooling and internal systems, build dashboards over run history, and coordinate large batches of runs. Official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs add typed requests and responses, built-in retries, and consistent errors. Start with an SDK unless you need full control over your HTTP client. ## Secrets @@ -82,4 +82,4 @@ Runs pick up your team's shared setup no matter what triggered them: [MCP server * [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. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - drive the platform programmatically. +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - drive the platform programmatically. diff --git a/src/content/docs/platform/oz-web-app.mdx b/src/content/docs/platform/oz-web-app.mdx index b40860d23..131cfca2e 100644 --- a/src/content/docs/platform/oz-web-app.mdx +++ b/src/content/docs/platform/oz-web-app.mdx @@ -38,7 +38,7 @@ The {VARS.WEB_APP} is ideal when you want to: * **Configure environments** — Set up repos, Docker images, and setup commands through a form-based flow * **Set up integrations** — Connect Slack and Linear with a guided setup flow, and configure how [GitHub](/platform/integrations/github/) mention-triggered runs execute -For scripting, automation, and CI/CD workflows, use the [{VARS.WARP_AGENT_CLI}](/reference/cli/) or [API](/reference/api-and-sdk/). +For scripting, automation, and CI/CD workflows, use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) or [API](/factories/api-and-sdk/). ## Getting started @@ -217,7 +217,7 @@ To create a new environment: 6. Click **Create environment**. The environment appears on the Environments page. :::note -For advanced environment configuration, see [Environments](/platform/environments/) and the [CLI reference](/reference/cli/integration-setup/). +For advanced environment configuration, see [Environments](/platform/environments/) and the [CLI reference](/agents/cli/oz-cli/integration-setup/). ::: ## Integrations @@ -251,5 +251,5 @@ For detailed integration setup instructions, see [Slack](/platform/integrations/ * [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [Environments](/platform/environments/) — Configure runtime context for cloud agents * [Managing Cloud Agents](/platform/managing-cloud-agents/) — Monitor agent activity and inspect runs -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — Command-line interface for running agents -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — Programmatic access to cloud agents +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Command-line interface for running agents +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — Programmatic access to cloud agents diff --git a/src/content/docs/platform/quickstart.mdx b/src/content/docs/platform/quickstart.mdx index b597b592c..45bbc2d73 100644 --- a/src/content/docs/platform/quickstart.mdx +++ b/src/content/docs/platform/quickstart.mdx @@ -102,7 +102,7 @@ Follow the prompts to save your task definition. Once created, you can run it ag **How this works:** Skills capture successful agent workflows as reusable building blocks. Instead of typing the same prompt repeatedly, you define it once. You can use it yourself, share it with teammates, schedule it to run automatically, or trigger it from integrations. Learn more about [Skills as Agents](/platform/skills-as-agents/). -**Prefer using the CLI?** See the [{VARS.WARP_AGENT_CLI} quickstart](/reference/cli/quickstart/) for CLI-based workflows. +**Prefer using the CLI?** See the [{VARS.WARP_AGENT_CLI} quickstart](/agents/cli/oz-cli/quickstart/) for CLI-based workflows. --- @@ -114,7 +114,7 @@ Now that you've run your first cloud agent, try these next steps: * [**Trigger agents from Slack or Linear**](/platform/integrations/quickstart/) - Connect Warp to team tools so mentions and issue updates can launch cloud agent runs. * [**Orchestrate multiple agents**](/platform/orchestration/multi-agent-runs/) - Fan work out across parent and child agents for large refactors, PR review swarms, and parallel package migrations. * [**Turn successful prompts into reusable skills**](/platform/skills-as-agents/) - Save repeatable agent workflows and run them again from the CLI, web app, API, or a schedule. -* [**Build programmatic automations**](/reference/api-and-sdk/quickstart/) - Start cloud agent runs from your own systems with the {VARS.API_SDK_NAME}. +* [**Build programmatic automations**](/factories/api-and-sdk/quickstart/) - Start cloud agent runs from your own systems with the {VARS.API_SDK_NAME}. For example, schedule a recurring agent from the CLI: @@ -135,13 +135,13 @@ Integrations require a team on Build, Max, or Business plan. ## Troubleshooting **Environment creation fails**\ -Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/platform/environments/) for more guidance on choosing Docker images and [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the related API error. +Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/platform/environments/) for more guidance on choosing Docker images and [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the related API error. **Agent can't access repos**\ -Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works) and [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). For automated workflows using an agent API key, make sure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`; permission mismatches can surface as [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). +Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/agents/cli/oz-cli/integration-setup/#how-github-authorization-works) and [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/). For automated workflows using an agent API key, make sure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`; permission mismatches can surface as [`not_authorized`](/factories/api-and-sdk/troubleshooting/errors/not-authorized/). **Not enough credits to run cloud agents**\ -Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. If a run is blocked because the billed principal has no remaining credits, see [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). +Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. If a run is blocked because the billed principal has no remaining credits, see [`insufficient_credits`](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/). **More resources** diff --git a/src/content/docs/platform/secrets.mdx b/src/content/docs/platform/secrets.mdx index e336eb55c..2290c7fae 100644 --- a/src/content/docs/platform/secrets.mdx +++ b/src/content/docs/platform/secrets.mdx @@ -290,7 +290,7 @@ Individual runs can override which secrets the run receives by listing them on t * **Explicit list of secret names** - Only the listed secrets are injected. Any other secrets the caller can access are skipped for this run. * **Empty list** - The run opts out of all secret injection. No managed secrets are injected, even for triggers that would otherwise receive them. -Run-level scoping is exposed through the public REST API on the run config. See the [{VARS.API_SDK_NAME} reference](/reference/api-and-sdk/) for the exact field and shape. +Run-level scoping is exposed through the public REST API on the run config. See the [{VARS.API_SDK_NAME} reference](/factories/api-and-sdk/) for the exact field and shape. :::note Secret names that don't exist in the caller's scope are silently skipped at injection time rather than failing the run. The run detail view surfaces any references that were requested but not resolved so you can spot typos or stale names. diff --git a/src/content/docs/platform/self-hosting/index.mdx b/src/content/docs/platform/self-hosting/index.mdx deleted file mode 100644 index baaa956c6..000000000 --- a/src/content/docs/platform/self-hosting/index.mdx +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: Self-hosting overview -description: >- - Run cloud agents on your own infrastructure with a managed worker daemon or - unmanaged CLI-based execution you control. ---- -import { VARS } from '@data/vars'; - -Self-hosting lets your team run cloud agent workloads on your own infrastructure instead of Warp-managed servers. You control the execution environment, compute resources, and network access. Repository clones, source files, build artifacts, runtime secrets, and agent execution workspaces stay on your infrastructure, and agents can reach services behind your VPN or firewall. - -**New to self-hosting?** Start with the [Self-hosting quickstart](/platform/self-hosting/quickstart/) to get a managed worker running on Docker in under 10 minutes. - -**Want a CLI-only path with no Docker requirement?** Jump straight to the [Unmanaged quickstart](/platform/self-hosting/unmanaged/#unmanaged-quickstart) to run `oz agent run` directly on any host. - -:::note -**Enterprise feature**: Self-hosted agents are available exclusively to teams on an Enterprise plan. To enable self-hosting for your team, [contact sales](https://www.warp.dev/contact-sales). -::: - -## Managed vs unmanaged - -Self-hosting has two architectures. The core distinction is **who orchestrates agent runs** — not who owns the compute. Both models keep code and execution on your infrastructure. - -* **Managed** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates agent runs. You run the `oz-agent-worker` daemon on your infrastructure; it connects to the {VARS.WARP_AUTOMATION_PLATFORM} and waits for work. [Slack](/platform/integrations/slack/) mentions, Linear comments, [schedules](/platform/triggers/scheduled-agents/), API calls, and `oz agent run-cloud` commands all route tasks to your worker, which executes them in isolated Docker containers, Kubernetes Jobs, or directly on the host. Similar to a [GitHub self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners). -* **Unmanaged** — You orchestrate agent runs. You invoke `oz agent run` directly from your existing CI pipeline, Kubernetes pod, VM, or dev box. The {VARS.WARP_AUTOMATION_PLATFORM} provides session tracking and observability for each run, but does not start or stop agents for you. - -### At a glance - -| Aspect | **Managed** | **Unmanaged** | -| --- | --- | --- | -| **Who triggers runs** | The {VARS.WARP_AUTOMATION_PLATFORM} (Slack, Linear, schedules, API, `run-cloud`) | Your system (CI, cron, scripts) | -| **What runs on your infra** | Long-lived `oz-agent-worker` daemon | One-shot `oz agent run` invocations | -| **OS support** | Linux (macOS/Windows coming) | Linux, macOS, Windows | -| **Execution isolation** | Docker container, Kubernetes Job, or direct host | Whatever your host provides | -| **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 deployment models diagram on [Deployment patterns](/platform/deployment-patterns/) compares what runs where in each model. - -## How self-hosting works - -Warp uses a split-plane architecture: **execution happens on your infrastructure**, while **orchestration, session management, and LLM inference route through Warp's backend**. Agent interactions — including code context in session transcripts and LLM prompts — transit Warp's control plane under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or train on it. - -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 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: - -* **Agent runs are tracked and steerable** — View status, metadata, and session transcripts in the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>, the Warp app, or via the [API/SDK](/reference/api-and-sdk/). Authorized teammates can attach to running sessions to monitor or steer agents. -* **Connectivity to Warp's backend is required** — Agents need outbound access to Warp for orchestration, session storage, and LLM inference. No inbound ports need to be opened. -* **Resource limits are controlled by your infrastructure** — Concurrency and compute are only limited by the machines you provision, not by Warp. - -:::note -Enterprise teams that need full control over LLM inference routing can use [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through their own cloud provider accounts. Cloud agent support varies by provider; see each provider's setup guide for details. -::: - ---- - -## Choosing an architecture - -:::caution -**OS support:** The managed architecture is **Linux-only** today (macOS and Windows support is coming). If you need agents to run on macOS or Windows, use the [unmanaged](/platform/self-hosting/unmanaged/) architecture, which works on any platform Warp supports. -::: - -Use these questions to decide between managed and unmanaged: - -1. **Do you need agents to run on Windows or macOS?** - * Yes → Use the [unmanaged](/platform/self-hosting/unmanaged/) architecture. Managed is Linux-only today. - * No, Linux works → Continue to the next question. -2. **Do you want the {VARS.WARP_AUTOMATION_PLATFORM} to handle starting and stopping agents** (from Slack, the web interface, the Warp app, schedules, or the API)? - * Yes → Use the [managed](#managed-architecture) architecture. - * No, you have your own triggering mechanism → Use the [unmanaged](/platform/self-hosting/unmanaged/) architecture. -3. **Can your development environment run in a Docker container or Kubernetes pod?** - * Yes, Docker → [Managed: Docker](/platform/self-hosting/managed-docker/) backend. - * Yes, Kubernetes → [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) backend. - * No (multi-service stacks that don't fit a single container, or environments where container runtimes aren't available) → [Unmanaged](/platform/self-hosting/unmanaged/) or [Managed: Direct](/platform/self-hosting/managed-direct/). -4. **Do you have your own orchestrator** (CI/CD, Kubernetes, internal job scheduler) **that starts agents on demand?** - * Yes → [Unmanaged](/platform/self-hosting/unmanaged/), using `oz agent run` as a drop-in. - * No → [Managed](#managed-architecture). - -### Choosing a managed backend - -The managed architecture supports three backends for task execution: - -1. **Are you deploying the worker into a Kubernetes cluster?** - * Yes → Use the [Kubernetes backend](/platform/self-hosting/managed-kubernetes/). Each task runs as a Kubernetes Job in your cluster; install with the included Helm chart. - * No → Continue. -2. **Is Docker available on your worker host?** - * Yes → Use the [Docker backend](/platform/self-hosting/managed-docker/) (default). Tasks run in isolated containers. - * No → Use the [Direct backend](/platform/self-hosting/managed-direct/). Tasks run directly on the host. -3. **Do you need container-level isolation between tasks?** - * Yes → [Docker](/platform/self-hosting/managed-docker/) or [Kubernetes](/platform/self-hosting/managed-kubernetes/) backend. - * No → Any backend works. -4. **Do you need Kubernetes-native scheduling, resource management, or policy enforcement?** - * Yes → [Kubernetes backend](/platform/self-hosting/managed-kubernetes/). - * No → [Docker](/platform/self-hosting/managed-docker/) or [Direct](/platform/self-hosting/managed-direct/) is simpler to set up. - ---- - -## Managed architecture - -With the managed architecture, you run the `oz-agent-worker` daemon on your infrastructure. The daemon connects to the {VARS.WARP_AUTOMATION_PLATFORM}'s backend, waits for tasks to be assigned to it, and executes those tasks on its host using one of three backends: - -* **[Docker backend](/platform/self-hosting/managed-docker/)** (default) — Runs each task in an isolated Docker container. -* **[Kubernetes backend](/platform/self-hosting/managed-kubernetes/)** — Runs each task as a Kubernetes Job in your cluster. -* **[Direct backend](/platform/self-hosting/managed-direct/)** — Runs each task directly on the host without a container runtime. - -The managed architecture enables full orchestration by the {VARS.WARP_AUTOMATION_PLATFORM} — it can remotely start agents via Slack, Linear, the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a>, the API/SDK, and the `oz agent run-cloud` command. Agents can access host resources through volume mounts (Docker), Kubernetes-native configuration (Kubernetes), and injected environment variables. - -## Unmanaged architecture - -With the [unmanaged architecture](/platform/self-hosting/unmanaged/), you run `oz agent run` inside your own orchestrator or dev environment. This works on any platform Warp supports (Linux, macOS, Windows), with no dependency on Docker or any other sandboxing platform. - -You're responsible for executing `oz agent run` on your infrastructure — similar to how you'd integrate Claude Code or Codex CLI. The agent runs directly on the host, which could itself be a Kubernetes pod, VM, container, or CI runner. - ---- - -## Routing runs to self-hosted workers - -This section applies to **all managed backends** (Docker, Kubernetes, and Direct). Once a worker is connected, route cloud agent runs to it by specifying the `--host` flag (or equivalent) with your worker ID. The `--host` value must match the `--worker-id` of a connected worker exactly. - -:::note -Unmanaged runs don't need routing — you invoke `oz agent run` directly on the host where you want the agent to execute. Routing is only relevant for managed workers. -::: - -### From the CLI - -```bash -oz agent run-cloud --prompt "Refactor the authentication module" --host "my-worker" -``` - -You can combine `--host` with any other `run-cloud` flags, such as `--environment`, `--model`, `--mcp`, `--skill`, `--computer-use`, and `--attach`. - -### From scheduled agents - -When creating or updating a schedule, specify the host: - -```bash -oz schedule create --name "daily-cleanup" \ - --cron "0 9 * * *" \ - --prompt "Run dead code cleanup" \ - --environment ENV_ID \ - --host "my-worker" - -oz schedule update SCHEDULE_ID --host "my-worker" -``` - -### From integrations - -When creating or updating an integration, specify the host: - -```bash -oz integration create slack --host "my-worker" ... -oz integration update linear --host "my-worker" ... -``` - -All tasks created through that integration route to your self-hosted worker. - -### From the API and SDKs - -When creating a run via the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), include `worker_host` in the config: - -```bash -curl -X POST https://app.warp.dev/api/v1/agent/run \ - --header 'Authorization: Bearer YOUR_API_KEY' \ - --header 'Content-Type: application/json' \ - --data '{ - "prompt": "Refactor the authentication module", - "config": { - "environment_id": "ENV_ID", - "worker_host": "my-worker" - } - }' -``` - -### From the web UI - -When creating a run, schedule, or integration in the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a>, select your self-hosted worker from the host dropdown. - ---- - -## Environments with self-hosted workers - -Self-hosted workers fully support [environments](/platform/environments/). When a task specifies an environment, the worker resolves the Docker image, clones the repositories, runs setup commands, and executes the agent inside the prepared container or Kubernetes Job. - -The same environment can be used for both Warp-hosted and self-hosted runs without modification. If your agents need custom tools, binaries, scripts, or system packages, add them to the environment's Docker image. See [Environments](/platform/environments/) for details on creating and configuring custom images. - -:::note -With the Kubernetes backend, setting a [`default_image`](/platform/self-hosting/reference/#kubernetes-backend-config) on the worker lets you skip creating a Warp environment when all your tasks use the same base image. -::: - -:::caution -Musl-based Docker images (such as Alpine Linux) are not supported as task images. The agent runtime requires glibc. Use glibc-based images like Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images. -::: - -## Monitoring runs - -Self-hosted runs have the same observability as Warp-hosted runs: - -* **Run history** — View task status, history, and metadata in the {VARS.DASHBOARD}, hosted in the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a>, or filter by source and status in the [Agent Management Panel](/platform/managing-cloud-agents/). -* **Session sharing** — Authorized teammates can attach to running tasks to [monitor progress](/platform/viewing-cloud-agent-runs/). -* **APIs and SDKs** — Query task history and build monitoring using the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). - -For infrastructure-level observability, the `oz-agent-worker` daemon can export OpenTelemetry metrics (worker health, task throughput, capacity saturation) to Prometheus, an OTLP collector, or the console. See [Monitoring](/platform/self-hosting/monitoring/) for setup, the full metric catalog, and sample PromQL queries. - ---- - -## Related pages - -* [Self-hosting quickstart](/platform/self-hosting/quickstart/) — Get a managed worker running in ~10 minutes. -* [Unmanaged](/platform/self-hosting/unmanaged/) — Run `oz agent run` in your CI, K8s, or dev environment. -* [Managed: Docker](/platform/self-hosting/managed-docker/) — Default managed setup with the Docker backend. -* [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Managed setup with the Kubernetes backend and Helm chart. -* [Managed: Direct](/platform/self-hosting/managed-direct/) — Managed setup with no container runtime. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config file schema. -* [Monitoring](/platform/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries, network egress, and security considerations. -* [Troubleshooting](/platform/self-hosting/troubleshooting/) — Worker won't start, tasks not picked up, and other common issues. -* [Deployment patterns](/platform/deployment-patterns/) — How self-hosting compares to CLI-only and Warp-hosted deployment. -* [Scheduled agents](/platform/triggers/scheduled-agents/) — Route recurring cloud agent work to a self-hosted worker with `--host`. -* [Integrations](/platform/integrations/) — Point Slack, Linear, and other triggers at a self-hosted worker. -* [Managing cloud agents](/platform/managing-cloud-agents/) — Inspect self-hosted runs alongside Warp-hosted ones. -* [Environments](/platform/environments/) — Define the runtime context for agent tasks. -* [Customizing workspace snapshots](/platform/handoff/snapshots/) — Configure end-of-run snapshots so handoff works when running outside the bundled cloud agent image. diff --git a/src/content/docs/platform/skills-as-agents.mdx b/src/content/docs/platform/skills-as-agents.mdx index e2e7d5ed7..56f3c284b 100644 --- a/src/content/docs/platform/skills-as-agents.mdx +++ b/src/content/docs/platform/skills-as-agents.mdx @@ -52,7 +52,7 @@ For cloud agent runs (`oz agent run-cloud`), skills are discovered from reposito 3. **The skill appears** in the Agents list in the {VARS.WEB_APP} :::note -You can also list available skills programmatically using the `GET /agent` endpoint. See the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) reference for details. +You can also list available skills programmatically using the `GET /agent` endpoint. See the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) reference for details. ::: ### Extra skill directories in cloud runs @@ -105,7 +105,7 @@ oz agent run-cloud \ --prompt "additional context" ``` -For full CLI documentation, see [Using skills](/reference/cli/#using-skills) in the CLI reference. +For full CLI documentation, see [Using skills](/agents/cli/oz-cli/#using-skills) in the CLI reference. ### API & SDK @@ -121,7 +121,7 @@ Use the `skill_spec` parameter when creating a run: } ``` -For full API documentation, see [Agent configuration](/reference/api-and-sdk/#agent-configuration) in the API reference. +For full API documentation, see [Agent configuration](/factories/api-and-sdk/#agent-configuration) in the API reference. --- @@ -164,5 +164,5 @@ Suggested skills appear on the Agents page under the **Suggested** filter. * [Environments](/platform/environments/) — Configure repositories and runtime context for cloud agents * [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [{VARS.WEB_APP}](/platform/oz-web-app/) — Visual interface for managing cloud agents -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — Command-line interface for running agents -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — Programmatic access to cloud agents +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Command-line interface for running agents +* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — Programmatic access to cloud agents diff --git a/src/content/docs/platform/team-access-billing-and-identity.mdx b/src/content/docs/platform/team-access-billing-and-identity.mdx index 094b0b384..413c04936 100644 --- a/src/content/docs/platform/team-access-billing-and-identity.mdx +++ b/src/content/docs/platform/team-access-billing-and-identity.mdx @@ -110,7 +110,7 @@ This ensures runs are scoped to what the user is allowed to see and modify, and By default, cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Warp Factories** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual's token. -This is useful for fully automated workflows that use an [agent API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. +This is useful for fully automated workflows that use an [agent API key](/agents/cli/oz-cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. ### How it works @@ -233,9 +233,9 @@ How credits are consumed depends on how the agent run is triggered and authentic * On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the team's shared add-on credit pool. With auto-reload off, the request is blocked when both are depleted. With auto-reload on, usage can trigger a reload into the team's shared pool subject to the team-wide monthly spend cap. * On Enterprise plans, these runs draw from the team-scoped credit pool, per your Enterprise contract terms. * Ideal for CI/CD pipelines, scheduled tasks, and other automated workflows. -* For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Warp Factories GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. +* For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Warp Factories GitHub App. Alternatively, use a [personal API key](/agents/cli/oz-cli/api-keys/) to authenticate as an individual user. -For more details on creating and using API keys, see [API Keys](/reference/cli/api-keys/). +For more details on creating and using API keys, see [API Keys](/agents/cli/oz-cli/api-keys/). :::note When a user triggers an agent via Slack or Linear, the run still follows that same order — plan-included credits first, then shared team grants, then any applicable user-scoped grants — as long as the triggering user's identity can be mapped to their Warp account. @@ -263,9 +263,9 @@ It's the team's responsibility to manage triggers, confirm they behave as intend If a cloud agent or integration run fails with an error code, use the error reference to narrow the fix: -* **Missing GitHub or external authorization** - See [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) when a user needs to authorize GitHub, Slack, or Linear before a run can continue. -* **Insufficient repo permissions** - See [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/) when the triggering user or GitHub App lacks access to the repo the agent needs. -* **Credits or spend caps block a run** - See [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) or [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/) when the billed account has depleted credits or reached a configured spend cap. +* **Missing GitHub or external authorization** - See [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) when a user needs to authorize GitHub, Slack, or Linear before a run can continue. +* **Insufficient repo permissions** - See [`not_authorized`](/factories/api-and-sdk/troubleshooting/errors/not-authorized/) when the triggering user or GitHub App lacks access to the repo the agent needs. +* **Credits or spend caps block a run** - See [`insufficient_credits`](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/) or [`budget_exceeded`](/factories/api-and-sdk/troubleshooting/errors/budget-exceeded/) when the billed account has depleted credits or reached a configured spend cap. --- diff --git a/src/content/docs/platform/triggers/index.mdx b/src/content/docs/platform/triggers/index.mdx index c30ca6039..f204f1303 100644 --- a/src/content/docs/platform/triggers/index.mdx +++ b/src/content/docs/platform/triggers/index.mdx @@ -15,8 +15,8 @@ If you're choosing between schedules, Slack, Linear, GitHub, GitHub Actions, the ## Available trigger types * **[Scheduled Agents](/platform/triggers/scheduled-agents/)** - Run agents on a recurring schedule using cron expressions. -* **[CLI](/reference/cli/)** - Trigger cloud agents directly from your terminal using the {VARS.WARP_AGENT_CLI}. -* **[API & SDK](/reference/api-and-sdk/)** - Programmatically trigger agents via the Warp API or SDK. +* **[CLI](/agents/cli/oz-cli/)** - Trigger cloud agents directly from your terminal using the {VARS.WARP_AGENT_CLI}. +* **[API & SDK](/factories/api-and-sdk/)** - Programmatically trigger agents via the Warp API or SDK. * **[Integrations](/platform/integrations/)** - Trigger agents from external services like Slack, Linear, or Jira. * **[GitHub](/platform/integrations/github/)** - Mention `@warp-agent` on an issue, pull request, or review comment to start an agent that replies in the thread. * **[GitHub Actions](/platform/integrations/github-actions/)** - Run agents from your own CI workflows and repository events. diff --git a/src/content/docs/platform/triggers/scheduled-agents.mdx b/src/content/docs/platform/triggers/scheduled-agents.mdx index f9e8b71f6..55e633cf1 100644 --- a/src/content/docs/platform/triggers/scheduled-agents.mdx +++ b/src/content/docs/platform/triggers/scheduled-agents.mdx @@ -69,7 +69,7 @@ Use `oz schedule create` (with required flags) to define a new Scheduled Agent. * A cron schedule. * A prompt or skill that the agent will execute. * An optional environment in which the agent will run. -* An optional [model selection](/reference/cli/#using-agent-profiles). +* An optional [model selection](/agents/cli/oz-cli/#using-agent-profiles). * [Optional MCP server configuration](/platform/mcp/). ```bash @@ -115,7 +115,7 @@ oz schedule create \ Once created, the agent will automatically run at the specified times without further action. -Scheduled Agents support the same [model selection](/reference/cli/) and [MCP server configuration](/platform/mcp/) as other cloud agent triggers. +Scheduled Agents support the same [model selection](/agents/cli/oz-cli/) and [MCP server configuration](/platform/mcp/) as other cloud agent triggers. #### Cron schedule format @@ -290,7 +290,7 @@ Each scheduled run behaves like a standard cloud agent run, with a few important * Runs execute automatically without human intervention. * All usage is billed to the team’s shared credit balance. -If a scheduled run fails, it does not block future runs. Each execution is independent. Use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret any returned error code. +If a scheduled run fails, it does not block future runs. Each execution is independent. Use the [API error reference](/factories/api-and-sdk/troubleshooting/errors/) to interpret any returned error code. ### Permissions and responsibility diff --git a/src/content/docs/platform/self-hosting/unmanaged.mdx b/src/content/docs/platform/unmanaged-execution.mdx similarity index 89% rename from src/content/docs/platform/self-hosting/unmanaged.mdx rename to src/content/docs/platform/unmanaged-execution.mdx index 49cf1d397..68df30864 100644 --- a/src/content/docs/platform/self-hosting/unmanaged.mdx +++ b/src/content/docs/platform/unmanaged-execution.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; With the unmanaged architecture, **you orchestrate agent runs** by invoking `oz agent run` directly from your existing CI pipelines, Kubernetes pods, VMs, or dev boxes. The agent runs on whatever host the command is executed from; Warp tracks the session for you but does not start or stop agents. :::note -Unmanaged is the right choice if you already have a system that schedules work (CI, internal orchestrators, cron, dev environments). If you'd rather have the {VARS.WARP_AUTOMATION_PLATFORM} trigger and route runs from Slack, Linear, schedules, or the API, use the [managed architecture](/platform/self-hosting/#managed-architecture) instead. +Unmanaged is the right choice if you already have a system that schedules work (CI, internal orchestrators, cron, dev environments). If you'd rather have the {VARS.WARP_AUTOMATION_PLATFORM} trigger and route runs from Slack, Linear, schedules, or the API, use the [managed architecture](/factories/self-hosting/#managed-architecture) instead. ::: ## When to use unmanaged @@ -33,8 +33,8 @@ No Docker, no worker daemon, no environment required — just the {VARS.WARP_AGE ### Prerequisites -* **The {VARS.WARP_AGENT_CLI}** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. -* **A Warp API key** — For automation, create an agent API key in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. +* **The {VARS.WARP_AGENT_CLI}** installed on the machine where agents will run. See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli) for platform-specific instructions. +* **A Warp API key** — For automation, create an agent API key in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. See [API Keys](/agents/cli/oz-cli/api-keys/) for personal vs. agent guidance. ### 1. Authenticate @@ -123,7 +123,7 @@ Unmanaged agents are tracked on Warp's backend. Each run creates a persistent se * **View** in the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>. * **Attach to** via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer. -* **Query** through the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) for custom dashboards or monitoring. +* **Query** through the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) for custom dashboards or monitoring. Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/platform/mcp/), [secrets](/platform/secrets/), Warp Drive context, and saved prompts all apply. @@ -133,8 +133,8 @@ Unmanaged runs don't ship with the bundled declarations script, so end-of-run wo ## Related pages -* [Self-hosting overview](/platform/self-hosting/) — Compare managed and unmanaged, plus the architecture decision guide. +* [Self-hosting overview](/factories/self-hosting/) — Compare managed and unmanaged, plus the architecture decision guide. * [GitHub Actions integration](/platform/integrations/github-actions/) — Run agents in CI with the official action. -* [Deployment patterns](/platform/deployment-patterns/) — Pattern 1 (CLI-only) explains the unmanaged model conceptually. -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — Full CLI reference for `oz agent run` and related commands. +* [Deployment patterns](/factories/deployment-patterns/) — Pattern 1 (CLI-only) explains the unmanaged model conceptually. +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Full CLI reference for `oz agent run` and related commands. * [Agent Session Sharing](/agents/local-agents/session-sharing/) — Attach to running sessions to monitor or steer them. diff --git a/src/content/docs/platform/viewing-cloud-agent-runs.mdx b/src/content/docs/platform/viewing-cloud-agent-runs.mdx index 12cb6f3b1..54d9b0128 100644 --- a/src/content/docs/platform/viewing-cloud-agent-runs.mdx +++ b/src/content/docs/platform/viewing-cloud-agent-runs.mdx @@ -9,7 +9,7 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Cloud agent session sharing lets you open, inspect, and continue interacting with agent tasks that are running on remote virtual machines. Whether a cloud agent was triggered from [integrations](/platform/integrations/) like Slack, Linear, GitHub Actions, or the [{VARS.WARP_AGENT_CLI}](/reference/cli/), you can view its full session, follow along in real time, ask follow-up questions, and even "fork" the work into your local Warp environment. +Cloud agent session sharing lets you open, inspect, and continue interacting with agent tasks that are running on remote virtual machines. Whether a cloud agent was triggered from [integrations](/platform/integrations/) like Slack, Linear, GitHub Actions, or the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), you can view its full session, follow along in real time, ask follow-up questions, and even "fork" the work into your local Warp environment. Use cloud agent session sharing when you need to inspect a cloud agent run, debug a failed automation, or give teammates a shared record of what the agent did. The shared session is the review surface for the run: it shows the prompt, plan, commands, logs, outputs, and follow-up messages where available. @@ -37,7 +37,7 @@ Everything is accessible whether or not Warp is installed on the viewer’s mach #### 1. Open a remote cloud agent run -When a cloud agent starts working — for example, from a Slack mention, a Linear issue, or a [CLI](/reference/cli/) trigger — Warp attaches a shareable link to the run. +When a cloud agent starts working — for example, from a Slack mention, a Linear issue, or a [CLI](/agents/cli/oz-cli/) trigger — Warp attaches a shareable link to the run. * From [Slack](/platform/integrations/slack/), click **View Agent** in the agent response to open the session. * From [Linear](/platform/integrations/linear/), click the ↗ **Warp** button ("Open in Warp") on the ticket to open the session. diff --git a/src/content/docs/reference/index.mdx b/src/content/docs/reference/index.mdx deleted file mode 100644 index 59996046e..000000000 --- a/src/content/docs/reference/index.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Technical reference -description: >- - Technical reference documentation for the {{WARP_AGENT_CLI}}, API, and SDK. ---- -import { VARS } from '@data/vars'; - -Technical reference documentation for the {VARS.WARP_AGENT_CLI}, API, and SDKs. Use these programmatic interfaces to run and manage agents from CI pipelines, scripts, backend services, and custom tooling without requiring the Warp desktop app. - -## CLI - -The [{VARS.WARP_AGENT_CLI}](/reference/cli/) lets you run and configure agents from any environment — locally, in CI pipelines, or on remote machines. - -- [API Keys](/reference/cli/api-keys/) - Create and manage API keys to authenticate the {VARS.WARP_AGENT_CLI} without human interaction, ideal for CI pipelines, headless servers, and containers. -- [Agent Profiles](/reference/cli/agent-profiles/) - Use agent profiles to control what the agent can access, how it behaves, and where it can act, including file access, command execution, and MCP server usage. -- [MCP Servers](/reference/cli/mcp-servers/) - Pass MCP server configuration to agent runs using the `--mcp` flag, by UUID, inline JSON, or file path. -- [Skills](/reference/cli/skills/) - Run agents from reusable instruction sets stored in your repositories using the `--skill` flag. -- [Warp Drive Context](/reference/cli/warp-drive/) - Reference saved prompts, notebooks, workflows, and rules from Warp Drive directly in CLI agent commands. -- [Integration Setup](/reference/cli/integration-setup/) - Configure environments and connect external tools like Slack and Linear so you can trigger agents from outside the terminal. -- [Troubleshooting](/reference/cli/troubleshooting/) - Find solutions to common CLI errors, including authentication issues, agent failures, environment problems, and Docker image issues. - -## API & SDK - -The [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) lets you create and monitor cloud agent runs over HTTP. Official SDKs for [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) provide typed clients with built-in retries and error handling. - -- [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) - example integration diff --git a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx index ceaf3c34a..f02dcf605 100644 --- a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx @@ -256,7 +256,7 @@ The waterfall is: When auto-reload is **off**, the request is blocked once both buckets are depleted. When auto-reload is **on**, cloud agent usage can trigger auto-reload into the team's shared pool subject to the team-wide spend cap; further cloud agent runs then draw from that reloaded balance until the cap is reached. -"Blocked" means the run fails immediately with an insufficient-credits error rather than queuing or retrying. For unattended runs (scheduled jobs, team-API-key triggers), this manifests as a failed run in the {VARS.DASHBOARD} with an [insufficient credits](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) error code; the run won't be retried automatically. Owners should monitor the dashboard and configure spend caps with headroom for critical scheduled workloads. +"Blocked" means the run fails immediately with an insufficient-credits error rather than queuing or retrying. For unattended runs (scheduled jobs, team-API-key triggers), this manifests as a failed run in the {VARS.DASHBOARD} with an [insufficient credits](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/) error code; the run won't be retried automatically. Owners should monitor the dashboard and configure spend caps with headroom for critical scheduled workloads. :::note Enterprise plans support team-scoped credit pools, so this traffic draws from the team pool rather than an individual admin. See [enterprise billing](/enterprise/support-and-resources/billing/) for overage and contract terms. diff --git a/src/sidebar.ts b/src/sidebar.ts index 5115ad6ef..faa486f0d 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -389,19 +389,16 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // next door, since the underlying concepts are the same. items: [ { - // 'Getting started', not 'Get started': matches the Terminal, - // Enterprise, and Guides tabs. - label: 'Getting started', + label: 'Overview', items: [ { slug: 'factories', label: 'Overview' }, - { slug: 'factories/quickstart', label: 'Quickstart' }, - // 'Warp' is redundant inside the Factories tab, and the sibling - // labels ('Factory agents', 'Factory MCP') drop it too. This also - // resolves a desync: the page's own frontmatter label already said - // 'How Factories work', which this override was silently shadowing. { slug: 'factories/how-factories-work', label: 'How Factories work' }, ], }, + { + label: 'Get started', + items: [{ slug: 'factories/quickstart', label: 'Quickstart' }], + }, { // Parallel to 'Agent configuration' in the Automation Platform tab. // Scoped to the factory itself: who runs the work, how it is defined, @@ -414,8 +411,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // now the Automations primitive's conceptual home, parallel to Factory // agents and Factory skills, not just a filters reference. { slug: 'factories/automations', label: 'Factory automations' }, - { slug: 'factories/factory-as-code', label: 'Factory definition' }, - { slug: 'factories/infrastructure-and-security', label: 'Infrastructure & security' }, + { slug: 'factories/factory-as-code', label: 'Definitions as code' }, ], }, { @@ -457,6 +453,36 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/factory-mcp', label: 'Factory MCP' }, ], }, + { + label: 'Developer tools', + items: [ + { slug: 'factories/developer-tools', label: 'Overview' }, + { slug: 'factories/factory-api', label: 'Factory API' }, + { slug: 'factories/api-and-sdk', label: VARS.API_SDK_NAME }, + { label: 'API reference', link: '/api' }, + { slug: 'factories/api-and-sdk/troubleshooting', label: 'API troubleshooting' }, + { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'API errors' }, + { slug: 'factories/factory-mcp', label: 'Factory MCP' }, + { slug: 'factories/webhooks', label: 'Webhooks' }, + ], + }, + { + label: 'Infrastructure & security', + items: [ + { slug: 'factories/infrastructure-and-security', label: 'Overview' }, + { slug: 'factories/deployment-patterns', label: 'Deployment patterns' }, + { slug: 'factories/warp-hosting', label: 'Warp-hosted execution' }, + { slug: 'factories/runners', label: 'Runners' }, + { slug: 'factories/self-hosting', label: 'Managed self-hosting' }, + { slug: 'factories/self-hosting/quickstart', label: 'Self-hosting quickstart' }, + { slug: 'factories/self-hosting/managed-docker', label: 'Docker backend' }, + { slug: 'factories/self-hosting/managed-kubernetes', label: 'Kubernetes backend' }, + { slug: 'factories/self-hosting/managed-direct', label: 'Direct backend' }, + 'factories/self-hosting/monitoring', + { slug: 'factories/self-hosting/reference', label: 'Worker reference' }, + 'factories/self-hosting/troubleshooting', + ], + }, { // Same label as the Automation Platform tab's group for watching and // steering runs, because it covers the same ground one level up: the @@ -571,6 +597,8 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ }, { slug: 'platform/team-access-billing-and-identity', label: 'Access, billing, and identity' }, { slug: 'platform/faqs', label: 'Cloud agent FAQs' }, + { slug: 'platform/unmanaged-execution', label: 'Unmanaged execution' }, + { slug: 'platform/execution-security', label: 'Execution security' }, ], }, { @@ -579,7 +607,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'platform/environments', label: 'Overview' }, { slug: 'platform/environments/configuring-environments', label: 'Configuring environments' }, { slug: 'platform/environments/troubleshooting-environments', label: 'Troubleshooting' }, - { slug: 'platform/runners', label: 'Runners' }, ], }, { @@ -641,105 +668,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'platform/orchestration/multi-agent-runs', label: 'Running orchestrated agents' }, ], }, - { - // Named for what the group contains, not just its largest member: it - // holds a comparison page (deployment-patterns), a Warp-HOSTED page, - // and the self-hosting set. Labeling it 'Self-hosting' put - // '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 - // whole group's, not self-hosting's. Both match their page titles. - { slug: 'platform/self-hosting', label: 'Self-hosting overview' }, - { slug: 'platform/self-hosting/quickstart', label: 'Self-hosting quickstart' }, - { slug: 'platform/self-hosting/managed-docker', label: 'Managed: Docker' }, - { slug: 'platform/self-hosting/managed-kubernetes', label: 'Managed: Kubernetes' }, - { slug: 'platform/self-hosting/managed-direct', label: 'Managed: Direct' }, - { slug: 'platform/self-hosting/unmanaged', label: 'Unmanaged' }, - 'platform/self-hosting/monitoring', - { slug: 'platform/self-hosting/reference', label: 'Self-hosted worker reference' }, - 'platform/self-hosting/security-and-networking', - { slug: 'platform/self-hosting/troubleshooting', label: 'Troubleshooting' }, - ], - }, - ], - }, - { - label: 'API & Reference', - link: '/reference/', - icon: 'open-book', - items: [ - { - // API Reference promoted to the top of the sidebar (was buried 3 - // levels deep under API & SDK) per HYC/Rachael's Slack discussion on - // discoverability after the top-level API tab was removed. - label: 'Technical Reference', - items: [ - { slug: 'reference', label: 'Overview' }, - { label: 'API Reference', link: '/api' }, - ], - }, - { - label: 'CLI', - items: [ - { slug: 'reference/cli', label: `${VARS.WARP_AGENT_CLI} (legacy)` }, - { slug: 'reference/cli/quickstart', label: 'Quickstart' }, - { slug: 'reference/cli/api-keys', label: 'API Keys' }, - { slug: 'reference/cli/agent-profiles', label: 'Agent Profiles' }, - { slug: 'reference/cli/mcp-servers', label: 'MCP Servers' }, - { slug: 'reference/cli/skills', label: 'Skills' }, - { slug: 'reference/cli/warp-drive', label: 'Warp Drive Context' }, - { slug: 'reference/cli/integration-setup', label: 'Integration Setup' }, - { slug: 'reference/cli/artifacts', label: 'Artifacts' }, - { slug: 'reference/cli/federate', label: 'Federated identity' }, - 'reference/cli/troubleshooting', - ], - }, - { - label: 'API & SDK', - items: [ - { slug: 'reference/api-and-sdk', label: VARS.API_SDK_NAME }, - { slug: 'reference/api-and-sdk/quickstart', label: 'Quickstart' }, - // API Reference link moved to the top-level 'Technical Reference' - // group above for discoverability -- not duplicated here. - 'reference/api-and-sdk/demo-sentry-monitoring-with-sdk', - { - label: 'API Troubleshooting', - collapsed: true, - items: [ - { slug: 'reference/api-and-sdk/troubleshooting', label: 'API Troubleshooting' }, - { - label: 'Errors', - collapsed: true, - items: [ - { slug: 'reference/api-and-sdk/troubleshooting/errors', label: 'Errors' }, - 'reference/api-and-sdk/troubleshooting/errors/insufficient-credits', - 'reference/api-and-sdk/troubleshooting/errors/feature-not-available', - 'reference/api-and-sdk/troubleshooting/errors/external-authentication-required', - 'reference/api-and-sdk/troubleshooting/errors/not-authorized', - 'reference/api-and-sdk/troubleshooting/errors/invalid-request', - 'reference/api-and-sdk/troubleshooting/errors/resource-not-found', - 'reference/api-and-sdk/troubleshooting/errors/budget-exceeded', - 'reference/api-and-sdk/troubleshooting/errors/integration-disabled', - 'reference/api-and-sdk/troubleshooting/errors/integration-not-configured', - 'reference/api-and-sdk/troubleshooting/errors/operation-not-supported', - 'reference/api-and-sdk/troubleshooting/errors/environment-setup-failed', - 'reference/api-and-sdk/troubleshooting/errors/content-policy-violation', - 'reference/api-and-sdk/troubleshooting/errors/conflict', - 'reference/api-and-sdk/troubleshooting/errors/authentication-required', - 'reference/api-and-sdk/troubleshooting/errors/resource-unavailable', - 'reference/api-and-sdk/troubleshooting/errors/internal-error', - 'reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout', - 'reference/api-and-sdk/troubleshooting/errors/agent-process-failed', - ], - }, - ], - }, - ], - }, ], }, { diff --git a/vercel.json b/vercel.json index 55a2455af..2ced957f4 100644 --- a/vercel.json +++ b/vercel.json @@ -6557,6 +6557,91 @@ "destination": "/agents/", "statusCode": 308 }, + { + "source": "/platform/warp-hosting", + "destination": "/factories/warp-hosting/", + "statusCode": 308 + }, + { + "source": "/platform/runners", + "destination": "/factories/runners/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting", + "destination": "/factories/self-hosting/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/quickstart", + "destination": "/factories/self-hosting/quickstart/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/managed-docker", + "destination": "/factories/self-hosting/managed-docker/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/managed-kubernetes", + "destination": "/factories/self-hosting/managed-kubernetes/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/managed-direct", + "destination": "/factories/self-hosting/managed-direct/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/monitoring", + "destination": "/factories/self-hosting/monitoring/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/reference", + "destination": "/factories/self-hosting/reference/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/troubleshooting", + "destination": "/factories/self-hosting/troubleshooting/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/unmanaged", + "destination": "/platform/unmanaged-execution/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/security-and-networking", + "destination": "/platform/execution-security/", + "statusCode": 308 + }, + { + "source": "/reference", + "destination": "/factories/developer-tools/", + "statusCode": 308 + }, + { + "source": "/reference/api-and-sdk", + "destination": "/factories/api-and-sdk/", + "statusCode": 308 + }, + { + "source": "/reference/api-and-sdk/:path*", + "destination": "/factories/api-and-sdk/:path*", + "statusCode": 308 + }, + { + "source": "/reference/cli", + "destination": "/agents/cli/oz-cli/", + "statusCode": 308 + }, + { + "source": "/reference/cli/:path*", + "destination": "/agents/cli/oz-cli/:path*", + "statusCode": 308 + }, { "source": "/agents/cli-agents(/?)", "destination": "/agents/cli-agents/overview/", From 7ea34736fcc6260f6cedea08477f0849b10a67e6 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 11:36:58 -0600 Subject: [PATCH 02/46] docs: fix factories restructure review findings Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/agents/cli/oz-cli/federate.mdx | 2 +- src/content/docs/factories/developer-tools.mdx | 6 ++---- .../build-a-mattermost-bot-for-warp-factories.mdx | 2 +- vercel.json | 5 +++++ 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/src/content/docs/agents/cli/oz-cli/federate.mdx b/src/content/docs/agents/cli/oz-cli/federate.mdx index 03da8aaa7..a2bda5c55 100644 --- a/src/content/docs/agents/cli/oz-cli/federate.mdx +++ b/src/content/docs/agents/cli/oz-cli/federate.mdx @@ -94,7 +94,7 @@ A typical AWS flow: A typical GCP flow: 1. Run `oz federate issue-token` to get the OIDC JWT. -2. Call the [Security Token Service `token` endpoint](https://cloud.google.com/iam/docs/factories/developer-tools/sts/rest/v1/TopLevel/token) to exchange the JWT for a federated access token. +2. Call the [Security Token Service `token` endpoint](https://cloud.google.com/iam/docs/reference/sts/rest/v1/TopLevel/token) to exchange the JWT for a federated access token. 3. Optionally impersonate a service account for the final credentials. ## Related diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx index 85518d073..22c014a37 100644 --- a/src/content/docs/factories/developer-tools.mdx +++ b/src/content/docs/factories/developer-tools.mdx @@ -19,11 +19,9 @@ Warp Factories provides programmatic interfaces for sending work to a factory, i * **[Webhooks](/factories/webhooks/)** - Receive events from systems that can send JSON and route matching deliveries into factory automations. ## Use the API and SDK +Use the API and SDK for typed requests, retries, and error handling. Start with the [API and SDK quickstart](/factories/api-and-sdk/quickstart/) to create and inspect a run, or use the [Sentry monitoring example](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) to connect an external event source. - -# Use the API and SDK -es/webhooks/)** - Receive events from syfor typed requests, retries, and error handling. Start with the [Aes/webhooks/)** - Recei/factories/api-and-sdk/quickstart/) to create and inspect a run, or use the [Sentry monitoring example](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) to connect an external event source. -es/webhooks/)** - Recrequests, see [API troubleshooting](/factories/api-and-sdk/troubleshooting/) and the [API error reference](/factories/api-and-sdk/troubleshooting/errors/). +For request errors, see [API troubleshooting](/factories/api-and-sdk/troubleshooting/) and the [API error reference](/factories/api-and-sdk/troubleshooting/errors/). ## Related pages diff --git a/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx b/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx index c15261df9..d5641e581 100644 --- a/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx +++ b/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx @@ -14,7 +14,7 @@ Build a Mattermost bot that sends work to a [Warp factory](/factories/) and post * **A Warp Factories factory** - [Set up a factory](/factories/quickstart/) before starting; this guide dispatches work to an existing factory rather than creating one. * **A Warp API key** - Create an [agent API key](/agents/cli/oz-cli/api-keys/#personal-vs-agent-keys) rather than a personal key, so the bot's requests aren't tied to your individual account. -* **A Mattermost bot account and access token** - Create one from your Mattermost System Console under **Integrations** > **Bot Accounts**, and generate a personal access token for it. Mattermost's own [bot accounts documentation](https://developers.mattermost.com/integrate/factories/developer-tools/bot-accounts/) covers the exact steps, since they vary by Mattermost version and hosting setup. +* **A Mattermost bot account and access token** - Create one from your Mattermost System Console under **Integrations** > **Bot Accounts**, and generate a personal access token for it. Mattermost's own [bot accounts documentation](https://developers.mattermost.com/integrate/reference/bot-accounts/) covers the exact steps, since they vary by Mattermost version and hosting setup. * **The {VARS.API_SDK_NAME} Python SDK** - Install it with `pip install oz-agent-sdk`. If you're working in another language, the [factory API page](/factories/factory-api/) shows the equivalent REST calls. ## 1. Store your credentials diff --git a/vercel.json b/vercel.json index 2ced957f4..835e2d784 100644 --- a/vercel.json +++ b/vercel.json @@ -6557,6 +6557,11 @@ "destination": "/agents/", "statusCode": 308 }, + { + "source": "/platform/deployment-patterns", + "destination": "/factories/deployment-patterns/", + "statusCode": 308 + }, { "source": "/platform/warp-hosting", "destination": "/factories/warp-hosting/", From da013deadf59a87ff46c19420ef4ff07320dd1f3 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 13:12:28 -0600 Subject: [PATCH 03/46] docs: restore legacy CLI sidebar group Co-Authored-By: Warp <agent@warp.dev> --- src/sidebar.ts | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/sidebar.ts b/src/sidebar.ts index faa486f0d..b315bcd15 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -354,6 +354,23 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agents/cli/reference', label: 'CLI reference' }, ], }, + { + label: `${VARS.WARP_AGENT_CLI} (legacy)`, + collapsed: true, + items: [ + { slug: 'agents/cli/oz-cli', label: 'Overview' }, + { slug: 'agents/cli/oz-cli/quickstart', label: 'Quickstart' }, + { slug: 'agents/cli/oz-cli/api-keys', label: 'API keys' }, + { slug: 'agents/cli/oz-cli/agent-profiles', label: 'Agent profiles' }, + { slug: 'agents/cli/oz-cli/mcp-servers', label: 'MCP servers' }, + { slug: 'agents/cli/oz-cli/skills', label: 'Skills' }, + { slug: 'agents/cli/oz-cli/warp-drive', label: 'Warp Drive context' }, + { slug: 'agents/cli/oz-cli/integration-setup', label: 'Integration setup' }, + { slug: 'agents/cli/oz-cli/artifacts', label: 'Artifacts' }, + { slug: 'agents/cli/oz-cli/federate', label: 'Federated identity' }, + 'agents/cli/oz-cli/troubleshooting', + ], + }, { label: 'Third-Party CLI Agents', items: [ From 0ee8861e56dca24cd3d35798e6ffc213847c987c Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 13:56:41 -0600 Subject: [PATCH 04/46] docs: fix factory navigation checks Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/factories/self-hosting/index.mdx | 2 +- src/content/docs/index.mdx | 6 +++--- src/sidebar.ts | 1 + 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/content/docs/factories/self-hosting/index.mdx b/src/content/docs/factories/self-hosting/index.mdx index 1883bffd8..d58babe69 100644 --- a/src/content/docs/factories/self-hosting/index.mdx +++ b/src/content/docs/factories/self-hosting/index.mdx @@ -40,7 +40,7 @@ The worker requires outbound HTTPS access to Warp and any repositories, registri ## Configure a factory to use a worker -Define the worker host and a compatible runner in your [factory definition](/factories/factory-as-code/). The factory dashboard shows each configured runner and the worker that executes its work. Use the [worker reference](/factories/self-hosting/reference/) to configure the worker process and the [Factory dashboard](/factories/factory-dashboard/) to inspect its runs. +Define the worker host and a compatible runner in your [factory definition](/factories/factory-as-code/). The factory dashboard shows each configured runner and the worker that executes its work. Use the [worker reference](/factories/self-hosting/reference/) to configure the worker process and the [factory dashboard](/factories/factory-dashboard/) to inspect its runs. ## Monitor and troubleshoot workers diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index d7ae36460..30b6904d2 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -22,12 +22,12 @@ Warp is the desktop terminal for running commands, editing code, and working wit The Warp Agent helps you investigate issues, edit code, run commands, and complete multi-step work. Use it in the Warp app or from the [Warp Agent CLI](/agents/cli/), which runs the same agent in any terminal. -## Automation Platform +## {VARS.WARP_AUTOMATION_PLATFORM} The {VARS.WARP_AUTOMATION_PLATFORM} runs cloud agents from triggers, schedules, integrations, and APIs. Use it for background work such as issue triage, pull request review, and recurring maintenance. * [Cloud agents](/platform/) - Run background agent work in the cloud. -* [Automation Platform](/platform/overview/) - Configure environments, integrations, orchestration, and shared agent settings. +* [The {VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) - Configure environments, integrations, orchestration, and shared agent settings. ## Warp Factories @@ -38,7 +38,7 @@ Warp Factories is available in Early Access. A factory turns incoming engineerin ## How the products work together -Use Warp and the Warp Agent for interactive development. Use the Automation Platform for background agents and shared cloud configuration. Use Warp Factories when your team needs a standing workflow to route, review, and improve work across repositories. +Use Warp and the Warp Agent for interactive development. Use the {VARS.WARP_AUTOMATION_PLATFORM} for background agents and shared cloud configuration. Use Warp Factories when your team needs a standing workflow to route, review, and improve work across repositories. ## Next steps diff --git a/src/sidebar.ts b/src/sidebar.ts index b315bcd15..27010440b 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -477,6 +477,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/factory-api', label: 'Factory API' }, { slug: 'factories/api-and-sdk', label: VARS.API_SDK_NAME }, { label: 'API reference', link: '/api' }, + { slug: 'factories/api-and-sdk/demo-sentry-monitoring-with-sdk', label: 'Sentry monitoring with the SDK' }, { slug: 'factories/api-and-sdk/troubleshooting', label: 'API troubleshooting' }, { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'API errors' }, { slug: 'factories/factory-mcp', label: 'Factory MCP' }, From 6d83e8f8eeaa0b4c57d295c88d931e175aeb422d Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 14:28:05 -0600 Subject: [PATCH 05/46] docs: fix factories review checks Co-Authored-By: Warp <agent@warp.dev> --- .github/workflows/agent-docs-review.yml | 2 ++ .../factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx | 1 + src/content/docs/factories/api-and-sdk/index.mdx | 1 + src/content/docs/factories/api-and-sdk/quickstart.mdx | 1 + .../api-and-sdk/troubleshooting/errors/agent-process-failed.mdx | 1 + .../troubleshooting/errors/authentication-required.mdx | 1 + .../api-and-sdk/troubleshooting/errors/budget-exceeded.mdx | 1 + .../factories/api-and-sdk/troubleshooting/errors/conflict.mdx | 1 + .../troubleshooting/errors/content-policy-violation.mdx | 1 + .../troubleshooting/errors/environment-setup-failed.mdx | 1 + .../troubleshooting/errors/external-authentication-required.mdx | 1 + .../troubleshooting/errors/feature-not-available.mdx | 1 + .../docs/factories/api-and-sdk/troubleshooting/errors/index.mdx | 1 + .../troubleshooting/errors/infrastructure-timeout.mdx | 1 + .../api-and-sdk/troubleshooting/errors/insufficient-credits.mdx | 1 + .../api-and-sdk/troubleshooting/errors/integration-disabled.mdx | 1 + .../troubleshooting/errors/integration-not-configured.mdx | 1 + .../api-and-sdk/troubleshooting/errors/internal-error.mdx | 1 + .../api-and-sdk/troubleshooting/errors/invalid-request.mdx | 1 + .../api-and-sdk/troubleshooting/errors/not-authorized.mdx | 1 + .../troubleshooting/errors/operation-not-supported.mdx | 1 + .../api-and-sdk/troubleshooting/errors/resource-not-found.mdx | 1 + .../api-and-sdk/troubleshooting/errors/resource-unavailable.mdx | 1 + .../docs/factories/api-and-sdk/troubleshooting/index.mdx | 1 + src/content/docs/factories/self-hosting/managed-direct.mdx | 2 +- src/content/docs/factories/self-hosting/managed-docker.mdx | 2 +- src/content/docs/factories/self-hosting/managed-kubernetes.mdx | 2 +- 27 files changed, 28 insertions(+), 3 deletions(-) diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 6b7b267c7..1918fc98c 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -60,6 +60,8 @@ jobs: changed file and line or quoted text, explain the problem, and state the requested resolution. Set reviewer_login to `github-actions[bot]`, the runner account that will publish the review. + 5. Your final response must contain only the single [SIGNAL:pr-review] JSON record. + Do not repeat the diff, review rationale, or findings outside that record. - name: Dismiss stale automated change requests env: GH_TOKEN: ${{ github.token }} diff --git a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index 3bdfd4c2f..d64295181 100644 --- a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: "Demo: Sentry monitoring with SDK" description: >- Build a Sentry webhook handler that triggers agents to investigate errors diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx index f60d954a6..3f2555796 100644 --- a/src/content/docs/factories/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: "{{API_SDK_NAME}} reference" sidebar: label: "{{API_SDK_NAME}}" diff --git a/src/content/docs/factories/api-and-sdk/quickstart.mdx b/src/content/docs/factories/api-and-sdk/quickstart.mdx index f500af542..6eeac8068 100644 --- a/src/content/docs/factories/api-and-sdk/quickstart.mdx +++ b/src/content/docs/factories/api-and-sdk/quickstart.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: "API & SDK quickstart" description: >- Create and monitor your first cloud agent run via the {{API_SDK_NAME}} in ~5 diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx index 421899ce4..52a7740fa 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: agent_process_failed description: >- The agent process exited unexpectedly during task execution. Retry the task diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx index c8c026b82..332140f14 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: authentication_required description: >- The API key in the request is invalid, expired, or missing. Generate a new diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx index b9e7e7cb8..cecf4fc26 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: budget_exceeded description: >- Your team's configured spending budget limit has been reached. Increase the diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx index c45972875..3cf340fdb 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: "Error: conflict (409)" sidebar: label: "conflict" diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx index ebc168b31..c27645de9 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: content_policy_violation description: >- The task prompt or environment setup commands were flagged by the platform's diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx index eb36310d0..598c0ea38 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: environment_setup_failed description: >- The cloud agent's environment failed to initialize. Check repo URLs, setup diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx index d1847c5bb..ec71c7fca 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: external_authentication_required description: >- The task requires access to an external service (GitHub, Slack, Linear, diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx index e911b9e14..fb9013b2d 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: feature_not_available description: >- The requested feature is not included in your current plan. Upgrade your diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx index 16dc9b825..1ca4dac8b 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: Errors Overview description: >- Reference for all error codes returned by the {{API_SDK_NAME}}. Each error diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx index e96660122..7e213ad0c 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: infrastructure_timeout description: >- The task was forcibly terminated because it remained active past the maximum diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx index 3eef34f85..c8000af6d 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: insufficient_credits description: >- The principal billed for the run has no remaining credits. Top up the diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx index aeff2a424..9f1a8a3a4 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: integration_disabled description: >- The integration (Slack, Linear, etc.) is currently disabled in the diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx index 775be7f26..e5da179e4 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: integration_not_configured description: >- The integration's setup is incomplete. Visit the setup URL to finish diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx index 1afacfd24..02a121076 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: internal_error description: >- An unexpected server-side error occurred. The platform will automatically diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx index ce6c6ec9f..3bce443c3 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: invalid_request description: >- The request body is malformed, missing required fields, or contains invalid diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx index a1870fea8..df721242f 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: not_authorized description: >- The authenticated user or API key does not have permission to perform the diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx index f57a68f50..b88945263 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: operation_not_supported description: >- The requested operation is not supported for this resource or its current diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx index 30feb59af..a75992bd0 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: resource_not_found description: >- The requested resource (task, environment, schedule, agent, etc.) does not diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx index 0e721a0c1..d0feae9af 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: resource_unavailable description: >- A transient infrastructure issue prevented the task from running. The diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx index ee151f68c..29101c02a 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: API Troubleshooting description: >- Troubleshooting resources for the {{API_SDK_NAME}}, including a full reference diff --git a/src/content/docs/factories/self-hosting/managed-direct.mdx b/src/content/docs/factories/self-hosting/managed-direct.mdx index 47e9917d9..d8c6035dd 100644 --- a/src/content/docs/factories/self-hosting/managed-direct.mdx +++ b/src/content/docs/factories/self-hosting/managed-direct.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Run the `oz-agent-worker` daemon with the **Direct backend** — tasks execute directly on the worker host without Docker or Kubernetes. The {VARS.WARP_AUTOMATION_PLATFORM} still orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); the worker just runs the agent in a per-task workspace on its own filesystem. :::note -This page covers the [managed architecture](/factories/self-hosting/#managed-architecture) with the Direct backend. For container-based task isolation, see [Managed: Docker](/factories/self-hosting/managed-docker/) or [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/). For invocation-driven use cases, see [Unmanaged](/platform/unmanaged-execution/). +The Direct backend uses the [managed architecture](/factories/self-hosting/#managed-architecture). For container-based task isolation, see [Managed: Docker](/factories/self-hosting/managed-docker/) or [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/). For invocation-driven use cases, see [Unmanaged](/platform/unmanaged-execution/). ::: ## When to use the Direct backend diff --git a/src/content/docs/factories/self-hosting/managed-docker.mdx b/src/content/docs/factories/self-hosting/managed-docker.mdx index 436be6b59..8206877c5 100644 --- a/src/content/docs/factories/self-hosting/managed-docker.mdx +++ b/src/content/docs/factories/self-hosting/managed-docker.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Run the `oz-agent-worker` daemon with the **Docker backend** — the default managed path. Each agent task runs in an isolated Docker container spawned from the worker, with full orchestration by the {VARS.WARP_AUTOMATION_PLATFORM} (Slack, Linear, schedules, API, `oz agent run-cloud`). :::note -This page covers the [managed architecture](/factories/self-hosting/#managed-architecture) with the Docker backend. For the Kubernetes backend, see [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/). For host execution without a container runtime, see [Managed: Direct](/factories/self-hosting/managed-direct/). If you'd rather invoke agents yourself, see [Unmanaged](/platform/unmanaged-execution/). +The Docker backend uses the [managed architecture](/factories/self-hosting/#managed-architecture). For the Kubernetes backend, see [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/). For host execution without a container runtime, see [Managed: Direct](/factories/self-hosting/managed-direct/). If you'd rather invoke agents yourself, see [Unmanaged](/platform/unmanaged-execution/). ::: ## When to use the Docker backend diff --git a/src/content/docs/factories/self-hosting/managed-kubernetes.mdx b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx index f1659e7ee..50a53700a 100644 --- a/src/content/docs/factories/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Deploy the `oz-agent-worker` daemon into a Kubernetes cluster using the included Helm chart. Each agent task runs as a **Kubernetes Job** in your cluster. The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); your cluster provides the compute, scheduling, and policy enforcement. :::note -This page covers the [managed architecture](/factories/self-hosting/#managed-architecture) with the Kubernetes backend. For the default Docker backend, see [Managed: Docker](/factories/self-hosting/managed-docker/). For host execution without a container runtime, see [Managed: Direct](/factories/self-hosting/managed-direct/). To route runs to a connected worker, see [Routing runs to this worker](/factories/self-hosting/managed-docker/#routing-runs-to-this-worker). +The Kubernetes backend uses the [managed architecture](/factories/self-hosting/#managed-architecture). For the default Docker backend, see [Managed: Docker](/factories/self-hosting/managed-docker/). For host execution without a container runtime, see [Managed: Direct](/factories/self-hosting/managed-direct/). To route runs to a connected worker, see [Routing runs to this worker](/factories/self-hosting/managed-docker/#routing-runs-to-this-worker). ::: ## When to use the Kubernetes backend From 6dda62b14eaa8909e7b80e3d7b5d283224f7e5b7 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 15:28:36 -0600 Subject: [PATCH 06/46] docs: complete factories GA phase 1 Co-Authored-By: Warp <agent@warp.dev> --- .../demo-sentry-monitoring-with-sdk.mdx | 2 + .../docs/factories/api-and-sdk/index.mdx | 10 ++- .../docs/factories/api-and-sdk/quickstart.mdx | 2 + .../docs/factories/deployment-patterns.mdx | 79 +++++++------------ .../docs/factories/factory-dashboard.mdx | 4 +- src/content/docs/factories/index.mdx | 2 +- .../factories/infrastructure-and-security.mdx | 1 + src/content/docs/factories/runners.mdx | 14 ++-- .../factories/self-hosting/quickstart.mdx | 4 +- src/content/docs/factories/warp-hosting.mdx | 18 +++-- src/content/docs/index.mdx | 2 +- src/content/docs/platform/environments.mdx | 2 + src/content/docs/platform/harnesses/index.mdx | 2 + src/content/docs/platform/index.mdx | 6 +- .../docs/platform/integrations/index.mdx | 2 + .../docs/platform/managing-cloud-agents.mdx | 2 + src/content/docs/platform/mcp.mdx | 2 + src/content/docs/platform/overview.mdx | 7 +- src/content/docs/platform/secrets.mdx | 2 + .../docs/platform/skills-as-agents.mdx | 2 + .../docs/platform/transitioning-from-oz.mdx | 37 +++++++++ src/content/docs/platform/triggers/index.mdx | 2 + src/sidebar.ts | 26 +----- 23 files changed, 124 insertions(+), 106 deletions(-) create mode 100644 src/content/docs/platform/transitioning-from-oz.mdx diff --git a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index d64295181..51250f461 100644 --- a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -18,6 +18,8 @@ Example repository: [**Sentry monitor example repository**](https://github.com/w In this demo, Ben builds a small TypeScript “Sentry monitor” service that listens for specific Sentry alerts (like a Go nil pointer dereference) and triggers a Warp cloud agent to investigate. The server validates the webhook, extracts the stack trace, and injects it into an agent run inside a Warp Environment so the agent can inspect the repo and propose a fix. +To route the alert through a factory's named agents and workflow instead, use the [factory API](/factories/factory-api/) to dispatch the request. This example remains useful for custom standalone cloud-agent intake. + He also covers the task lifecycle basics in the TypeScript SDK (running an agent, polling task state to fetch a session link for debugging), and shows the end result: a draft GitHub pull request created from the Sentry event for a maintainer to review. **What Ben covers** diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx index 3f2555796..943f9c759 100644 --- a/src/content/docs/factories/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -4,16 +4,18 @@ title: "{{API_SDK_NAME}} reference" sidebar: label: "{{API_SDK_NAME}}" description: >- - Create and inspect cloud agent runs over HTTP, or use the Python and - TypeScript SDKs for typed requests, retries, and error handling. + Create and operate factory and cloud agent runs over HTTP, or use the Python + and TypeScript SDKs for typed requests, retries, and error handling. --- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -The {VARS.API_SDK_NAME} lets you create, monitor, and inspect cloud agent runs programmatically. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling. The SDKs are ideal for CI pipelines, internal tools, and custom integrations. +The {VARS.API_SDK_NAME} lets you integrate with Warp Factories and operate the cloud agent runs behind them. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling. + +Use the [factory API](/factories/factory-api/) to discover a factory and send it work. Use this API and SDK reference to monitor factory runs, submit follow-ups, inspect results, or start standalone cloud-agent runs from CI, internal tools, and custom integrations. :::note -Some examples in this reference and the [CLI reference](/agents/cli/oz-cli/) use `oz` commands (for example, `oz environment list`) from the {VARS.WARP_AGENT_CLI}. Those commands remain supported through the end of September 2026. The [Warp Agent CLI reference](/agents/cli/reference/) does not yet document a `warp` equivalent. +Some examples in this reference and the [CLI reference](/agents/cli/oz-cli/) use `oz` commands (for example, `oz environment list`) from the {VARS.WARP_AGENT_CLI}. Those commands remain available during the transition. The [Warp Agent CLI reference](/agents/cli/reference/) does not yet document a `warp` equivalent. ::: ### API overview diff --git a/src/content/docs/factories/api-and-sdk/quickstart.mdx b/src/content/docs/factories/api-and-sdk/quickstart.mdx index 6eeac8068..725c5f9bd 100644 --- a/src/content/docs/factories/api-and-sdk/quickstart.mdx +++ b/src/content/docs/factories/api-and-sdk/quickstart.mdx @@ -12,6 +12,8 @@ import { VARS } from '@data/vars'; The {VARS.API_SDK_NAME} lets you run and manage cloud agents from anywhere — CI/CD pipelines, backend services, scripts, or custom tooling — without the Warp desktop app. This quickstart walks you through creating your first run and checking its status. +To dispatch work through a factory's named agents and workflow, use the [factory API](/factories/factory-api/) after this quickstart. The run-management steps below also apply to the factory run that API creates. + Watch this short demo of how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team: <VideoEmbed url="https://youtu.be/N6qMe641K34" title={`${VARS.API_SDK_NAME} quickstart video`} /> diff --git a/src/content/docs/factories/deployment-patterns.mdx b/src/content/docs/factories/deployment-patterns.mdx index e8adae12e..e6d23f9ef 100644 --- a/src/content/docs/factories/deployment-patterns.mdx +++ b/src/content/docs/factories/deployment-patterns.mdx @@ -1,70 +1,38 @@ --- -title: Deployment patterns +title: Deployment patterns for Warp Factories description: >- - Common architectures for deploying cloud agents, including CLI-only, - {{WARP_AUTOMATION_PLATFORM}}-hosted, and self-hosted execution patterns. + Choose Warp-hosted or managed self-hosted execution for Warp Factories based + on your network, compliance, and operational requirements. sidebar: label: "Deployment patterns" --- 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. +Choose an execution model for your factory based on where its code must run and who operates the compute. Warp-hosted execution is the default. Managed self-hosting keeps checkout and command execution in your network while Warp coordinates the work. ![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 +## Choose an execution model -Cloud agent setups usually have four moving parts: +| If your factory needs to... | Choose | +| --- | --- | +| Run public repositories and services without operating workers | [Warp-hosted execution](#warp-hosted-execution) | +| Reach private repositories or services behind your network boundary | [Managed self-hosting](#managed-self-hosting) | +| Run standalone agents from CI or developer infrastructure, without a factory | [Unmanaged execution](/platform/unmanaged-execution/) | -1. **Trigger**: something happens (CI step, webhook, cron, Slack mention). -2. **Orchestration**: something decides what to run and tracks it ({VARS.WARP_AUTOMATION_PLATFORM} orchestrator, GitHub Actions, your internal system). -3. **Execution**: where the agent actually runs (your runner, {VARS.WARP_AUTOMATION_PLATFORM}-hosted environment, or self-hosted workers). -4. **Visibility**: how the team monitors and intervenes ({VARS.DASHBOARD}, session sharing, APIs). +Both factory options use the same [factory definition](/factories/factory-as-code/), [runners](/factories/runners/), and [factory dashboard](/factories/factory-dashboard/). The execution host changes the location of checkout, command execution, and the sandbox filesystem. --- -## Pattern 1: CLI-only agents (bring your own orchestrator) +## Standalone CLI-only agents -Use this when you already have a system that schedules work (CI, dev boxes, internal orchestrators), and you need a reliable, cloud-connected agent runner. - -### What it looks like - -* **Trigger**: GitHub Actions / CI, a script, a dev box action, or an internal orchestrator -* **Orchestration**: your existing system -* **Execution**: wherever that system runs -* **Warp adds**: cloud connectivity, shared context, visibility, session sharing, and tracking - -### Why teams choose it - -* You want a **drop-in replacement** for other CLI/SDK-based agents (Claude Code, Codex CLI, Gemini CLI/SDK-style flows). -* You want to run agents anywhere without requiring Warp desktop. -* You still want **team-level observability** even when execution is “outside Warp.” - -### Common examples - -* **CI PR helper**: run formatting checks, generate review comments, suggest fixes, open PRs. -* **Remote dev box agent**: run refactors or debugging tasks inside a pre-provisioned box. -* **Internal orchestrator integration**: treat Warp as one agent option alongside other model providers. - -### What you still get even without Warp orchestration - -* Access to your shared Warp context (for example MCP config, Warp Drive context, rules/prompts). -* [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor/steer runs. -* Read-only APIs for tracking and reporting. -* A path to [Handoff](/platform/handoff/) workflows (where a run can be continued or inspected in richer surfaces). - -### Minimal setup checklist - -* A Warp team -* A [cloud agent](/platform/agents/) (recommended for automation) -* The {VARS.WARP_AGENT_CLI} installed on the runner / box -* Any needed credentials (often via secrets + environment variables) +This is not a factory deployment model. Use it when you already have a system that schedules work and need to run standalone agents from CI, developer infrastructure, or an internal orchestrator. See [Unmanaged execution](/platform/unmanaged-execution/) for the Platform reference. --- -## Pattern 2: Warp-hosted agents and orchestration (managed cloud execution) +## Warp-hosted execution -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. +Use this when your factory can reach its repositories and services over the public internet. The {VARS.WARP_AUTOMATION_PLATFORM} runs the work on Warp-managed infrastructure while your factory definition selects the agents, runner, workspace, and credentials. ![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) @@ -115,11 +83,11 @@ When a task is naturally divisible, use [multi-agent orchestration](/platform/or --- -## Pattern 3: Self-hosted execution +## Managed self-hosting -Use this when you need to control where agent execution happens while still using {VARS.WARP_AUTOMATION_PLATFORM} orchestration and visibility. Repositories are cloned and stored only on your infrastructure. Orchestration metadata and session transcripts route through Warp's backend; cloud conversations require Warp to store conversation data according to Warp's retention terms. LLM inference requests and responses route through Warp to contracted model providers under [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), except for provider-specific models that are not covered by ZDR and follow the provider's retention requirements. +Use this when a factory must run checkout and execution on your infrastructure while the {VARS.WARP_AUTOMATION_PLATFORM} coordinates the work and records its results. Repositories are cloned and stored only on your infrastructure. Orchestration metadata and session transcripts route through Warp's backend; cloud conversations require Warp to store conversation data according to Warp's retention terms. LLM inference requests and responses route through Warp to contracted model providers under [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), except for provider-specific models that are not covered by ZDR and follow the provider's retention requirements. -Think of self-hosted execution as **customer-hosted execution with Warp-hosted orchestration**, not as a fully offline agent stack. Code repositories, build artifacts, runtime secrets, and execution workspaces stay on your infrastructure. Code context can still appear in session transcripts and LLM prompts as the agent works. +Think of managed self-hosting as **customer-hosted execution with Warp-hosted orchestration**, not as a fully offline agent stack. Code repositories, build artifacts, runtime secrets, and execution workspaces stay on your infrastructure. Code context can still appear in session transcripts and LLM prompts as the agent works. :::note **Enterprise feature**: Self-hosted execution is available exclusively to teams on an Enterprise plan. @@ -128,7 +96,7 @@ Think of self-hosted execution as **customer-hosted execution with Warp-hosted o Self-hosting has two architectures that differ on **who orchestrates agent runs** (both keep code and execution on your infrastructure): * **[Managed](/factories/self-hosting/#managed-architecture)** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates. You run the `oz-agent-worker` daemon; the {VARS.WARP_AUTOMATION_PLATFORM} routes runs to it from Slack, Linear, schedules, the API, or `oz agent run-cloud`. Tasks execute in Docker containers, Kubernetes Jobs, or directly on the host. -* **[Unmanaged](/platform/unmanaged-execution/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment. Warp provides session tracking and observability; it does not start or stop agents. +* **[Unmanaged](/platform/unmanaged-execution/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment. This is a standalone-agent model, not a factory host. Why teams choose self-hosted execution: @@ -136,4 +104,11 @@ Why teams choose self-hosted execution: * Agents need to access services behind a VPN or self-hosted SCMs like GitLab or Bitbucket. Warp-hosted agents can also access GitLab and Bitbucket over the public internet — see the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides. * Your environments (multi-service stacks, heavy resource requirements) don't fit in a single Docker container. -For setup, decision guides, and a quickstart, start with [Self-hosting](/factories/self-hosting/). +For factory worker setup and a quickstart, start with [Managed self-hosting](/factories/self-hosting/). For security and network boundaries that apply to both managed and unmanaged execution, see [Execution security](/platform/execution-security/). + +## Related pages + +* [Infrastructure and security](/factories/infrastructure-and-security/) - Choose execution, inference, storage, and credential boundaries for a factory. +* [Warp-hosted execution](/factories/warp-hosting/) - Review hosted execution capacity, networking, and supported environments. +* [Managed self-hosting](/factories/self-hosting/) - Install and operate a factory worker on your infrastructure. +* [Unmanaged execution](/platform/unmanaged-execution/) - Run standalone agents outside a factory. diff --git a/src/content/docs/factories/factory-dashboard.mdx b/src/content/docs/factories/factory-dashboard.mdx index 4c1310399..9d6ea3d48 100644 --- a/src/content/docs/factories/factory-dashboard.mdx +++ b/src/content/docs/factories/factory-dashboard.mdx @@ -81,13 +81,13 @@ When an agent proposes a change to a Warp-managed definition, a spec review for * **Repositories** - The repos the factory works in. * **Pull request authorship** - Whether pull requests are authored by the agent or the run creator (the definition's [`credentialStrategy`](/factories/factory-as-code/#credentialstrategy)). * **Analysis model** - The model [Self-improvement](/factories/measure-and-improve/self-improvement/) uses to analyze failed runs. -* **Runners** - The compute the factory's runs execute on. +* **Runners** - The compute the factory's runs execute on. See [factory runners](/factories/runners/) to choose runner configuration or [managed self-hosting](/factories/self-hosting/) to run factory work on your infrastructure. * **Integrations** - The integrations this factory can access. * **Deletion** - Deletes the factory. This cannot be undone. For a file-managed factory, `runners/*.yaml` in the repository is the source of truth. Anything managed in an external repository is read-only in Settings. -## Next steps +## Related pages * [Factory inbox](/factories/factory-inbox/) - See and resolve the questions, spec approvals, and PR reviews waiting on you. * [How Warp Factories work](/factories/how-factories-work/) - The stages work moves through and where humans stay in the loop. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 88cd98f45..c72dd74cc 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -93,7 +93,7 @@ flowchart LR Slack["Slack or Linear"] -->|"@handle"| Foreman ``` -## Next steps +## Related pages * [**Set up a factory**](/factories/quickstart/) - Create a factory and send its first work item. * [**Understand the execution model**](/factories/how-factories-work/) - See how the foreman coordinates stages, runs, and human decisions. diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index d373db11e..bd058ab91 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -129,3 +129,4 @@ Warp meters hosted compute, Warp-provided inference, and platform services. Mana * [**Execution security**](/platform/execution-security/) - Review data boundaries, network egress, and backend-specific controls. * [**Bring Your Own LLM**](/enterprise/enterprise-features/bring-your-own-llm/) - Compare customer-owned inference options and provider support. * [**Enterprise security overview**](/enterprise/security-and-compliance/security-overview/) - Review data handling, ZDR, compliance, and access controls across Warp. +* [Team-managed model keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) - Configure customer-supplied inference credentials. diff --git a/src/content/docs/factories/runners.mdx b/src/content/docs/factories/runners.mdx index c51a1c92f..987835724 100644 --- a/src/content/docs/factories/runners.mdx +++ b/src/content/docs/factories/runners.mdx @@ -1,17 +1,17 @@ --- -title: Cloud agent runners +title: Runners for Warp Factories sidebar: label: "Runners" description: >- - Runners define the OS, architecture, instance size, and sandbox image cloud - agents run on, managed with the {{WARP_AGENT_CLI}}. + Runners define the OS, architecture, instance size, and sandbox image for + Warp Factories work. --- import { VARS } from '@data/vars'; import { Tabs, TabItem } from '@astrojs/starlight/components'; -Runners define the compute a [cloud agent](/platform/) runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. +Runners define the compute a factory agent runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. Select runners in the [factory definition](/factories/factory-as-code/) or the [factory dashboard](/factories/factory-dashboard/). -A runner is a reusable compute configuration. Where an [environment](/platform/environments/) defines _what_ an agent works on (the repos, setup commands, and toolchain), a runner defines _where and on what hardware_ that work executes. Separating the two lets you reuse the same environment across different machine shapes—for example, a small Linux box for routine tasks and a larger instance for heavier builds. +A runner is a reusable compute configuration. Where an [environment](/platform/environments/) defines _what_ an agent works on (the repos, setup commands, and toolchain), a runner defines _where and on what hardware_ that work executes. Separating the two lets a factory use a small Linux runner for triage and a larger runner for builds. :::note Most runs don't need a custom runner. Every environment has a default runner, and Warp picks a sensible default shape when you don't specify one. Create a runner when you need a specific OS, architecture, instance size, or sandbox image. @@ -62,9 +62,9 @@ Each environment has a default runner. Specifying a runner for a run overrides t </TabItem> </Tabs> -## Managing runners with the CLI +## Managing runners with the legacy CLI -Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) to create, list, update, and delete runners. Runner commands require an authenticated CLI—see the [CLI quickstart](/agents/cli/oz-cli/quickstart/) to get set up. +For a file-managed factory, edit `runners/*.yaml` in the factory definition. For a Warp-managed factory, edit runner files in the factory dashboard. The legacy [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) also supports creating, listing, updating, and deleting reusable runners. ### Create a runner diff --git a/src/content/docs/factories/self-hosting/quickstart.mdx b/src/content/docs/factories/self-hosting/quickstart.mdx index f30a91205..4841addaf 100644 --- a/src/content/docs/factories/self-hosting/quickstart.mdx +++ b/src/content/docs/factories/self-hosting/quickstart.mdx @@ -8,7 +8,7 @@ sidebar: --- import { VARS } from '@data/vars'; -Run your first cloud agent on your own infrastructure in ~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting. +Run your first managed worker on your own infrastructure in ~10 minutes using the Docker backend. After you verify the worker, configure a factory to route its work to that worker. :::note This quickstart sets up the [managed architecture](/factories/self-hosting/#managed-architecture), where the {VARS.WARP_AUTOMATION_PLATFORM} orchestrates the agent and your worker provides the compute. **Prefer a CLI-only path with no Docker requirement?** Jump to the [Unmanaged quickstart](/platform/unmanaged-execution/#unmanaged-quickstart) to run `oz agent run` directly on any host. @@ -63,6 +63,8 @@ oz agent run-cloud --prompt "List the files in the current directory" --host "my **Expected outcome:** The {VARS.WARP_AUTOMATION_PLATFORM} accepts the task, routes it to your worker, and the worker spawns a Docker container to execute the agent. You'll see the run appear in the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a> with status moving from `QUEUED` → `INPROGRESS` → `SUCCEEDED`. +This test verifies that the worker is connected. To route factory work to it, set `workerHost` and a platform-matched runner in the [factory definition](/factories/factory-as-code/#routing-to-a-self-hosted-worker). + ### 4. Verify the run Open the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>, find the new task, and confirm the session transcript shows the agent running against your worker. You can attach to the session at any time via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer it. diff --git a/src/content/docs/factories/warp-hosting.mdx b/src/content/docs/factories/warp-hosting.mdx index 11bc60b6c..29d3b3dfe 100644 --- a/src/content/docs/factories/warp-hosting.mdx +++ b/src/content/docs/factories/warp-hosting.mdx @@ -1,15 +1,16 @@ --- -title: Warp-hosted agents +title: Warp-hosted execution for Warp Factories description: >- - Run cloud agents on Warp's infrastructure. Warp handles scaling, isolation, and performance for agent execution. + Run factory work on Warp-hosted infrastructure, with managed compute, + isolation, networking, and capacity. sidebar: - label: "Warp-hosted agents" + label: "Warp-hosted execution" --- import { VARS } from '@data/vars'; -Warp's managed infrastructure lets your team run cloud agent workloads in fast, secure sandboxes. +Warp-hosted execution runs factory work in managed sandboxes. Warp provisions the compute while your factory definition selects each agent's runner, repositories, setup, and credentials. -Use Warp-hosted agents to quickly get started with the {VARS.WARP_AUTOMATION_PLATFORM}, without needing to configure compute resources or maintain services. +Use it when your factory's repositories and services are reachable from the public internet and your team does not need to manage worker capacity or host maintenance. For private services or a network boundary that must contain checkout and execution, use [managed self-hosting](/factories/self-hosting/). ## Sandbox environment @@ -17,7 +18,7 @@ All Warp-hosted agents run in fully-isolated sandboxes. Warp uses a mix of infra ### OS and architecture -Warp-hosted agents use the container image specified in your [environment](/platform/environments/). +Warp-hosted factory agents use the runner and workspace configuration in your [factory definition](/factories/factory-as-code/). A factory can also use an existing [environment](/platform/environments/) when its definition specifies one. They are compatible with any Linux x86-64 image that includes a `bash` shell and core utilities like `ls` and `mkdir`. ### Resources @@ -51,5 +52,6 @@ Warp's hosted agents have network egress enabled by default. Outgoing requests m ## Related pages -* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) - Learn how Warp-hosted agents fit into the {VARS.WARP_AUTOMATION_PLATFORM}. -* [Self-hosting](/factories/self-hosting/) - Run agents on infrastructure you manage when execution must stay inside your network. +* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) - Configure the shared cloud-agent primitives behind a factory. +* [Factory runners](/factories/runners/) - Choose the operating system, architecture, and instance shape for factory work. +* [Managed self-hosting](/factories/self-hosting/) - Run factory work on infrastructure you manage when execution must stay inside your network. diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 30b6904d2..cad74d8fe 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -40,7 +40,7 @@ Warp Factories is available in Early Access. A factory turns incoming engineerin Use Warp and the Warp Agent for interactive development. Use the {VARS.WARP_AUTOMATION_PLATFORM} for background agents and shared cloud configuration. Use Warp Factories when your team needs a standing workflow to route, review, and improve work across repositories. -## Next steps +## Related pages * [Install Warp](/quickstart/) - Set up Warp and start coding. * [Start an agent conversation](/agents/) - Work with the Warp Agent in a local checkout. diff --git a/src/content/docs/platform/environments.mdx b/src/content/docs/platform/environments.mdx index 81f12d6d7..9a19483fc 100644 --- a/src/content/docs/platform/environments.mdx +++ b/src/content/docs/platform/environments.mdx @@ -9,6 +9,8 @@ import { VARS } from '@data/vars'; Environments describe _how_ an agent executes a task, not _what_ it does. They give cloud agents the same container, repositories, and setup every time they run. Use an environment for a cloud agent run that needs a repeatable toolchain. Interactive local runs use your current checkout and machine setup, so they don't need one. +Factories manage their own repositories and workspace by default. Set `agentDefaults.environmentId` in a [factory definition](/factories/factory-as-code/#agentdefaultsenvironmentid) when a factory agent must use an existing environment. + ## What an environment includes An environment groups the runtime configuration for a cloud agent run: diff --git a/src/content/docs/platform/harnesses/index.mdx b/src/content/docs/platform/harnesses/index.mdx index 8578dc4f8..60b7d6d56 100644 --- a/src/content/docs/platform/harnesses/index.mdx +++ b/src/content/docs/platform/harnesses/index.mdx @@ -12,6 +12,8 @@ import { VARS } from '@data/vars'; The {VARS.WARP_AUTOMATION_PLATFORM} can run third-party agent harnesses as cloud agents alongside Warp Agent, including [Claude Code](/platform/harnesses/claude-code/) and [Codex](/platform/harnesses/codex/). You choose the harness (agent runtime) that fits the task; the platform around the run stays the same. +For a factory, set the default or per-agent harness in its [factory definition](/factories/factory-as-code/#agentdefaultsharness) or configure it for a [factory agent](/factories/factory-agents/). + Watch this walkthrough to see how to run Warp Agent, Claude Code, or Codex as a cloud agent. <VideoEmbed url="https://www.youtube.com/watch?v=ZUYyuA5i1VU" title={`Run any agent in the cloud with the ${VARS.WARP_AUTOMATION_PLATFORM} - Claude Code, Codex, or Warp Agent`} /> diff --git a/src/content/docs/platform/index.mdx b/src/content/docs/platform/index.mdx index 9bb57f234..a50628c65 100644 --- a/src/content/docs/platform/index.mdx +++ b/src/content/docs/platform/index.mdx @@ -9,16 +9,16 @@ sidebar: import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; -{/* Transition notice for the 2026-08-18 rename. Remove after 2026-10-06, when - the CLI and web app take their new names and the old one stops appearing. */} :::note -**Oz is now the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/).** Only the name changed. Your existing cloud agents, integrations, API keys, and schedules keep working exactly as before. The `oz` CLI and the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> keep the Oz name until October 6, 2026. +**The [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) is the current name.** Existing cloud agents, integrations, API keys, and schedules continue to work. The `oz` CLI and the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> retain their legacy names during the transition. See [Transitioning](/platform/transitioning-from-oz/) for the current guidance. ::: Cloud agents are autonomous, background agents that run on Warp's cloud infrastructure or your own, triggered by system events, schedules, or integrations like Slack and GitHub. They execute tasks with full observability — every run is tracked, inspectable, and shareable across your team. **New to cloud agents?** Start with the [Cloud agents quickstart](/platform/quickstart/) to run your first cloud agent in ~10 minutes. +For a standing, multi-stage workflow with named agents, automations, and measurement, use [Warp Factories](/factories/). The factory-specific setup and operations guidance complements this shared cloud-agent reference. + ### Monitor, inspect, and share cloud agent runs To understand what a cloud agent did, start from the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app or the [Runs page in the {VARS.WEB_APP}](/platform/oz-web-app/#runs). From there, you can find a run by source, status, trigger, or owner; open the run transcript; inspect the prompt, plan, commands, logs, and output; and share the session link with teammates for review. diff --git a/src/content/docs/platform/integrations/index.mdx b/src/content/docs/platform/integrations/index.mdx index bf2245a4c..3bf7901c4 100644 --- a/src/content/docs/platform/integrations/index.mdx +++ b/src/content/docs/platform/integrations/index.mdx @@ -14,6 +14,8 @@ Warp integrations let your team trigger agents directly from the terminal, or fr * Run code inside your codebase in a remote environment * Open pull requests and perform other multi-step agent workflows on your behalf +For intake that routes work through a factory's named agents and automations, use the [Factory integrations](/factories/connect-your-factory/) documentation. + Integrations are one way to start a cloud agent. For the full set, including schedules, the {VARS.WARP_AGENT_CLI}, and the API, see [Triggers](/platform/triggers/). If you're deciding which one to use, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). :::note diff --git a/src/content/docs/platform/managing-cloud-agents.mdx b/src/content/docs/platform/managing-cloud-agents.mdx index 5bb605a3e..f4c606492 100644 --- a/src/content/docs/platform/managing-cloud-agents.mdx +++ b/src/content/docs/platform/managing-cloud-agents.mdx @@ -13,6 +13,8 @@ Warp provides two management surfaces for tracking and observing agent activity Use these surfaces as the starting point for real-time agent observability in Warp. They help you see which agents are active, which runs are blocked or failed, where each run started, and which session link opens the prompt, plan, commands, logs, outputs, and follow-up messages behind the work. +To inspect work from one factory, use that factory's [Runs page](/factories/factory-dashboard/#inspect-runs). This page remains the reference for interactive and standalone cloud-agent management. + The Agent Management Panel and {VARS.WEB_APP} Runs page are designed to answer, at a glance: * Which agents are active or have been running recently. diff --git a/src/content/docs/platform/mcp.mdx b/src/content/docs/platform/mcp.mdx index ad13551b4..6dbb95772 100644 --- a/src/content/docs/platform/mcp.mdx +++ b/src/content/docs/platform/mcp.mdx @@ -27,6 +27,8 @@ You can supply MCP configuration in two ways: * **At run time** — pass `--mcp` when calling `oz agent run` or `oz agent run-cloud`. See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) in the CLI reference for the full syntax. * **In an agent config file** — define `mcp_servers` directly in a YAML or JSON agent config file (passed with `-f / --file`). This is the recommended approach for repeatable workflows. +For factory work, declare factory-wide or per-agent MCP servers in the [factory definition](/factories/factory-as-code/#mcpservers). Use [Factory MCP](/factories/factory-mcp/) to connect an external coding agent to a factory. + ## Configuration schema Each MCP server entry is keyed by a name you choose. A server config must have **exactly one** transport type: diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index 5d87dc41b..06257e7d2 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -13,12 +13,9 @@ import { VARS } from '@data/vars'; If you're new to cloud agents, the [Cloud agents quickstart](/platform/quickstart/) gets you to your first run in about ten minutes. -{/* Transition notice for the 2026-08-18 rename. Remove after 2026-10-06, when - the CLI and web app take their new names and the old one stops appearing. */} :::note -**Oz is now the {VARS.WARP_AUTOMATION_PLATFORM}.** Only the name changed. Your existing integrations, API keys, scheduled agents, and scripts keep working exactly as before — nothing to migrate. - -The `oz` CLI and the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> keep the Oz name until October 6, 2026, which is why you'll still see it in commands and URLs. +**The {VARS.WARP_AUTOMATION_PLATFORM} is the current name.** Your existing integrations, API keys, scheduled agents, and scripts keep working exactly as before — nothing to migrate. +The `oz` CLI and the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> retain their legacy names during the transition. See [Transitioning](/platform/transitioning-from-oz/) for the current guidance. ::: <VideoEmbed url="https://youtu.be/poLkJhO7fdo" title={`${VARS.WARP_AUTOMATION_PLATFORM} cloud agents overview video`} /> diff --git a/src/content/docs/platform/secrets.mdx b/src/content/docs/platform/secrets.mdx index 2290c7fae..528e53d30 100644 --- a/src/content/docs/platform/secrets.mdx +++ b/src/content/docs/platform/secrets.mdx @@ -12,6 +12,8 @@ Cloud agents often need to interact with external systems such as APIs, database Warp-managed secrets are designed to work across [cloud agent](/platform/) and [integration](/platform/integrations/) triggers (CLI, Slack, Linear, and schedules), support both team-wide and personal credentials, and give engineering and security teams visibility into what agents can access. +For factory work, declare the managed secrets a factory or individual factory agent receives in its [factory definition](/factories/factory-as-code/#secrets). This page remains the reference for creating, scoping, and rotating the shared secrets. + **Warp-managed secrets are useful when:** * A cloud agent needs to call an API or CLI that does not support OAuth diff --git a/src/content/docs/platform/skills-as-agents.mdx b/src/content/docs/platform/skills-as-agents.mdx index 56f3c284b..ff784aba6 100644 --- a/src/content/docs/platform/skills-as-agents.mdx +++ b/src/content/docs/platform/skills-as-agents.mdx @@ -12,6 +12,8 @@ You can start an agent from a [skill](/agents/capabilities/skills/)—a reusable Skills work with both **local agents** (running on your machine) and **cloud agents** (running in Warp's infrastructure). +For reusable instructions scoped to a factory or one of its agents, use [factory skills](/factories/factory-skills/). This page describes skills that run independently of a factory. + This is useful when you want: * **Consistent behavior** — The same skill produces the same workflow every time, regardless of who triggers it or where it runs. diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx new file mode 100644 index 000000000..6c31600dd --- /dev/null +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -0,0 +1,37 @@ +--- +title: Transitioning to the {{WARP_AUTOMATION_PLATFORM}} and Warp Factories +description: >- + Warp's documentation is moving to a factory-first structure while existing + workflows, configuration, and tools remain available. +sidebar: + label: "Transitioning" +--- +import { VARS } from '@data/vars'; + +Warp's documentation is moving to a factory-first structure. Existing workflows, cloud agents, integrations, schedules, API keys, and the `oz` CLI remain available, so you don't need to migrate immediately. + +The {VARS.WARP_AUTOMATION_PLATFORM} remains the shared foundation for cloud agents. Warp Factories builds on those primitives for teams that need standing workflows with named agents, work intake, review stages, and measurement. + +## Choose the right entry point + +* **Use the {VARS.WARP_AUTOMATION_PLATFORM}** - Configure standalone cloud agents, environments, schedules, integrations, and orchestration. Start with the [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) or [Cloud agents overview](/platform/). +* **Warp Factories** - Use a repeatable workflow that routes work through named agents and tracks it in one place. Start with the [Warp Factories overview](/factories/) or the [factory quickstart](/factories/quickstart/). + +## What stays available + +Current workflows and configuration continue to work during this documentation transition. Links from legacy API, SDK, and CLI reference paths point to their current documentation locations: + +* **API and SDK documentation** - Available under [Developer tools for Warp Factories](/factories/developer-tools/). +* **Legacy {VARS.WARP_AGENT_CLI} documentation** - Available in the [legacy CLI reference](/agents/cli/oz-cli/). +* **Managed self-hosting documentation** - Available in [Managed self-hosting for Warp Factories](/factories/self-hosting/). +* **Standalone cloud-agent execution** - Available in [Unmanaged execution](/platform/unmanaged-execution/). + +## What comes next + +This page will add verified migration actions, compatibility dates, and replacement destinations as the product transition is finalized. Until then, follow the documentation for the workflow you use today. + +## Related pages + +* [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) - Configure the reusable primitives behind cloud-agent workflows. +* [Warp Factories overview](/factories/) - Build and operate a standing software factory. +* [Factory dashboard](/factories/factory-dashboard/) - Inspect work items, runs, and factory settings. diff --git a/src/content/docs/platform/triggers/index.mdx b/src/content/docs/platform/triggers/index.mdx index f204f1303..490144081 100644 --- a/src/content/docs/platform/triggers/index.mdx +++ b/src/content/docs/platform/triggers/index.mdx @@ -8,6 +8,8 @@ import { VARS } from '@data/vars'; A trigger is anything that starts a cloud agent run without you typing a prompt: a recurring schedule, an integration like Slack or Linear, a CI event, or a call to the API. This page covers the full set, including the [integrations](/platform/integrations/) that connect agents to the tools your team already uses. +For triggers that route work through one factory's named agents and workflow, use [factory automations](/factories/automations/) and [factory integrations](/factories/connect-your-factory/). + To set up your first recurring agent, follow the [Scheduled Agents Quickstart](/platform/triggers/scheduled-agents-quickstart/). If you're choosing between schedules, Slack, Linear, GitHub, GitHub Actions, the {VARS.WARP_AGENT_CLI}, or the API, start with [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). diff --git a/src/sidebar.ts b/src/sidebar.ts index 27010440b..cd9534ffb 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -438,9 +438,9 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // Integrations subgroup, which would have rendered as // Integrations > Integrations > Slack. // - // 'Connect your factory' leads because it is the overview for this - // group; Factory MCP trails because it is a connection mechanism - // rather than a third-party service. + // 'Connect your factory' leads because it is the overview for this + // group. The direct developer interfaces live in the Developer tools + // group rather than alongside third-party service integrations. label: 'Integrations', items: [ { slug: 'factories/connect-your-factory', label: 'Connect your factory' }, @@ -449,25 +449,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/integrations/gitlab', label: 'GitLab' }, { slug: 'factories/integrations/linear', label: 'Linear' }, { slug: 'factories/integrations/jira', label: 'Jira' }, - // Custom webhooks connect any JSON-posting system, so they sit - // between the named third-party services and the API-style - // mechanisms below. Label matches the factory dashboard's nav. - // The overview holds the concept and the happy path; each - // provider whose setup differs from it gets its own page nested - // here (HYC, 9/15), same shape as 'Measure and improve' below. - { - label: 'Webhooks', - collapsed: false, - items: [ - { slug: 'factories/webhooks', label: 'Overview' }, - { slug: 'factories/webhooks/vercel', label: 'Vercel' }, - ], - }, - // Alongside Factory MCP: both are direct API-style connection - // mechanisms rather than third-party services, so they trail the - // per-service integrations above. - { slug: 'factories/factory-api', label: 'Factory API' }, - { slug: 'factories/factory-mcp', label: 'Factory MCP' }, ], }, { @@ -555,6 +536,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ items: [ { slug: 'platform', label: 'Overview' }, { slug: 'platform/quickstart', label: 'Quickstart' }, + { slug: 'platform/transitioning-from-oz', label: 'Transitioning' }, { // Runtime (which agent executes the run) is kept separate from // configuration (how any run is set up) -- HYC review, 8/14. From 834b380ed65079d0cc1e404da40d0fa5855fff39 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 15:52:45 -0600 Subject: [PATCH 07/46] docs: refine factories transition copy Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/factories/index.mdx | 3 +++ src/content/docs/index.mdx | 2 +- .../docs/platform/transitioning-from-oz.mdx | 23 +++++++++---------- src/sidebar.ts | 9 +++----- 4 files changed, 18 insertions(+), 19 deletions(-) diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index c72dd74cc..f3f6e5f8d 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -15,6 +15,9 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ A software factory takes in requests (bug reports, feature specs, support escalations), and a coordinated fleet of agents works them into a stream of mergeable pull requests instead of a growing backlog. Warp Factories gives you the building blocks, so your team stays in the loop where it matters, approving specs when needed and merging every pull request. +:::note +The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing workflows remain available today. See [Transitioning from the {VARS.WEB_APP}](/platform/transitioning-from-oz/) for the current transition guidance. +::: <VideoEmbed url="https://www.youtube.com/watch?v=0WBk4ai8y1A" title="Introducing Warp Factories" /> ## What is a software factory? diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index cad74d8fe..b1d0e4c4b 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -8,7 +8,7 @@ sidebar: --- import { VARS } from '@data/vars'; -Warp is an [open source](https://github.com/warpdotdev/warp) development environment for working in the terminal and with coding agents. Use Warp for interactive coding, run the Warp Agent from any terminal, automate recurring work in the cloud, or connect a team workflow to Warp Factories. +Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Development Environment** for working in the terminal and with coding agents. Use Warp for interactive coding, run the Warp Agent from any terminal, automate recurring work in the cloud, or connect a team workflow to Warp Factories. ## Warp diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx index 6c31600dd..a981cdb32 100644 --- a/src/content/docs/platform/transitioning-from-oz.mdx +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -1,16 +1,16 @@ --- -title: Transitioning to the {{WARP_AUTOMATION_PLATFORM}} and Warp Factories +title: Transitioning from the {{WEB_APP}} description: >- - Warp's documentation is moving to a factory-first structure while existing - workflows, configuration, and tools remain available. + The {{WEB_APP}} will retire after Warp Factories reaches general availability. + Existing workflows, configuration, and tools remain available today. sidebar: - label: "Transitioning" + label: "Transitioning from the {{WEB_APP}}" --- import { VARS } from '@data/vars'; -Warp's documentation is moving to a factory-first structure. Existing workflows, cloud agents, integrations, schedules, API keys, and the `oz` CLI remain available, so you don't need to migrate immediately. +The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing cloud agents, integrations, schedules, API keys, and the `oz` CLI remain available today, so you don't need to migrate immediately. -The {VARS.WARP_AUTOMATION_PLATFORM} remains the shared foundation for cloud agents. Warp Factories builds on those primitives for teams that need standing workflows with named agents, work intake, review stages, and measurement. +The {VARS.WARP_AUTOMATION_PLATFORM} remains the shared foundation for cloud agents. Warp Factories builds on that foundation for teams that need standing workflows with named agents, work intake, review stages, and measurement. ## Choose the right entry point @@ -19,16 +19,15 @@ The {VARS.WARP_AUTOMATION_PLATFORM} remains the shared foundation for cloud agen ## What stays available -Current workflows and configuration continue to work during this documentation transition. Links from legacy API, SDK, and CLI reference paths point to their current documentation locations: +Existing workflows and configuration continue to work today: -* **API and SDK documentation** - Available under [Developer tools for Warp Factories](/factories/developer-tools/). -* **Legacy {VARS.WARP_AGENT_CLI} documentation** - Available in the [legacy CLI reference](/agents/cli/oz-cli/). -* **Managed self-hosting documentation** - Available in [Managed self-hosting for Warp Factories](/factories/self-hosting/). -* **Standalone cloud-agent execution** - Available in [Unmanaged execution](/platform/unmanaged-execution/). +* **Cloud agents** - Continue to run from existing events, schedules, integrations, APIs, and the CLI. +* **Configuration** - Existing environments, integrations, schedules, API keys, and secrets remain available. +* **Current tools** - The {VARS.WARP_AGENT_CLI}, API and SDK, and managed self-hosting continue to support their current workflows. ## What comes next -This page will add verified migration actions, compatibility dates, and replacement destinations as the product transition is finalized. Until then, follow the documentation for the workflow you use today. +This page will add verified migration actions, compatibility dates, and replacement destinations as the product transition is finalized. Until then, continue using the workflow that fits your work today. ## Related pages diff --git a/src/sidebar.ts b/src/sidebar.ts index cd9534ffb..100c1aed5 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -27,12 +27,9 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { label: 'Getting started', items: [ - // Shortened at the 8/18 rename. This label duplicates index.mdx's - // frontmatter title, which IS tokenized, so the two would have - // disagreed once the variable flipped. "Getting started with Warp - // and the Automation Platform" is too long for a sidebar row, and - // Warp is the umbrella product anyway. Keep both in sync. - { label: 'Getting started with Warp', link: '/' }, + // The root product overview remains in the Terminal topic until + // the GA navigation change adds a separate Terminal landing page. + { label: 'Warp products', link: '/' }, { slug: 'quickstart', label: 'Warp quickstart' }, 'getting-started/quickstart/installation-and-setup', 'getting-started/quickstart/coding-in-warp', From 0b5136c6530887331e9593b601f154129f7da8f1 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 16:13:21 -0600 Subject: [PATCH 08/46] docs: combine factories transition notice Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/factories/index.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index f3f6e5f8d..d46eb5dd2 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -11,13 +11,12 @@ import VideoEmbed from '@components/VideoEmbed.astro'; :::note Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. If your team already has access, sign in to the <a href={VARS.FACTORY_WEB_APP_URL}>{VARS.FACTORY_WEB_APP}</a>. + +The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing workflows remain available today. See [Transitioning from the {VARS.WEB_APP}](/platform/transitioning-from-oz/) for the current transition guidance. ::: A software factory takes in requests (bug reports, feature specs, support escalations), and a coordinated fleet of agents works them into a stream of mergeable pull requests instead of a growing backlog. Warp Factories gives you the building blocks, so your team stays in the loop where it matters, approving specs when needed and merging every pull request. -:::note -The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing workflows remain available today. See [Transitioning from the {VARS.WEB_APP}](/platform/transitioning-from-oz/) for the current transition guidance. -::: <VideoEmbed url="https://www.youtube.com/watch?v=0WBk4ai8y1A" title="Introducing Warp Factories" /> ## What is a software factory? From b11f02dec95648136d1833ff27affb96a36ec774 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 16:20:58 -0600 Subject: [PATCH 09/46] docs: clarify factories and product overviews Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/factories/index.mdx | 2 +- src/content/docs/index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index d46eb5dd2..abbdd88ac 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -15,7 +15,7 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing workflows remain available today. See [Transitioning from the {VARS.WEB_APP}](/platform/transitioning-from-oz/) for the current transition guidance. ::: -A software factory takes in requests (bug reports, feature specs, support escalations), and a coordinated fleet of agents works them into a stream of mergeable pull requests instead of a growing backlog. Warp Factories gives you the building blocks, so your team stays in the loop where it matters, approving specs when needed and merging every pull request. +A software factory uses a coordinated fleet of agents to take in requests, manage them from triage through review, and turn a growing backlog into mergeable pull requests. Your team stays in the loop to approve specifications and merge each pull request. <VideoEmbed url="https://www.youtube.com/watch?v=0WBk4ai8y1A" title="Introducing Warp Factories" /> diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index b1d0e4c4b..5eda8814e 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -8,7 +8,7 @@ sidebar: --- import { VARS } from '@data/vars'; -Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Development Environment** for working in the terminal and with coding agents. Use Warp for interactive coding, run the Warp Agent from any terminal, automate recurring work in the cloud, or connect a team workflow to Warp Factories. +Warp is an [open-source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that brings together the terminal, coding agents, cloud orchestration, and Warp Factories. Use Warp to work interactively, run the Warp Agent from any terminal, automate recurring work in the cloud, and build team workflows with Warp Factories. ## Warp From 16d5a8a2c211990273feb6a1c250a5f62bfc87f8 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 16:25:50 -0600 Subject: [PATCH 10/46] docs: address factories restructure review Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/platform/integrations/github-actions.mdx | 2 +- src/content/docs/platform/skills-as-agents.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/platform/integrations/github-actions.mdx b/src/content/docs/platform/integrations/github-actions.mdx index fd17644cd..adcffc9bd 100644 --- a/src/content/docs/platform/integrations/github-actions.mdx +++ b/src/content/docs/platform/integrations/github-actions.mdx @@ -48,7 +48,7 @@ The `oz-agent-action` is a GitHub Action that wraps the {VARS.WARP_AGENT_CLI} an To use agents in GitHub Actions, you need: -* A [**Warp API Key**](/agents/cli/oz-cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to run as a [cloud agent](/platform/agents/) on your team. See [API keys](/agents/cli/oz-cli/api-keys/) for when to pick each. +* A [**Warp API key**](/agents/cli/oz-cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to run as a [cloud agent](/platform/agents/) on your team. See [API keys](/agents/cli/oz-cli/api-keys/) for when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) diff --git a/src/content/docs/platform/skills-as-agents.mdx b/src/content/docs/platform/skills-as-agents.mdx index ff784aba6..56ec7cb5c 100644 --- a/src/content/docs/platform/skills-as-agents.mdx +++ b/src/content/docs/platform/skills-as-agents.mdx @@ -12,7 +12,7 @@ You can start an agent from a [skill](/agents/capabilities/skills/)—a reusable Skills work with both **local agents** (running on your machine) and **cloud agents** (running in Warp's infrastructure). -For reusable instructions scoped to a factory or one of its agents, use [factory skills](/factories/factory-skills/). This page describes skills that run independently of a factory. +Skills that run independently of a factory are covered here. For instructions scoped to a factory or one of its agents, see [factory skills](/factories/factory-skills/). This is useful when you want: From a3b6f721ef51bfc228e5108c29923bbb7629f985 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 18:28:20 -0600 Subject: [PATCH 11/46] ci: avoid oversized agent review output Co-Authored-By: Warp <agent@warp.dev> --- .../test_agent_docs_review_workflow.py | 5 +++++ .github/workflows/agent-docs-review.yml | 15 +++++++-------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py index fec643842..bcf120f8c 100644 --- a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py +++ b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py @@ -33,6 +33,11 @@ def test_all_review_findings_must_supply_actionable_details(self): self.assertIn("actionable_findings", self.workflow) self.assertIn("critical, important, suggestion, or nit", self.workflow) self.assertIn("file and line or quoted text", self.workflow) + def test_review_signal_is_passed_through_a_file(self): + self.assertIn(".agent-docs-review-signal.txt", self.workflow) + self.assertNotIn( + "AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}", self.workflow + ) if __name__ == "__main__": diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 1918fc98c..8003ce2a4 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -60,8 +60,10 @@ jobs: changed file and line or quoted text, explain the problem, and state the requested resolution. Set reviewer_login to `github-actions[bot]`, the runner account that will publish the review. - 5. Your final response must contain only the single [SIGNAL:pr-review] JSON record. - Do not repeat the diff, review rationale, or findings outside that record. + 5. Before your final response, write the single [SIGNAL:pr-review] JSON record to + ${{ github.workspace }}/.agent-docs-review-signal.txt. Your final response must + contain that same single record. Do not repeat the diff, review rationale, or + findings outside that record. - name: Dismiss stale automated change requests env: GH_TOKEN: ${{ github.token }} @@ -80,11 +82,10 @@ jobs: - name: Publish the independent review env: GH_TOKEN: ${{ github.token }} - AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }} run: | - printf '%s' "$AGENT_OUTPUT" > /tmp/agent-output.txt + test -s .agent-docs-review-signal.txt python3 .agents/skills/doc_quality_policy/publish_review_signal.py \ - --agent-output /tmp/agent-output.txt \ + --agent-output .agent-docs-review-signal.txt \ --pr "${{ github.event.pull_request.number }}" \ --head-sha "${{ github.event.pull_request.head.sha }}" \ --output /tmp/review-request.json @@ -98,12 +99,10 @@ jobs: - name: Verify the current review signal and GitHub review env: GH_TOKEN: ${{ github.token }} - AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }} run: | - printf '%s' "$AGENT_OUTPUT" > /tmp/agent-output.txt python3 .agents/skills/doc_quality_policy/verify_review_signal.py \ --repo "${{ github.repository }}" \ --pr "${{ github.event.pull_request.number }}" \ --head-sha "${{ github.event.pull_request.head.sha }}" \ - --agent-output /tmp/agent-output.txt \ + --agent-output .agent-docs-review-signal.txt \ --reviewer-login github-actions[bot] From 09f2ac9c5fd399a9da6c0758db2b0e1cd0d276fd Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 18:43:11 -0600 Subject: [PATCH 12/46] ci: harden agent docs review handoff Co-Authored-By: Warp <agent@warp.dev> --- .../normalize_review_signal.py | 56 +++++++++++++++++++ .../test_agent_docs_review_workflow.py | 2 + .../test_normalize_review_signal.py | 38 +++++++++++++ .github/workflows/agent-docs-review.yml | 12 +++- .github/workflows/ci.yml | 1 + src/content/docs/factories/runners.mdx | 12 ++-- .../docs/platform/unmanaged-execution.mdx | 2 +- 7 files changed, 116 insertions(+), 7 deletions(-) create mode 100644 .agents/skills/doc_quality_policy/normalize_review_signal.py create mode 100644 .agents/skills/doc_quality_policy/test_normalize_review_signal.py diff --git a/.agents/skills/doc_quality_policy/normalize_review_signal.py b/.agents/skills/doc_quality_policy/normalize_review_signal.py new file mode 100644 index 000000000..3f3b1bb04 --- /dev/null +++ b/.agents/skills/doc_quality_policy/normalize_review_signal.py @@ -0,0 +1,56 @@ +#!/usr/bin/env python3 +"""Apply workflow-owned identifiers to an agent-written review signal.""" +from __future__ import annotations + +import argparse +import importlib.util +import json +import sys +from pathlib import Path +from typing import List, Optional + +_HERE = Path(__file__).resolve().parent +_SPEC = importlib.util.spec_from_file_location( + "verify_review_signal", _HERE / "verify_review_signal.py" +) +vrs = importlib.util.module_from_spec(_SPEC) +sys.modules[_SPEC.name] = vrs +_SPEC.loader.exec_module(vrs) + + +def normalize_review_signal( + agent_output: str, pr_number: str, head_sha: str, reviewer_login: str +) -> str: + signal, problems = vrs._parse_signal(agent_output) + if signal is None: + raise ValueError("; ".join(problems)) + signal["pr"] = str(pr_number) + signal["head_sha"] = head_sha + signal["reviewer_login"] = reviewer_login + return f"[SIGNAL:pr-review] {json.dumps(signal, sort_keys=True)}\n" + + +def main(argv: Optional[List[str]] = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--agent-output", required=True) + parser.add_argument("--pr", required=True) + parser.add_argument("--head-sha", required=True) + parser.add_argument("--reviewer-login", default="github-actions[bot]") + parser.add_argument("--output", required=True) + args = parser.parse_args(argv) + try: + normalized = normalize_review_signal( + Path(args.agent_output).read_text(encoding="utf-8"), + args.pr, + args.head_sha, + args.reviewer_login, + ) + except (OSError, ValueError) as exc: + print(f"error: {exc}", file=sys.stderr) + return 1 + Path(args.output).write_text(normalized, encoding="utf-8") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py index bcf120f8c..a241b3429 100644 --- a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py +++ b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py @@ -35,6 +35,8 @@ def test_all_review_findings_must_supply_actionable_details(self): self.assertIn("file and line or quoted text", self.workflow) def test_review_signal_is_passed_through_a_file(self): self.assertIn(".agent-docs-review-signal.txt", self.workflow) + self.assertIn("Normalize the independent review signal", self.workflow) + self.assertIn("--output /tmp/agent-review-signal.txt", self.workflow) self.assertNotIn( "AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}", self.workflow ) diff --git a/.agents/skills/doc_quality_policy/test_normalize_review_signal.py b/.agents/skills/doc_quality_policy/test_normalize_review_signal.py new file mode 100644 index 000000000..77eb0aa7a --- /dev/null +++ b/.agents/skills/doc_quality_policy/test_normalize_review_signal.py @@ -0,0 +1,38 @@ +#!/usr/bin/env python3 +"""Unit tests for normalize_review_signal.py.""" +from __future__ import annotations + +import importlib.util +import json +import sys +import unittest +from pathlib import Path + +_HERE = Path(__file__).resolve().parent +_SPEC = importlib.util.spec_from_file_location( + "normalize_review_signal", _HERE / "normalize_review_signal.py" +) +nrs = importlib.util.module_from_spec(_SPEC) +sys.modules[_SPEC.name] = nrs +_SPEC.loader.exec_module(nrs) + + +class TestNormalizeReviewSignal(unittest.TestCase): + def test_replaces_workflow_owned_identifiers(self): + output = ( + '[SIGNAL:pr-review] {"pr":"old","head_sha":"old","verdict":"Approve",' + '"critical":0,"important":0,"reviewer_login":"agent"}' + ) + + normalized = nrs.normalize_review_signal( + output, "748", "current-sha", "github-actions[bot]" + ) + signal = json.loads(normalized.removeprefix("[SIGNAL:pr-review] ")) + + self.assertEqual(signal["pr"], "748") + self.assertEqual(signal["head_sha"], "current-sha") + self.assertEqual(signal["reviewer_login"], "github-actions[bot]") + + +if __name__ == "__main__": + unittest.main() diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 8003ce2a4..0fda07399 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -64,6 +64,15 @@ jobs: ${{ github.workspace }}/.agent-docs-review-signal.txt. Your final response must contain that same single record. Do not repeat the diff, review rationale, or findings outside that record. + + - name: Normalize the independent review signal + run: | + test -s .agent-docs-review-signal.txt + python3 .agents/skills/doc_quality_policy/normalize_review_signal.py \ + --agent-output .agent-docs-review-signal.txt \ + --pr "${{ github.event.pull_request.number }}" \ + --head-sha "${{ github.event.pull_request.head.sha }}" \ + --output /tmp/agent-review-signal.txt - name: Dismiss stale automated change requests env: GH_TOKEN: ${{ github.token }} @@ -83,9 +92,8 @@ jobs: env: GH_TOKEN: ${{ github.token }} run: | - test -s .agent-docs-review-signal.txt python3 .agents/skills/doc_quality_policy/publish_review_signal.py \ - --agent-output .agent-docs-review-signal.txt \ + --agent-output /tmp/agent-review-signal.txt \ --pr "${{ github.event.pull_request.number }}" \ --head-sha "${{ github.event.pull_request.head.sha }}" \ --output /tmp/review-request.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6a00fe72e..fbc9718df 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,6 +63,7 @@ jobs: python3 .agents/skills/doc_quality_policy/test_check_compression_contract.py python3 .agents/skills/doc_quality_policy/test_verify_review_signal.py python3 .agents/skills/doc_quality_policy/test_publish_review_signal.py + python3 .agents/skills/doc_quality_policy/test_normalize_review_signal.py python3 .agents/skills/doc_quality_policy/test_stale_review_requests.py python3 .agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py python3 .agents/skills/doc_quality_policy/test_manifest.py diff --git a/src/content/docs/factories/runners.mdx b/src/content/docs/factories/runners.mdx index 987835724..7e9fe8da9 100644 --- a/src/content/docs/factories/runners.mdx +++ b/src/content/docs/factories/runners.mdx @@ -4,14 +4,18 @@ sidebar: label: "Runners" description: >- Runners define the OS, architecture, instance size, and sandbox image for - Warp Factories work. + cloud agent runs, including work from Warp Factories. --- import { VARS } from '@data/vars'; import { Tabs, TabItem } from '@astrojs/starlight/components'; -Runners define the compute a factory agent runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. Select runners in the [factory definition](/factories/factory-as-code/) or the [factory dashboard](/factories/factory-dashboard/). +Runners define the compute a [cloud agent](/platform/) runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. Factory agents select runners through the [factory definition](/factories/factory-as-code/) or the [factory dashboard](/factories/factory-dashboard/). -A runner is a reusable compute configuration. Where an [environment](/platform/environments/) defines _what_ an agent works on (the repos, setup commands, and toolchain), a runner defines _where and on what hardware_ that work executes. Separating the two lets a factory use a small Linux runner for triage and a larger runner for builds. +A runner is a reusable compute configuration. Where an [environment](/platform/environments/) defines _what_ an agent works on (the repos, setup commands, and toolchain), a runner defines _where and on what hardware_ that work executes. This lets any cloud-agent workflow use different machine shapes for different workloads. + +## Configure runners for a factory + +Set a factory's default runner in `agentDefaults.runner`, then override it per agent or automation when the work needs different compute. For file-managed factories, edit `runners/*.yaml` in the factory definition. For Warp-managed factories, edit runner files in the factory dashboard. :::note Most runs don't need a custom runner. Every environment has a default runner, and Warp picks a sensible default shape when you don't specify one. Create a runner when you need a specific OS, architecture, instance size, or sandbox image. @@ -64,7 +68,7 @@ Each environment has a default runner. Specifying a runner for a run overrides t ## Managing runners with the legacy CLI -For a file-managed factory, edit `runners/*.yaml` in the factory definition. For a Warp-managed factory, edit runner files in the factory dashboard. The legacy [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) also supports creating, listing, updating, and deleting reusable runners. +The legacy [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) also supports creating, listing, updating, and deleting reusable runners for standalone cloud-agent workflows. ### Create a runner diff --git a/src/content/docs/platform/unmanaged-execution.mdx b/src/content/docs/platform/unmanaged-execution.mdx index 68df30864..eadd5dc62 100644 --- a/src/content/docs/platform/unmanaged-execution.mdx +++ b/src/content/docs/platform/unmanaged-execution.mdx @@ -135,6 +135,6 @@ Unmanaged runs don't ship with the bundled declarations script, so end-of-run wo * [Self-hosting overview](/factories/self-hosting/) — Compare managed and unmanaged, plus the architecture decision guide. * [GitHub Actions integration](/platform/integrations/github-actions/) — Run agents in CI with the official action. -* [Deployment patterns](/factories/deployment-patterns/) — Pattern 1 (CLI-only) explains the unmanaged model conceptually. +* [Deployment patterns](/factories/deployment-patterns/) — The Standalone CLI-only agents section describes the unmanaged model conceptually. * [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Full CLI reference for `oz agent run` and related commands. * [Agent Session Sharing](/agents/local-agents/session-sharing/) — Attach to running sessions to monitor or steer them. From 5fde04c78e09c3d5deb800b3915314f233e2bbfe Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Tue, 15 Sep 2026 18:52:59 -0600 Subject: [PATCH 13/46] ci: capture agent docs review output to file Co-Authored-By: Warp <agent@warp.dev> --- .../normalize_review_signal.py | 56 ------------------- .../test_agent_docs_review_workflow.py | 5 +- .../test_normalize_review_signal.py | 38 ------------- .github/workflows/agent-docs-review.yml | 40 ++++++------- .github/workflows/ci.yml | 1 - 5 files changed, 22 insertions(+), 118 deletions(-) diff --git a/.agents/skills/doc_quality_policy/normalize_review_signal.py b/.agents/skills/doc_quality_policy/normalize_review_signal.py index 3f3b1bb04..e69de29bb 100644 --- a/.agents/skills/doc_quality_policy/normalize_review_signal.py +++ b/.agents/skills/doc_quality_policy/normalize_review_signal.py @@ -1,56 +0,0 @@ -#!/usr/bin/env python3 -"""Apply workflow-owned identifiers to an agent-written review signal.""" -from __future__ import annotations - -import argparse -import importlib.util -import json -import sys -from pathlib import Path -from typing import List, Optional - -_HERE = Path(__file__).resolve().parent -_SPEC = importlib.util.spec_from_file_location( - "verify_review_signal", _HERE / "verify_review_signal.py" -) -vrs = importlib.util.module_from_spec(_SPEC) -sys.modules[_SPEC.name] = vrs -_SPEC.loader.exec_module(vrs) - - -def normalize_review_signal( - agent_output: str, pr_number: str, head_sha: str, reviewer_login: str -) -> str: - signal, problems = vrs._parse_signal(agent_output) - if signal is None: - raise ValueError("; ".join(problems)) - signal["pr"] = str(pr_number) - signal["head_sha"] = head_sha - signal["reviewer_login"] = reviewer_login - return f"[SIGNAL:pr-review] {json.dumps(signal, sort_keys=True)}\n" - - -def main(argv: Optional[List[str]] = None) -> int: - parser = argparse.ArgumentParser(description=__doc__) - parser.add_argument("--agent-output", required=True) - parser.add_argument("--pr", required=True) - parser.add_argument("--head-sha", required=True) - parser.add_argument("--reviewer-login", default="github-actions[bot]") - parser.add_argument("--output", required=True) - args = parser.parse_args(argv) - try: - normalized = normalize_review_signal( - Path(args.agent_output).read_text(encoding="utf-8"), - args.pr, - args.head_sha, - args.reviewer_login, - ) - except (OSError, ValueError) as exc: - print(f"error: {exc}", file=sys.stderr) - return 1 - Path(args.output).write_text(normalized, encoding="utf-8") - return 0 - - -if __name__ == "__main__": - sys.exit(main()) diff --git a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py index a241b3429..cb2d2cb22 100644 --- a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py +++ b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py @@ -34,9 +34,8 @@ def test_all_review_findings_must_supply_actionable_details(self): self.assertIn("critical, important, suggestion, or nit", self.workflow) self.assertIn("file and line or quoted text", self.workflow) def test_review_signal_is_passed_through_a_file(self): - self.assertIn(".agent-docs-review-signal.txt", self.workflow) - self.assertIn("Normalize the independent review signal", self.workflow) - self.assertIn("--output /tmp/agent-review-signal.txt", self.workflow) + self.assertIn('oz "${args[@]}" > /tmp/agent-output.txt', self.workflow) + self.assertIn("--agent-output /tmp/agent-output.txt", self.workflow) self.assertNotIn( "AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}", self.workflow ) diff --git a/.agents/skills/doc_quality_policy/test_normalize_review_signal.py b/.agents/skills/doc_quality_policy/test_normalize_review_signal.py index 77eb0aa7a..e69de29bb 100644 --- a/.agents/skills/doc_quality_policy/test_normalize_review_signal.py +++ b/.agents/skills/doc_quality_policy/test_normalize_review_signal.py @@ -1,38 +0,0 @@ -#!/usr/bin/env python3 -"""Unit tests for normalize_review_signal.py.""" -from __future__ import annotations - -import importlib.util -import json -import sys -import unittest -from pathlib import Path - -_HERE = Path(__file__).resolve().parent -_SPEC = importlib.util.spec_from_file_location( - "normalize_review_signal", _HERE / "normalize_review_signal.py" -) -nrs = importlib.util.module_from_spec(_SPEC) -sys.modules[_SPEC.name] = nrs -_SPEC.loader.exec_module(nrs) - - -class TestNormalizeReviewSignal(unittest.TestCase): - def test_replaces_workflow_owned_identifiers(self): - output = ( - '[SIGNAL:pr-review] {"pr":"old","head_sha":"old","verdict":"Approve",' - '"critical":0,"important":0,"reviewer_login":"agent"}' - ) - - normalized = nrs.normalize_review_signal( - output, "748", "current-sha", "github-actions[bot]" - ) - signal = json.loads(normalized.removeprefix("[SIGNAL:pr-review] ")) - - self.assertEqual(signal["pr"], "748") - self.assertEqual(signal["head_sha"], "current-sha") - self.assertEqual(signal["reviewer_login"], "github-actions[bot]") - - -if __name__ == "__main__": - unittest.main() diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 0fda07399..35686e2e8 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -37,12 +37,16 @@ jobs: uses: actions/checkout@v4 - name: Run independent review-docs-pr agent - id: oz-review - uses: warpdotdev/oz-agent-action@main - with: - warp_api_key: ${{ secrets.WARP_API_KEY }} - profile: ${{ vars.WARP_AGENT_PROFILE || '' }} - prompt: | + env: + WARP_API_KEY: ${{ secrets.WARP_API_KEY }} + WARP_AGENT_PROFILE: ${{ vars.WARP_AGENT_PROFILE || '' }} + run: | + curl --fail --location \ + "https://app.warp.dev/download/cli?os=linux&package=deb&arch=x86_64&channel=stable" \ + --output /tmp/oz.deb + sudo dpkg -i /tmp/oz.deb + sudo apt-get -f install -y + PROMPT="$(cat <<'EOF' Run the review-docs-pr skill against warpdotdev/docs PR #${{ github.event.pull_request.number }} at head SHA ${{ github.event.pull_request.head.sha }}. This PR carries the warpy-factory agent marker, so it requires the independent v1 agent-doc quality review pass (see @@ -60,19 +64,15 @@ jobs: changed file and line or quoted text, explain the problem, and state the requested resolution. Set reviewer_login to `github-actions[bot]`, the runner account that will publish the review. - 5. Before your final response, write the single [SIGNAL:pr-review] JSON record to - ${{ github.workspace }}/.agent-docs-review-signal.txt. Your final response must - contain that same single record. Do not repeat the diff, review rationale, or - findings outside that record. - - - name: Normalize the independent review signal - run: | - test -s .agent-docs-review-signal.txt - python3 .agents/skills/doc_quality_policy/normalize_review_signal.py \ - --agent-output .agent-docs-review-signal.txt \ - --pr "${{ github.event.pull_request.number }}" \ - --head-sha "${{ github.event.pull_request.head.sha }}" \ - --output /tmp/agent-review-signal.txt + 5. Your final response must contain only the single [SIGNAL:pr-review] JSON record. + Do not repeat the diff, review rationale, or findings outside that record. + EOF + )" + args=(agent run --sandboxed --output-format text --prompt "$PROMPT") + if [ -n "$WARP_AGENT_PROFILE" ]; then + args+=(--profile "$WARP_AGENT_PROFILE") + fi + oz "${args[@]}" > /tmp/agent-output.txt - name: Dismiss stale automated change requests env: GH_TOKEN: ${{ github.token }} @@ -93,7 +93,7 @@ jobs: GH_TOKEN: ${{ github.token }} run: | python3 .agents/skills/doc_quality_policy/publish_review_signal.py \ - --agent-output /tmp/agent-review-signal.txt \ + --agent-output /tmp/agent-output.txt \ --pr "${{ github.event.pull_request.number }}" \ --head-sha "${{ github.event.pull_request.head.sha }}" \ --output /tmp/review-request.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fbc9718df..6a00fe72e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,7 +63,6 @@ jobs: python3 .agents/skills/doc_quality_policy/test_check_compression_contract.py python3 .agents/skills/doc_quality_policy/test_verify_review_signal.py python3 .agents/skills/doc_quality_policy/test_publish_review_signal.py - python3 .agents/skills/doc_quality_policy/test_normalize_review_signal.py python3 .agents/skills/doc_quality_policy/test_stale_review_requests.py python3 .agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py python3 .agents/skills/doc_quality_policy/test_manifest.py From 1f0253fd73e93dd3c66ae61879cb11972f07bf00 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 11:40:04 -0600 Subject: [PATCH 14/46] docs: reconcile factories GA restructure with main Co-Authored-By: Warp <agent@warp.dev> --- .../test_agent_docs_review_workflow.py | 1 + .github/workflows/agent-docs-review.yml | 2 +- src/content/docs/factories/factory-as-code.mdx | 2 +- src/sidebar.ts | 9 ++++++++- 4 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py index cb2d2cb22..d30aae6d4 100644 --- a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py +++ b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py @@ -36,6 +36,7 @@ def test_all_review_findings_must_supply_actionable_details(self): def test_review_signal_is_passed_through_a_file(self): self.assertIn('oz "${args[@]}" > /tmp/agent-output.txt', self.workflow) self.assertIn("--agent-output /tmp/agent-output.txt", self.workflow) + self.assertNotIn(".agent-docs-review-signal.txt", self.workflow) self.assertNotIn( "AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}", self.workflow ) diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 35686e2e8..3043de760 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -112,5 +112,5 @@ jobs: --repo "${{ github.repository }}" \ --pr "${{ github.event.pull_request.number }}" \ --head-sha "${{ github.event.pull_request.head.sha }}" \ - --agent-output .agent-docs-review-signal.txt \ + --agent-output /tmp/agent-output.txt \ --reviewer-login github-actions[bot] diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index a7296832f..113eed296 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -725,7 +725,7 @@ agentDefaults: workerHost: SELF_HOSTED_WORKER_ID ``` -Pair `workerHost` with a runner whose `platform` matches the worker's operating system and architecture. Follow the [Self-hosting quickstart](/platform/self-hosting/quickstart/) to deploy and connect a managed worker, then see [choose an execution host](/factories/infrastructure-and-security/#choose-an-execution-host) for the factory-specific setup. For a working definition, see [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker). +Pair `workerHost` with a runner whose `platform` matches the worker's operating system and architecture. Follow the [Self-hosting quickstart](/factories/self-hosting/quickstart/) to deploy and connect a managed worker, then see [choose an execution host](/factories/infrastructure-and-security/#choose-an-execution-host) for the factory-specific setup. For a working definition, see [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker). ## Related pages diff --git a/src/sidebar.ts b/src/sidebar.ts index 100c1aed5..a6ba35d7f 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -459,7 +459,14 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/api-and-sdk/troubleshooting', label: 'API troubleshooting' }, { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'API errors' }, { slug: 'factories/factory-mcp', label: 'Factory MCP' }, - { slug: 'factories/webhooks', label: 'Webhooks' }, + { + label: 'Webhooks', + collapsed: false, + items: [ + { slug: 'factories/webhooks', label: 'Overview' }, + { slug: 'factories/webhooks/vercel', label: 'Vercel' }, + ], + }, ], }, { From aea92362467077ef85a757dd2807b815eaa31426 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:03:30 -0600 Subject: [PATCH 15/46] docs: remove redirect chains and orphaned files Co-Authored-By: Warp <agent@warp.dev> --- vercel.json | 142 ++++++++++++++++++++++++++-------------------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/vercel.json b/vercel.json index 835e2d784..536550d61 100644 --- a/vercel.json +++ b/vercel.json @@ -359,7 +359,7 @@ }, { "source": "/platform/api-sdk", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { @@ -1924,12 +1924,12 @@ }, { "source": "/errors", - "destination": "/reference/api-and-sdk/troubleshooting/errors/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/", "statusCode": 308 }, { "source": "/errors/:code", - "destination": "/reference/api-and-sdk/troubleshooting/errors/:code/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/:code/", "statusCode": 308 }, { @@ -2759,12 +2759,12 @@ }, { "source": "/reference/agent-api-and-sdk(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/ambient-agents/mcp-servers-for-agents(/?)", - "destination": "/reference/cli/mcp-servers/", + "destination": "/agents/cli/oz-cli/mcp-servers/", "statusCode": 308 }, { @@ -2784,147 +2784,147 @@ }, { "source": "/reference/api-and-sdk/troubleshooting/errors/authentication_required(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/authentication-required/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/authentication-required/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/budget_exceeded(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/budget-exceeded/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/content_policy_violation(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/content-policy-violation/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/content-policy-violation/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/environment_setup_failed(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/external_authentication_required(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/agent_process_failed(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/agent-process-failed/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/feature_not_available(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/feature-not-available/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/feature-not-available/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/infrastructure_timeout(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/insufficient_credits(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/integration_disabled(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/integration-disabled/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/integration-disabled/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/integration_not_configured(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/integration-not-configured/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/internal_error(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/internal-error/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/internal-error/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/invalid_request(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/invalid-request/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/invalid-request/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/not_authorized(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/not-authorized/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/not-authorized/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/operation_not_supported(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/operation-not-supported/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/operation-not-supported/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/resource_not_found(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/resource-not-found/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/resource-not-found/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/resource_unavailable(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/resource-unavailable/", "statusCode": 308 }, { "source": "/reference/cli#api-key-authentication", - "destination": "/reference/cli/api-keys/", + "destination": "/agents/cli/oz-cli/api-keys/", "statusCode": 308 }, { "source": "/reference/cli#quickstart-guide", - "destination": "/reference/cli/quickstart/", + "destination": "/agents/cli/oz-cli/quickstart/", "statusCode": 308 }, { "source": "/reference/cli/README.md#api-key-authentication", - "destination": "/reference/cli/api-keys/", + "destination": "/agents/cli/oz-cli/api-keys/", "statusCode": 308 }, { "source": "/reference/cli/integrations-and-environments(/?)", - "destination": "/reference/cli/integration-setup/", + "destination": "/agents/cli/oz-cli/integration-setup/", "statusCode": 308 }, { "source": "/reference/cli/mcp-for-cloud-agents(/?)", - "destination": "/reference/cli/mcp-servers/", + "destination": "/agents/cli/oz-cli/mcp-servers/", "statusCode": 308 }, { "source": "/reference/cli/mcp-servers-for-cloud-agents(/?)", - "destination": "/reference/cli/mcp-servers/", + "destination": "/agents/cli/oz-cli/mcp-servers/", "statusCode": 308 }, { "source": "/reference/developers/cli(/?)", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/reference/developers/cli#api-key-authentication", - "destination": "/reference/cli/api-keys/#authenticating-with-api-keys", + "destination": "/agents/cli/oz-cli/api-keys/#authenticating-with-api-keys", "statusCode": 308 }, { "source": "/reference/developers/cli#generating-api-keys", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/reference/developers/cli#linux", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/reference/integrations/integrations-overview/integrations-and-environments(/?)", - "destination": "/reference/cli/integration-setup/", + "destination": "/agents/cli/oz-cli/integration-setup/", "statusCode": 308 }, { "source": "/reference/integrations/integrations-overview/integrations-and-environments#creating-an-environment", - "destination": "/reference/cli/integration-setup/#step-1-creating-an-environment", + "destination": "/agents/cli/oz-cli/integration-setup/#step-1-creating-an-environment", "statusCode": 308 }, { @@ -2939,57 +2939,57 @@ }, { "source": "/reference/platform/agent-api-and-sdk(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/platform/agent-api-and-sdk#agent-sdk", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/platform/agent-api-and-sdk/agent(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/platform/agent-api-and-sdk/agent-1(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/platform/agent-api-and-sdk/demo-sentry-monitoring-with-sdk(/?)", - "destination": "/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/", + "destination": "/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/", "statusCode": 308 }, { "source": "/reference/platform/cli(/?)", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/reference/platform/cli#api-key-authentication", - "destination": "/reference/cli/api-keys/", + "destination": "/agents/cli/oz-cli/api-keys/", "statusCode": 308 }, { "source": "/reference/platform/cli/api-keys(/?)", - "destination": "/reference/cli/api-keys/", + "destination": "/agents/cli/oz-cli/api-keys/", "statusCode": 308 }, { "source": "/reference/platform/cli/integrations-and-environments(/?)", - "destination": "/reference/cli/integration-setup/", + "destination": "/agents/cli/oz-cli/integration-setup/", "statusCode": 308 }, { "source": "/reference/platform/cli/troubleshooting(/?)", - "destination": "/reference/cli/troubleshooting/", + "destination": "/agents/cli/oz-cli/troubleshooting/", "statusCode": 308 }, { "source": "/reference/platform/warp-platform(/?)", - "destination": "/reference/", + "destination": "/factories/developer-tools/", "statusCode": 308 }, { @@ -4574,17 +4574,17 @@ }, { "source": "/reference/api-and-sdk/api-and-sdk(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/models(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/cli/cli(/?)", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -4724,7 +4724,7 @@ }, { "source": "/platform/warp-platform(/?)", - "destination": "/reference/", + "destination": "/factories/developer-tools/", "statusCode": 308 }, { @@ -4779,12 +4779,12 @@ }, { "source": "/errors/", - "destination": "/reference/api-and-sdk/troubleshooting/errors/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/", "statusCode": 308 }, { "source": "/errors/:code/", - "destination": "/reference/api-and-sdk/troubleshooting/errors/:code/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/:code/", "statusCode": 308 }, { @@ -4814,7 +4814,7 @@ }, { "source": "/platform/cli", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -4959,7 +4959,7 @@ }, { "source": "/platform/agent-api-and-sdk", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { @@ -5199,7 +5199,7 @@ }, { "source": "/platform/agent-api-and-sdk/agent-1", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { @@ -5254,7 +5254,7 @@ }, { "source": "/platform/cli/troubleshooting", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -5864,7 +5864,7 @@ }, { "source": "/developers/cli", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -6054,72 +6054,72 @@ }, { "source": "/platform/agent-api-and-sdk/agent", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/platform/agent-api-and-sdk/demo-sentry-monitoring-with-sdk", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/platform/cli#api-key-authentication", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#bundled-with-warp", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#id-2.-authenticate", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#id-3.-run-an-agent", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#id-4.-add-github-context-optional", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#id-5.-next-steps", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#interactive-login-local-machines", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#running-agents", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#running-locally-warp-agent-run", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#running-the-cli", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#standalone-package", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#what-is-the-warp-cli", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -6249,7 +6249,7 @@ }, { "source": "/integrations/integrations-overview/integrations-and-environments", - "destination": "/reference/cli/integration-setup/", + "destination": "/agents/cli/oz-cli/integration-setup/", "statusCode": 308 }, { From eac28b7d8ef7bcef9716139a7cd193d945e1071e Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:04:00 -0600 Subject: [PATCH 16/46] ci: remove orphaned review signal files Co-Authored-By: Warp <agent@warp.dev> --- .agents/skills/doc_quality_policy/normalize_review_signal.py | 0 .agents/skills/doc_quality_policy/test_normalize_review_signal.py | 0 2 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 .agents/skills/doc_quality_policy/normalize_review_signal.py delete mode 100644 .agents/skills/doc_quality_policy/test_normalize_review_signal.py diff --git a/.agents/skills/doc_quality_policy/normalize_review_signal.py b/.agents/skills/doc_quality_policy/normalize_review_signal.py deleted file mode 100644 index e69de29bb..000000000 diff --git a/.agents/skills/doc_quality_policy/test_normalize_review_signal.py b/.agents/skills/doc_quality_policy/test_normalize_review_signal.py deleted file mode 100644 index e69de29bb..000000000 From b6b289268e2fca12bf49c1de75812d74730563c8 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:15:03 -0600 Subject: [PATCH 17/46] docs: address final factories review findings Co-Authored-By: Warp <agent@warp.dev> --- .github/workflows/agent-docs-review.yml | 4 +- .../docs/platform/transitioning-from-oz.mdx | 2 +- vercel.json | 37 ++++++++----------- 3 files changed, 19 insertions(+), 24 deletions(-) diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 3043de760..f5d2c8afc 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -44,8 +44,8 @@ jobs: curl --fail --location \ "https://app.warp.dev/download/cli?os=linux&package=deb&arch=x86_64&channel=stable" \ --output /tmp/oz.deb - sudo dpkg -i /tmp/oz.deb - sudo apt-get -f install -y + sudo apt-get update + sudo apt-get install -y /tmp/oz.deb PROMPT="$(cat <<'EOF' Run the review-docs-pr skill against warpdotdev/docs PR #${{ github.event.pull_request.number }} at head SHA ${{ github.event.pull_request.head.sha }}. This PR carries the warpy-factory agent diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx index a981cdb32..810bc5325 100644 --- a/src/content/docs/platform/transitioning-from-oz.mdx +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -27,7 +27,7 @@ Existing workflows and configuration continue to work today: ## What comes next -This page will add verified migration actions, compatibility dates, and replacement destinations as the product transition is finalized. Until then, continue using the workflow that fits your work today. +Migration actions, compatibility dates, and replacement destinations will be documented after product mapping is finalized. Until then, continue using the workflow that fits your work today. ## Related pages diff --git a/vercel.json b/vercel.json index 536550d61..75bfc36ba 100644 --- a/vercel.json +++ b/vercel.json @@ -5157,11 +5157,6 @@ "destination": "/agent-platform/capabilities/web-search/", "statusCode": 308 }, - { - "source": "/platform/deployment-patterns", - "destination": "/platform/deployment-patterns/", - "statusCode": 308 - }, { "source": "/agent-platform/warps-agent/agent-context/images-as-context", "destination": "/agent-platform/local-agents/agent-context/images-as-context/", @@ -6558,77 +6553,77 @@ "statusCode": 308 }, { - "source": "/platform/deployment-patterns", + "source": "/platform/deployment-patterns(/?)", "destination": "/factories/deployment-patterns/", "statusCode": 308 }, { - "source": "/platform/warp-hosting", + "source": "/platform/warp-hosting(/?)", "destination": "/factories/warp-hosting/", "statusCode": 308 }, { - "source": "/platform/runners", + "source": "/platform/runners(/?)", "destination": "/factories/runners/", "statusCode": 308 }, { - "source": "/platform/self-hosting", + "source": "/platform/self-hosting(/?)", "destination": "/factories/self-hosting/", "statusCode": 308 }, { - "source": "/platform/self-hosting/quickstart", + "source": "/platform/self-hosting/quickstart(/?)", "destination": "/factories/self-hosting/quickstart/", "statusCode": 308 }, { - "source": "/platform/self-hosting/managed-docker", + "source": "/platform/self-hosting/managed-docker(/?)", "destination": "/factories/self-hosting/managed-docker/", "statusCode": 308 }, { - "source": "/platform/self-hosting/managed-kubernetes", + "source": "/platform/self-hosting/managed-kubernetes(/?)", "destination": "/factories/self-hosting/managed-kubernetes/", "statusCode": 308 }, { - "source": "/platform/self-hosting/managed-direct", + "source": "/platform/self-hosting/managed-direct(/?)", "destination": "/factories/self-hosting/managed-direct/", "statusCode": 308 }, { - "source": "/platform/self-hosting/monitoring", + "source": "/platform/self-hosting/monitoring(/?)", "destination": "/factories/self-hosting/monitoring/", "statusCode": 308 }, { - "source": "/platform/self-hosting/reference", + "source": "/platform/self-hosting/reference(/?)", "destination": "/factories/self-hosting/reference/", "statusCode": 308 }, { - "source": "/platform/self-hosting/troubleshooting", + "source": "/platform/self-hosting/troubleshooting(/?)", "destination": "/factories/self-hosting/troubleshooting/", "statusCode": 308 }, { - "source": "/platform/self-hosting/unmanaged", + "source": "/platform/self-hosting/unmanaged(/?)", "destination": "/platform/unmanaged-execution/", "statusCode": 308 }, { - "source": "/platform/self-hosting/security-and-networking", + "source": "/platform/self-hosting/security-and-networking(/?)", "destination": "/platform/execution-security/", "statusCode": 308 }, { - "source": "/reference", + "source": "/reference(/?)", "destination": "/factories/developer-tools/", "statusCode": 308 }, { - "source": "/reference/api-and-sdk", + "source": "/reference/api-and-sdk(/?)", "destination": "/factories/api-and-sdk/", "statusCode": 308 }, @@ -6638,7 +6633,7 @@ "statusCode": 308 }, { - "source": "/reference/cli", + "source": "/reference/cli(/?)", "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, From bcbfb17fe2aa16bf532f86f9e29db19f103a2e08 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:25:46 -0600 Subject: [PATCH 18/46] docs: address agent review follow-up Co-Authored-By: Warp <agent@warp.dev> --- .github/workflows/agent-docs-review.yml | 2 +- src/content/docs/index.mdx | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index f5d2c8afc..5bbfaad58 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -68,7 +68,7 @@ jobs: Do not repeat the diff, review rationale, or findings outside that record. EOF )" - args=(agent run --sandboxed --output-format text --prompt "$PROMPT") + args=(agent run --output-format text --prompt "$PROMPT") if [ -n "$WARP_AGENT_PROFILE" ]; then args+=(--profile "$WARP_AGENT_PROFILE") fi diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 5eda8814e..f19440f69 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -46,3 +46,4 @@ Use Warp and the Warp Agent for interactive development. Use the {VARS.WARP_AUTO * [Start an agent conversation](/agents/) - Work with the Warp Agent in a local checkout. * [Run cloud agents](/platform/quickstart/) - Set up background automation. * [Set up a factory](/factories/quickstart/) - Route engineering work through Warp Factories. +* [Privacy and security](/support-and-community/privacy-and-security/privacy/) - Review Warp's data handling, privacy, and security practices. From 0f9a3d1d3fe6b0c5768c90d4d9571d49ea21c766 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:41:52 -0600 Subject: [PATCH 19/46] ci: pin and verify agent review CLI Co-Authored-By: Warp <agent@warp.dev> --- .../test_agent_docs_review_workflow.py | 5 +++++ .github/workflows/agent-docs-review.yml | 19 +++++++++++++++---- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py index d30aae6d4..230d5f826 100644 --- a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py +++ b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py @@ -41,6 +41,11 @@ def test_review_signal_is_passed_through_a_file(self): "AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}", self.workflow ) + def test_review_uses_a_pinned_signed_oz_package(self): + self.assertIn("0913165C78D5B7A41B42AC657FF7AB39D60F803F", self.workflow) + self.assertIn("signed-by=/etc/apt/keyrings/warpdotdev.gpg", self.workflow) + self.assertIn("oz-stable=0.2026.09.09.08.26.stable.02", self.workflow) + if __name__ == "__main__": unittest.main() diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 5bbfaad58..2c88e2a75 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -41,11 +41,22 @@ jobs: WARP_API_KEY: ${{ secrets.WARP_API_KEY }} WARP_AGENT_PROFILE: ${{ vars.WARP_AGENT_PROFILE || '' }} run: | - curl --fail --location \ - "https://app.warp.dev/download/cli?os=linux&package=deb&arch=x86_64&channel=stable" \ - --output /tmp/oz.deb sudo apt-get update - sudo apt-get install -y /tmp/oz.deb + sudo apt-get install -y gpg + curl --fail --location https://releases.warp.dev/linux/keys/warp.asc \ + --output /tmp/warpdotdev.asc + test "$( + gpg --show-keys --with-colons /tmp/warpdotdev.asc | + awk -F: '/^fpr:/ { print $10; exit }' + )" = "0913165C78D5B7A41B42AC657FF7AB39D60F803F" + gpg --dearmor --output /tmp/warpdotdev.gpg /tmp/warpdotdev.asc + sudo install -D -o root -g root -m 644 /tmp/warpdotdev.gpg \ + /etc/apt/keyrings/warpdotdev.gpg + sudo tee /etc/apt/sources.list.d/warpdotdev.list > /dev/null <<'EOF' + deb [arch=amd64 signed-by=/etc/apt/keyrings/warpdotdev.gpg] https://releases.warp.dev/linux/deb stable main + EOF + sudo apt-get update + sudo apt-get install -y oz-stable=0.2026.09.09.08.26.stable.02 PROMPT="$(cat <<'EOF' Run the review-docs-pr skill against warpdotdev/docs PR #${{ github.event.pull_request.number }} at head SHA ${{ github.event.pull_request.head.sha }}. This PR carries the warpy-factory agent From aa04f3ceba48929beae09319aff20d4042a06a68 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 12:47:04 -0600 Subject: [PATCH 20/46] docs: retarget self-hosted worker routing links Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/factories/self-hosting/managed-direct.mdx | 3 ++- src/content/docs/factories/self-hosting/managed-docker.mdx | 2 +- .../docs/factories/self-hosting/managed-kubernetes.mdx | 3 ++- src/content/docs/factories/self-hosting/quickstart.mdx | 3 ++- src/content/docs/factories/self-hosting/reference.mdx | 4 ++-- 5 files changed, 9 insertions(+), 6 deletions(-) diff --git a/src/content/docs/factories/self-hosting/managed-direct.mdx b/src/content/docs/factories/self-hosting/managed-direct.mdx index d8c6035dd..f14722f2c 100644 --- a/src/content/docs/factories/self-hosting/managed-direct.mdx +++ b/src/content/docs/factories/self-hosting/managed-direct.mdx @@ -127,6 +127,7 @@ backend: * [Self-hosted worker reference](/factories/self-hosting/reference/#direct-backend-config) — Full config schema for the Direct backend. * [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and the backend decision guide. -* [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. +* [Factory definition](/factories/factory-as-code/#agentdefaultsworkerhost) — Route factory work to a compatible worker and runner. +* [CLI reference](/agents/cli/oz-cli/) — Route standalone cloud agents to the worker with `--host`. * [Security and networking](/platform/execution-security/) — Data boundaries and security considerations for the Direct backend. * [Troubleshooting](/factories/self-hosting/troubleshooting/#direct-backend) — Common Direct-backend issues. diff --git a/src/content/docs/factories/self-hosting/managed-docker.mdx b/src/content/docs/factories/self-hosting/managed-docker.mdx index 8206877c5..ed42a2625 100644 --- a/src/content/docs/factories/self-hosting/managed-docker.mdx +++ b/src/content/docs/factories/self-hosting/managed-docker.mdx @@ -212,7 +212,7 @@ Sidecar images (the `oz` binary and dependencies) are pulled from public registr ## Routing runs to this worker -Once your Docker worker is connected, route tasks to it with `--host "<your-worker-id>"`. Routing is the same across all managed backends — see [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) for CLI, scheduled, integration, API, and web UI examples. +Once your Docker worker is connected, route factory work to it with `workerHost` in the [factory definition](/factories/factory-as-code/#agentdefaultsworkerhost). To route a standalone cloud agent with `--host "<your-worker-id>"`, see the [CLI reference](/agents/cli/oz-cli/). --- diff --git a/src/content/docs/factories/self-hosting/managed-kubernetes.mdx b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx index 50a53700a..44673a3c6 100644 --- a/src/content/docs/factories/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx @@ -268,7 +268,8 @@ See [Monitoring](/factories/self-hosting/monitoring/) for the full list of Helm * [Self-hosted worker reference](/factories/self-hosting/reference/) — Full CLI flag and config file schema, including every Kubernetes backend field. * [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and the backend decision guide. -* [Routing runs to this worker](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. +* [Factory definition](/factories/factory-as-code/#agentdefaultsworkerhost) — Route factory work to a compatible worker and runner. +* [CLI reference](/agents/cli/oz-cli/) — Route standalone cloud agents to the worker with `--host`. * [Environments](/platform/environments/) — Define the task image, repos, and setup commands. * [Monitoring](/factories/self-hosting/monitoring/) — OpenTelemetry metrics, including Helm chart metrics values. * [Security and networking](/platform/execution-security/) — RBAC, admission policies, and data boundaries. diff --git a/src/content/docs/factories/self-hosting/quickstart.mdx b/src/content/docs/factories/self-hosting/quickstart.mdx index 4841addaf..7c324ae7d 100644 --- a/src/content/docs/factories/self-hosting/quickstart.mdx +++ b/src/content/docs/factories/self-hosting/quickstart.mdx @@ -76,7 +76,8 @@ Open the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>, find the new task, and * [Unmanaged quickstart](/platform/unmanaged-execution/#unmanaged-quickstart) — ~5-minute CLI-only path: run `oz agent run` in your CI, Kubernetes pod, or dev box with no worker daemon and no Docker requirement. * [Managed: Docker](/factories/self-hosting/managed-docker/) — Full Docker backend setup, including private registries, volume mounts, and runtime configuration. * [Environments](/platform/environments/) — Define a repository, Docker image, and setup commands so agents have a reproducible workspace for every run. -* [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to route tasks from schedules, integrations (Slack, Linear), the API, and the {VARS.WEB_APP}. +* [Factory definition](/factories/factory-as-code/#agentdefaultsworkerhost) — Route factory work to a compatible worker and runner. +* [CLI reference](/agents/cli/oz-cli/) — Route standalone cloud agents to the worker with `--host`. * [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Deploy workers into a Kubernetes cluster with Helm. * [Self-hosted worker reference](/factories/self-hosting/reference/) — All CLI flags and config file options. diff --git a/src/content/docs/factories/self-hosting/reference.mdx b/src/content/docs/factories/self-hosting/reference.mdx index ae0e017a2..075ecf499 100644 --- a/src/content/docs/factories/self-hosting/reference.mdx +++ b/src/content/docs/factories/self-hosting/reference.mdx @@ -189,9 +189,9 @@ When deploying with the Helm chart, use the `metrics.*` values instead of settin --- -## Routing runs to self-hosted workers +## Routing work to self-hosted workers -Once a worker is running, route cloud agent runs to it with the `--host` flag or its equivalents. See [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) for examples across the CLI, schedules, integrations, the API, and the web UI. +To route factory work to a worker, set `workerHost` and a compatible runner in the [factory definition](/factories/factory-as-code/#agentdefaultsworkerhost). To route a standalone cloud agent to the worker with `--host`, see the [CLI reference](/agents/cli/oz-cli/). --- From 92eaf7628fe1cb85355f06393cb83b5ba4d1e789 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 13:11:37 -0600 Subject: [PATCH 21/46] docs: refine Warp products introduction Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index f19440f69..10058c719 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -8,7 +8,7 @@ sidebar: --- import { VARS } from '@data/vars'; -Warp is an [open-source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that brings together the terminal, coding agents, cloud orchestration, and Warp Factories. Use Warp to work interactively, run the Warp Agent from any terminal, automate recurring work in the cloud, and build team workflows with Warp Factories. +Warp is an [open-source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that brings together terminal work, coding agents, and cloud automation. Use Warp to work interactively, run the Warp Agent from any terminal, automate recurring work in the cloud, and build team workflows with Warp Factories. ## Warp From 78cd52ce0171d5c05c5f8571f30180f02be593e6 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 13:21:11 -0600 Subject: [PATCH 22/46] docs: consolidate factories sidebar group Co-Authored-By: Warp <agent@warp.dev> --- src/sidebar.ts | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/src/sidebar.ts b/src/sidebar.ts index a6ba35d7f..3b0bfb07d 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -403,16 +403,13 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // next door, since the underlying concepts are the same. items: [ { - label: 'Overview', + label: 'Factories', items: [ { slug: 'factories', label: 'Overview' }, { slug: 'factories/how-factories-work', label: 'How Factories work' }, + { slug: 'factories/quickstart', label: 'Quickstart' }, ], }, - { - label: 'Get started', - items: [{ slug: 'factories/quickstart', label: 'Quickstart' }], - }, { // Parallel to 'Agent configuration' in the Automation Platform tab. // Scoped to the factory itself: who runs the work, how it is defined, From ff6da38d369fe2fc6efa89fc11512585f336db58 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 16:55:56 -0600 Subject: [PATCH 23/46] Update documentation for factory API and managed self-hosting --- src/content/docs/factories/api-and-sdk/index.mdx | 7 +++++-- src/content/docs/factories/self-hosting/index.mdx | 2 ++ 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx index 943f9c759..6774e5817 100644 --- a/src/content/docs/factories/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -10,9 +10,12 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -The {VARS.API_SDK_NAME} lets you integrate with Warp Factories and operate the cloud agent runs behind them. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling. +Use the [factory API](/factories/factory-api/) to find a factory and send it new work. Use the {VARS.API_SDK_NAME} to start standalone cloud-agent runs, or to monitor, continue, and cancel any run after it starts. -Use the [factory API](/factories/factory-api/) to discover a factory and send it work. Use this API and SDK reference to monitor factory runs, submit follow-ups, inspect results, or start standalone cloud-agent runs from CI, internal tools, and custom integrations. +| API | Use it for | +| --- | --- | +| **Factory API** | Find a factory and dispatch new work to its foreman. | +| **{VARS.API_SDK_NAME}** | Start standalone cloud-agent runs, and manage factory or standalone runs after they begin. | :::note Some examples in this reference and the [CLI reference](/agents/cli/oz-cli/) use `oz` commands (for example, `oz environment list`) from the {VARS.WARP_AGENT_CLI}. Those commands remain available during the transition. The [Warp Agent CLI reference](/agents/cli/reference/) does not yet document a `warp` equivalent. diff --git a/src/content/docs/factories/self-hosting/index.mdx b/src/content/docs/factories/self-hosting/index.mdx index d58babe69..7544bf4f2 100644 --- a/src/content/docs/factories/self-hosting/index.mdx +++ b/src/content/docs/factories/self-hosting/index.mdx @@ -14,6 +14,8 @@ Managed self-hosting runs factory work on infrastructure you control. A worker c Managed self-hosting is available to Enterprise teams. [Contact sales](https://www.warp.dev/contact-sales) to enable it for your team. ::: +Managed workers run on Linux `amd64` or `arm64` hosts. + <a id="managed-architecture"></a> ## How managed self-hosting works From c5be80d7e10596efcc6fd6249a1a1e47fdd271ce Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Wed, 16 Sep 2026 17:12:39 -0600 Subject: [PATCH 24/46] docs: resolve self-hosting review feedback Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/factories/deployment-patterns.mdx | 2 +- src/content/docs/factories/self-hosting/index.mdx | 4 ++-- .../docs/factories/self-hosting/quickstart.mdx | 13 ------------- 3 files changed, 3 insertions(+), 16 deletions(-) diff --git a/src/content/docs/factories/deployment-patterns.mdx b/src/content/docs/factories/deployment-patterns.mdx index e6d23f9ef..f993a5e3c 100644 --- a/src/content/docs/factories/deployment-patterns.mdx +++ b/src/content/docs/factories/deployment-patterns.mdx @@ -96,7 +96,7 @@ Think of managed self-hosting as **customer-hosted execution with Warp-hosted or Self-hosting has two architectures that differ on **who orchestrates agent runs** (both keep code and execution on your infrastructure): * **[Managed](/factories/self-hosting/#managed-architecture)** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates. You run the `oz-agent-worker` daemon; the {VARS.WARP_AUTOMATION_PLATFORM} routes runs to it from Slack, Linear, schedules, the API, or `oz agent run-cloud`. Tasks execute in Docker containers, Kubernetes Jobs, or directly on the host. -* **[Unmanaged](/platform/unmanaged-execution/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment. This is a standalone-agent model, not a factory host. +* **[Unmanaged](/platform/unmanaged-execution/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment for standalone-agent work. Route factory work to a managed worker. Why teams choose self-hosted execution: diff --git a/src/content/docs/factories/self-hosting/index.mdx b/src/content/docs/factories/self-hosting/index.mdx index 7544bf4f2..8dec2503a 100644 --- a/src/content/docs/factories/self-hosting/index.mdx +++ b/src/content/docs/factories/self-hosting/index.mdx @@ -14,7 +14,7 @@ Managed self-hosting runs factory work on infrastructure you control. A worker c Managed self-hosting is available to Enterprise teams. [Contact sales](https://www.warp.dev/contact-sales) to enable it for your team. ::: -Managed workers run on Linux `amd64` or `arm64` hosts. +Managed workers run only on Linux `amd64` or `arm64` hosts. To run agents on macOS or Windows, use [unmanaged execution](/platform/unmanaged-execution/). <a id="managed-architecture"></a> @@ -22,7 +22,7 @@ Managed workers run on Linux `amd64` or `arm64` hosts. Run the `oz-agent-worker` daemon on infrastructure that can reach your repositories and internal services. The worker connects outbound to the {VARS.WARP_AUTOMATION_PLATFORM}, waits for factory work, and runs each task using the backend you configure. -A managed worker is the self-hosted execution option for a factory. [Unmanaged execution](/platform/unmanaged-execution/) runs `oz agent run` directly from your own CI or infrastructure, but it cannot run factory work. +A managed worker is the self-hosted execution option for a factory. [Unmanaged execution](/platform/unmanaged-execution/) runs standalone agents directly from your own CI or infrastructure. Route factory work to a managed worker through the [factory definition](/factories/factory-as-code/#agentdefaultsworkerhost). <a id="choosing-a-managed-backend"></a> diff --git a/src/content/docs/factories/self-hosting/quickstart.mdx b/src/content/docs/factories/self-hosting/quickstart.mdx index 7c324ae7d..34a8bcab5 100644 --- a/src/content/docs/factories/self-hosting/quickstart.mdx +++ b/src/content/docs/factories/self-hosting/quickstart.mdx @@ -80,16 +80,3 @@ Open the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>, find the new task, and * [CLI reference](/agents/cli/oz-cli/) — Route standalone cloud agents to the worker with `--host`. * [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Deploy workers into a Kubernetes cluster with Helm. * [Self-hosted worker reference](/factories/self-hosting/reference/) — All CLI flags and config file options. - -## Troubleshooting - -**Worker won't start**\ -Verify Docker is running (`docker info`) and that the daemon platform is `linux/amd64` or `linux/arm64`. Musl-based (Alpine) worker hosts are not supported. - -**Worker won't connect**\ -Verify your API key has team scope. Ensure the machine has outbound internet access to `oz.warp.dev:443`. Increase log verbosity with `--log-level debug` to see connection details. - -**Task stays queued and never runs**\ -Confirm the `--host` value you passed to `oz agent run-cloud` matches your `--worker-id` exactly (case-sensitive). Check that the worker's team matches the team creating the task. - -For more, see [Troubleshooting](/factories/self-hosting/troubleshooting/). From ff13a606058c4fe07c0076b1c406782efb6c9161 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 17 Sep 2026 10:16:36 -0600 Subject: [PATCH 25/46] docs: refine product and transition copy Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/index.mdx | 8 ++++---- .../docs/platform/transitioning-from-oz.mdx | 14 +++++++------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 10058c719..ab6acde6b 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -8,11 +8,11 @@ sidebar: --- import { VARS } from '@data/vars'; -Warp is an [open-source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that brings together terminal work, coding agents, and cloud automation. Use Warp to work interactively, run the Warp Agent from any terminal, automate recurring work in the cloud, and build team workflows with Warp Factories. +Warp is an [open-source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that brings together terminal work, coding agents, and cloud automation. With Warp, you can work in a desktop terminal, use the Warp Agent in a local checkout or from any terminal, automate background work in the cloud, and run repeatable team workflows with Warp Factories. ## Warp -Warp is the desktop terminal for running commands, editing code, and working with agents in a local checkout. +With the [Warp desktop terminal](/), you can run commands, edit code, and work with agents in a local checkout. * [Modern terminal editing](/terminal/editor/) - Edit commands, navigate blocks, manage tabs, and customize your terminal. * [Code](/code/overview/) - Review agent changes and edit files alongside your terminal. @@ -20,7 +20,7 @@ Warp is the desktop terminal for running commands, editing code, and working wit ## Warp Agent -The Warp Agent helps you investigate issues, edit code, run commands, and complete multi-step work. Use it in the Warp app or from the [Warp Agent CLI](/agents/cli/), which runs the same agent in any terminal. +The Warp Agent helps you investigate issues, edit code, run commands, and complete multi-step work. Use it in the Warp terminal or from the [Warp Agent CLI](/agents/cli/), which runs the same agent in any terminal. ## {VARS.WARP_AUTOMATION_PLATFORM} @@ -38,7 +38,7 @@ Warp Factories is available in Early Access. A factory turns incoming engineerin ## How the products work together -Use Warp and the Warp Agent for interactive development. Use the {VARS.WARP_AUTOMATION_PLATFORM} for background agents and shared cloud configuration. Use Warp Factories when your team needs a standing workflow to route, review, and improve work across repositories. +The Warp terminal and Warp Agent support interactive development in a local checkout. The {VARS.WARP_AUTOMATION_PLATFORM} runs background agents and provides shared cloud configuration. Warp Factories gives teams a standing workflow for routing, reviewing, and improving work across repositories. ## Related pages diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx index 810bc5325..9f81aafcc 100644 --- a/src/content/docs/platform/transitioning-from-oz.mdx +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -1,8 +1,8 @@ --- title: Transitioning from the {{WEB_APP}} description: >- - The {{WEB_APP}} will retire after Warp Factories reaches general availability. - Existing workflows, configuration, and tools remain available today. + Understand the upcoming {{WEB_APP}} retirement while current cloud-agent + workflows remain available. sidebar: label: "Transitioning from the {{WEB_APP}}" --- @@ -10,16 +10,16 @@ import { VARS } from '@data/vars'; The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing cloud agents, integrations, schedules, API keys, and the `oz` CLI remain available today, so you don't need to migrate immediately. -The {VARS.WARP_AUTOMATION_PLATFORM} remains the shared foundation for cloud agents. Warp Factories builds on that foundation for teams that need standing workflows with named agents, work intake, review stages, and measurement. +The {VARS.WARP_AUTOMATION_PLATFORM} remains the shared foundation for cloud agents. Warp Factories builds on that foundation for teams that need standing workflows that route work through specialized agents, add review stages, and show the progress of work. ## Choose the right entry point -* **Use the {VARS.WARP_AUTOMATION_PLATFORM}** - Configure standalone cloud agents, environments, schedules, integrations, and orchestration. Start with the [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) or [Cloud agents overview](/platform/). -* **Warp Factories** - Use a repeatable workflow that routes work through named agents and tracks it in one place. Start with the [Warp Factories overview](/factories/) or the [factory quickstart](/factories/quickstart/). +* **{VARS.WARP_AUTOMATION_PLATFORM}** - Configure standalone cloud agents, environments, schedules, integrations, and orchestration. Start with the [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) or [Cloud agents overview](/platform/). +* **Warp Factories** - Build a repeatable workflow that routes work through specialized agents and tracks it in one place. Start with the [Warp Factories overview](/factories/) or the [factory quickstart](/factories/quickstart/). ## What stays available -Existing workflows and configuration continue to work today: +These existing workflows and configuration continue to work today: * **Cloud agents** - Continue to run from existing events, schedules, integrations, APIs, and the CLI. * **Configuration** - Existing environments, integrations, schedules, API keys, and secrets remain available. @@ -27,7 +27,7 @@ Existing workflows and configuration continue to work today: ## What comes next -Migration actions, compatibility dates, and replacement destinations will be documented after product mapping is finalized. Until then, continue using the workflow that fits your work today. +Migration guidance will identify each replacement workflow and its compatibility dates as the transition progresses. Continue using the workflow that fits your work today. ## Related pages From eed44b1ba645c721a4a543e090e5613c84cfc73f Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 17 Sep 2026 11:24:42 -0600 Subject: [PATCH 26/46] docs: refine factories and platform navigation Co-Authored-By: Warp <agent@warp.dev> --- .../docs/factories/api-and-sdk/index.mdx | 2 +- .../troubleshooting/errors/index.mdx | 4 +-- .../api-and-sdk/troubleshooting/index.mdx | 14 ---------- .../docs/factories/developer-tools.mdx | 3 ++- src/content/docs/factories/factory-api.mdx | 16 +++++------ src/content/docs/index.mdx | 2 +- src/content/docs/platform/overview.mdx | 5 ++-- src/sidebar.ts | 27 +++++++++++-------- vercel.json | 10 +++++++ 9 files changed, 42 insertions(+), 41 deletions(-) diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx index 6774e5817..a95aeaafc 100644 --- a/src/content/docs/factories/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -10,7 +10,7 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Use the [factory API](/factories/factory-api/) to find a factory and send it new work. Use the {VARS.API_SDK_NAME} to start standalone cloud-agent runs, or to monitor, continue, and cancel any run after it starts. +Use the {VARS.API_SDK_NAME} to start standalone cloud-agent runs, or to monitor, continue, and cancel any run after it starts. To find a factory and send it new work, use the [Factory API](/factories/factory-api/). | API | Use it for | | --- | --- | diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx index 1ca4dac8b..ef969c79d 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx @@ -1,6 +1,6 @@ --- topic: factories -title: Errors Overview +title: API errors description: >- Reference for all error codes returned by the {{API_SDK_NAME}}. Each error includes an HTTP status, machine-readable code, and actionable resolution @@ -8,7 +8,7 @@ description: >- --- import { VARS } from '@data/vars'; -When the {VARS.API_SDK_NAME} encounters an error, it returns a structured JSON response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807). Every error response includes a machine-readable error code, a human-readable message, and metadata to help you diagnose and resolve the issue. +When the {VARS.API_SDK_NAME} encounters an error, it returns a structured JSON response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807). Every error response includes a machine-readable error code, HTTP status, human-readable message, and resolution details. --- diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx index 29101c02a..e69de29bb 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx @@ -1,14 +0,0 @@ ---- -topic: factories -title: API Troubleshooting -description: >- - Troubleshooting resources for the {{API_SDK_NAME}}, including a full reference - for all platform error codes. ---- -import { VARS } from '@data/vars'; - -When the {VARS.API_SDK_NAME} encounters an error, it returns a structured response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807) with a machine-readable error code, HTTP status, and actionable resolution steps. - -## Resources - -* [**Errors**](/factories/api-and-sdk/troubleshooting/errors/) — Full reference for all API error codes, including causes, example responses, and resolution steps diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx index 22c014a37..8e92a677f 100644 --- a/src/content/docs/factories/developer-tools.mdx +++ b/src/content/docs/factories/developer-tools.mdx @@ -19,9 +19,10 @@ Warp Factories provides programmatic interfaces for sending work to a factory, i * **[Webhooks](/factories/webhooks/)** - Receive events from systems that can send JSON and route matching deliveries into factory automations. ## Use the API and SDK + Use the API and SDK for typed requests, retries, and error handling. Start with the [API and SDK quickstart](/factories/api-and-sdk/quickstart/) to create and inspect a run, or use the [Sentry monitoring example](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) to connect an external event source. -For request errors, see [API troubleshooting](/factories/api-and-sdk/troubleshooting/) and the [API error reference](/factories/api-and-sdk/troubleshooting/errors/). +For request errors, see [API errors](/factories/api-and-sdk/troubleshooting/errors/). ## Related pages diff --git a/src/content/docs/factories/factory-api.mdx b/src/content/docs/factories/factory-api.mdx index 40a03c247..6f0837e50 100644 --- a/src/content/docs/factories/factory-api.mdx +++ b/src/content/docs/factories/factory-api.mdx @@ -1,14 +1,14 @@ --- -title: Use the factory API +title: Use the Factory API description: >- - Discover factories and dispatch tasks by UID with the public factory API, + Discover factories and dispatch tasks by UID with the public Factory API, without learning the foreman agent's internals. sidebar: label: "Factory API" --- import { VARS } from '@data/vars'; -Use the factory API to find a factory and start work from a custom integration without managing agent details. Build it into a chat bot, script, or service for any tool Warp doesn't connect to directly. +Use the Factory API to find a factory and start work from a custom integration without managing agent details. Build it into a chat bot, script, or service for any tool Warp doesn't connect to directly. :::note Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. @@ -22,14 +22,14 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [Agent API](/factories/api-and-sdk/) you'd use for any run. -## When to use the factory API vs the Agent API +## When to use the Factory API vs the Agent API -Use the factory API to find or start work on a factory. Use the Agent API for everything else - a standalone cloud agent, run management, or orchestration. +Use the Factory API to find or start work on a factory. Use the Agent API for everything else - a standalone cloud agent, run management, or orchestration. | Task | Recommended API | | --- | --- | -| Find a factory by name before dispatching to it | factory API - `GET /factory?search=` | -| Start a new task on a factory | factory API - `POST /factory/{uid}/runs` | +| Find a factory by name before dispatching to it | Factory API - `GET /factory?search=` | +| Start a new task on a factory | Factory API - `POST /factory/{uid}/runs` | | Continue, monitor, or cancel a run (factory or standalone) | Agent API - `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` | | Run a standalone cloud agent with no factory involved | Agent API - `POST /agent/run` | | Build a multi-agent orchestration | Agent API - see [multi-agent orchestration](/platform/orchestration/) | @@ -123,7 +123,7 @@ See [key endpoints](/factories/api-and-sdk/#key-endpoints) for the full set of r ## Related pages -* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the factory API alongside Slack, GitHub, and Factory MCP. +* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the Factory API alongside Slack, GitHub, and Factory MCP. * [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) - A worked example that discovers a factory and dispatches and continues a task from a custom chat integration. * [Factory MCP](/factories/factory-mcp/) - Connect a local coding agent to a factory instead of calling the REST API directly. * [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying Agent API. diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index ab6acde6b..839a54952 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -38,7 +38,7 @@ Warp Factories is available in Early Access. A factory turns incoming engineerin ## How the products work together -The Warp terminal and Warp Agent support interactive development in a local checkout. The {VARS.WARP_AUTOMATION_PLATFORM} runs background agents and provides shared cloud configuration. Warp Factories gives teams a standing workflow for routing, reviewing, and improving work across repositories. +Start and steer interactive work in the Warp terminal with the Warp Agent. For work that starts from a schedule, integration, or API, the {VARS.WARP_AUTOMATION_PLATFORM} runs agents in the cloud. Warp Factories builds on the {VARS.WARP_AUTOMATION_PLATFORM} to turn incoming team work into a repeatable workflow with specialized agents and review stages. ## Related pages diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index 06257e7d2..0230b4434 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -9,13 +9,12 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -[Cloud agents](/platform/) run on the {VARS.WARP_AUTOMATION_PLATFORM}. You define the work (a prompt or a skill) and what starts it, and the platform runs the agent and records what it did. For example, an agent can triage each new issue as it's filed, or start fixing a build the moment CI fails. +[Cloud agents](/platform/) run on the {VARS.WARP_AUTOMATION_PLATFORM}. You define a task and its trigger. The {VARS.WARP_AUTOMATION_PLATFORM} runs the agent and records the results. For example, an agent can triage each new issue as it's filed, or start fixing a build the moment CI fails. If you're new to cloud agents, the [Cloud agents quickstart](/platform/quickstart/) gets you to your first run in about ten minutes. :::note -**The {VARS.WARP_AUTOMATION_PLATFORM} is the current name.** Your existing integrations, API keys, scheduled agents, and scripts keep working exactly as before — nothing to migrate. -The `oz` CLI and the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> retain their legacy names during the transition. See [Transitioning](/platform/transitioning-from-oz/) for the current guidance. +The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing cloud-agent workflows remain available today, so you don't need to migrate immediately. The `oz` CLI retains its legacy name during the transition. See [Transitioning from Oz](/platform/transitioning-from-oz/) for the current guidance. ::: <VideoEmbed url="https://youtu.be/poLkJhO7fdo" title={`${VARS.WARP_AUTOMATION_PLATFORM} cloud agents overview video`} /> diff --git a/src/sidebar.ts b/src/sidebar.ts index 3b0bfb07d..7c7f317e4 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -30,7 +30,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // The root product overview remains in the Terminal topic until // the GA navigation change adds a separate Terminal landing page. { label: 'Warp products', link: '/' }, - { slug: 'quickstart', label: 'Warp quickstart' }, + { slug: 'quickstart', label: 'Quickstart' }, 'getting-started/quickstart/installation-and-setup', 'getting-started/quickstart/coding-in-warp', 'getting-started/quickstart/customizing-warp', @@ -453,7 +453,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/api-and-sdk', label: VARS.API_SDK_NAME }, { label: 'API reference', link: '/api' }, { slug: 'factories/api-and-sdk/demo-sentry-monitoring-with-sdk', label: 'Sentry monitoring with the SDK' }, - { slug: 'factories/api-and-sdk/troubleshooting', label: 'API troubleshooting' }, { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'API errors' }, { slug: 'factories/factory-mcp', label: 'Factory MCP' }, { @@ -473,14 +472,20 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/deployment-patterns', label: 'Deployment patterns' }, { slug: 'factories/warp-hosting', label: 'Warp-hosted execution' }, { slug: 'factories/runners', label: 'Runners' }, - { slug: 'factories/self-hosting', label: 'Managed self-hosting' }, - { slug: 'factories/self-hosting/quickstart', label: 'Self-hosting quickstart' }, - { slug: 'factories/self-hosting/managed-docker', label: 'Docker backend' }, - { slug: 'factories/self-hosting/managed-kubernetes', label: 'Kubernetes backend' }, - { slug: 'factories/self-hosting/managed-direct', label: 'Direct backend' }, - 'factories/self-hosting/monitoring', - { slug: 'factories/self-hosting/reference', label: 'Worker reference' }, - 'factories/self-hosting/troubleshooting', + { + label: 'Managed self-hosting', + collapsed: false, + items: [ + { slug: 'factories/self-hosting', label: 'Overview' }, + { slug: 'factories/self-hosting/quickstart', label: 'Quickstart' }, + { slug: 'factories/self-hosting/managed-docker', label: 'Docker backend' }, + { slug: 'factories/self-hosting/managed-kubernetes', label: 'Kubernetes backend' }, + { slug: 'factories/self-hosting/managed-direct', label: 'Direct backend' }, + 'factories/self-hosting/monitoring', + { slug: 'factories/self-hosting/reference', label: 'Worker reference' }, + 'factories/self-hosting/troubleshooting', + ], + }, ], }, { @@ -537,7 +542,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ items: [ { slug: 'platform', label: 'Overview' }, { slug: 'platform/quickstart', label: 'Quickstart' }, - { slug: 'platform/transitioning-from-oz', label: 'Transitioning' }, + { slug: 'platform/transitioning-from-oz', label: 'Transitioning from Oz' }, { // Runtime (which agent executes the run) is kept separate from // configuration (how any run is set up) -- HYC review, 8/14. diff --git a/vercel.json b/vercel.json index 75bfc36ba..995cb5a8e 100644 --- a/vercel.json +++ b/vercel.json @@ -6627,6 +6627,16 @@ "destination": "/factories/api-and-sdk/", "statusCode": 308 }, + { + "source": "/reference/api-and-sdk/troubleshooting(/?)", + "destination": "/factories/api-and-sdk/troubleshooting/errors/", + "statusCode": 308 + }, + { + "source": "/factories/api-and-sdk/troubleshooting(/?)", + "destination": "/factories/api-and-sdk/troubleshooting/errors/", + "statusCode": 308 + }, { "source": "/reference/api-and-sdk/:path*", "destination": "/factories/api-and-sdk/:path*", From d90b662bc8b65a74a530cdbeea887b7072292030 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 17 Sep 2026 12:35:58 -0600 Subject: [PATCH 27/46] docs: remove empty API troubleshooting page Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/index.mdx deleted file mode 100644 index e69de29bb..000000000 From c6cfc0fcb50443bf6b1b3dbc20af7912fe6f7523 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 17 Sep 2026 13:17:16 -0600 Subject: [PATCH 28/46] fix: parse review findings with brace syntax Co-Authored-By: Warp <agent@warp.dev> --- .../test_verify_review_signal.py | 11 +++++++ .../verify_review_signal.py | 32 +++++++++---------- 2 files changed, 26 insertions(+), 17 deletions(-) diff --git a/.agents/skills/doc_quality_policy/test_verify_review_signal.py b/.agents/skills/doc_quality_policy/test_verify_review_signal.py index 9d02c1063..b333bdb37 100644 --- a/.agents/skills/doc_quality_policy/test_verify_review_signal.py +++ b/.agents/skills/doc_quality_policy/test_verify_review_signal.py @@ -77,6 +77,17 @@ def test_escaped_action_output_signal_passes(self): with mock.patch.object(vrs.cpc, "_fetch_reviews", return_value=[GOOD_REVIEW]): problems = vrs.check_review_signal("o/r", "1", "sha1", output) self.assertEqual(problems, []) + def test_signal_with_braces_in_an_actionable_finding_passes(self): + output = ( + '[SIGNAL:pr-review] {"pr":"1","head_sha":"sha1",' + '"reviewer_login":"github-actions[bot]","verdict":"Approve with nits",' + '"critical":0,"important":0,"suggestions":1,"nits":0,' + '"actionable_findings":["`factory-api.mdx:20` — Check ' + '`POST /factory/{uid}/runs`."]}' + ) + with mock.patch.object(vrs.cpc, "_fetch_reviews", return_value=[{**GOOD_REVIEW, "body": output}]): + problems = vrs.check_review_signal("o/r", "1", "sha1", output) + self.assertEqual(problems, []) def test_distinct_signals_fail(self): different_signal = GOOD_OUTPUT.replace('"Approve"', '"Approve with nits"') diff --git a/.agents/skills/doc_quality_policy/verify_review_signal.py b/.agents/skills/doc_quality_policy/verify_review_signal.py index f38866f18..626664aec 100644 --- a/.agents/skills/doc_quality_policy/verify_review_signal.py +++ b/.agents/skills/doc_quality_policy/verify_review_signal.py @@ -5,7 +5,6 @@ import argparse import importlib.util import json -import re import sys from pathlib import Path from typing import Dict, List, Optional, Tuple @@ -16,7 +15,7 @@ sys.modules[_spec.name] = cpc _spec.loader.exec_module(cpc) -_SIGNAL_RE = re.compile(r"\[SIGNAL:pr-review\]\s*(\{.*?\})", re.DOTALL) +_SIGNAL_PREFIX = "[SIGNAL:pr-review]" _PASSING_VERDICTS = {"approve", "approve with nits", "approve_with_nits"} @@ -25,25 +24,24 @@ def _parse_signal( pr_number: Optional[str] = None, head_sha: Optional[str] = None, ) -> Tuple[Optional[Dict[str, object]], List[str]]: - matches = _SIGNAL_RE.findall(text) - if not matches: + occurrences = text.count(_SIGNAL_PREFIX) + if not occurrences: return None, ["expected exactly one [SIGNAL:pr-review] record, found 0"] unique_signals = {} - for match in matches: - try: - signal = json.loads(match) - except json.JSONDecodeError as original_error: + offset = 0 + while True: + marker = text.find(_SIGNAL_PREFIX, offset) + if marker == -1: + break + offset = marker + len(_SIGNAL_PREFIX) + candidate = text[offset:].lstrip() + signal = None + for payload in (candidate, candidate.replace('\\"', '"')): try: - # The GitHub Action can serialize its text output once more, - # leaving an otherwise valid object in the form - # {\"key\":\"value\"}. Decode that wrapper only after direct - # JSON parsing has failed. - signal = json.loads(match.replace('\\"', '"')) + signal, _ = json.JSONDecoder().raw_decode(payload) + break except json.JSONDecodeError: - # Agent output includes the skill's marker examples and prior - # review transcripts. Ignore malformed candidates and require - # a valid, current-head record below. continue if not isinstance(signal, dict): continue @@ -57,7 +55,7 @@ def _parse_signal( if len(signals) != 1: return None, [ "expected one valid [SIGNAL:pr-review] record for the current PR head, " - f"found {len(signals)} across {len(matches)} occurrences" + f"found {len(signals)} across {occurrences} occurrences" ] return signals[0], [] From b4c5967f78e6d45a07c50c54e10d1ab70220a298 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 17 Sep 2026 13:56:12 -0600 Subject: [PATCH 29/46] docs: organize sidebar entry points Co-Authored-By: Warp <agent@warp.dev> --- src/sidebar.ts | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/src/sidebar.ts b/src/sidebar.ts index 7c7f317e4..75d75298d 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -245,10 +245,9 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ icon: 'puzzle', items: [ { - label: 'Agents', + label: 'Overview', items: [ { slug: 'agents', label: 'Overview' }, - 'agents/getting-started/faqs', ], }, { @@ -385,6 +384,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agents/agent-memory', label: 'Agent Memory' }, ], }, + { slug: 'agents/getting-started/faqs', label: 'Agent FAQs' }, ], }, { @@ -403,10 +403,15 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // next door, since the underlying concepts are the same. items: [ { - label: 'Factories', + label: 'Overview', items: [ { slug: 'factories', label: 'Overview' }, { slug: 'factories/how-factories-work', label: 'How Factories work' }, + ], + }, + { + label: 'Get started', + items: [ { slug: 'factories/quickstart', label: 'Quickstart' }, ], }, @@ -751,13 +756,17 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ icon: 'setting', items: [ { - label: 'Getting started', + label: 'Overview', items: [ { slug: 'enterprise', label: 'Overview' }, - { slug: 'enterprise/getting-started/quickstart', label: 'Quick start' }, + ], + }, + { + label: 'Get started', + items: [ + { slug: 'enterprise/getting-started/quickstart', label: 'Quickstart' }, { slug: 'enterprise/getting-started/getting-started-enterprise', label: 'Getting started for admins' }, { slug: 'enterprise/getting-started/getting-started-developers', label: 'Getting started for developers' }, - { slug: 'enterprise/getting-started/faq', label: 'FAQ' }, ], }, { @@ -793,6 +802,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ 'enterprise/support-and-resources/billing', { slug: 'enterprise/support-and-resources/troubleshooting-login', label: 'Troubleshooting login' }, { slug: 'enterprise/support-and-resources/feedback-and-feature-requests', label: 'Feedback and feature requests' }, + { slug: 'enterprise/getting-started/faq', label: 'FAQ' }, ], }, ], @@ -803,7 +813,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ link: '/guides/', icon: 'rocket', items: [ - { slug: 'guides', label: 'Guides' }, + { slug: 'guides', label: 'Overview' }, { label: 'Getting started', items: [ From 77f6a0286946212b835693b411108b8845440fea Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 17 Sep 2026 14:02:13 -0600 Subject: [PATCH 30/46] docs: resolve terminology and redirect review Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/factories/api-and-sdk/index.mdx | 4 ++-- src/content/docs/factories/factory-api.mdx | 16 ++++++++-------- src/content/docs/platform/overview.mdx | 2 +- vercel.json | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx index a95aeaafc..b1f54b026 100644 --- a/src/content/docs/factories/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -10,11 +10,11 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Use the {VARS.API_SDK_NAME} to start standalone cloud-agent runs, or to monitor, continue, and cancel any run after it starts. To find a factory and send it new work, use the [Factory API](/factories/factory-api/). +Use the {VARS.API_SDK_NAME} to start standalone cloud-agent runs, or to monitor, continue, and cancel any run after it starts. To find a factory and send it new work, use the [factory API](/factories/factory-api/). | API | Use it for | | --- | --- | -| **Factory API** | Find a factory and dispatch new work to its foreman. | +| **factory API** | Find a factory and dispatch new work to its foreman. | | **{VARS.API_SDK_NAME}** | Start standalone cloud-agent runs, and manage factory or standalone runs after they begin. | :::note diff --git a/src/content/docs/factories/factory-api.mdx b/src/content/docs/factories/factory-api.mdx index 6f0837e50..40a03c247 100644 --- a/src/content/docs/factories/factory-api.mdx +++ b/src/content/docs/factories/factory-api.mdx @@ -1,14 +1,14 @@ --- -title: Use the Factory API +title: Use the factory API description: >- - Discover factories and dispatch tasks by UID with the public Factory API, + Discover factories and dispatch tasks by UID with the public factory API, without learning the foreman agent's internals. sidebar: label: "Factory API" --- import { VARS } from '@data/vars'; -Use the Factory API to find a factory and start work from a custom integration without managing agent details. Build it into a chat bot, script, or service for any tool Warp doesn't connect to directly. +Use the factory API to find a factory and start work from a custom integration without managing agent details. Build it into a chat bot, script, or service for any tool Warp doesn't connect to directly. :::note Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. @@ -22,14 +22,14 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [Agent API](/factories/api-and-sdk/) you'd use for any run. -## When to use the Factory API vs the Agent API +## When to use the factory API vs the Agent API -Use the Factory API to find or start work on a factory. Use the Agent API for everything else - a standalone cloud agent, run management, or orchestration. +Use the factory API to find or start work on a factory. Use the Agent API for everything else - a standalone cloud agent, run management, or orchestration. | Task | Recommended API | | --- | --- | -| Find a factory by name before dispatching to it | Factory API - `GET /factory?search=` | -| Start a new task on a factory | Factory API - `POST /factory/{uid}/runs` | +| Find a factory by name before dispatching to it | factory API - `GET /factory?search=` | +| Start a new task on a factory | factory API - `POST /factory/{uid}/runs` | | Continue, monitor, or cancel a run (factory or standalone) | Agent API - `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` | | Run a standalone cloud agent with no factory involved | Agent API - `POST /agent/run` | | Build a multi-agent orchestration | Agent API - see [multi-agent orchestration](/platform/orchestration/) | @@ -123,7 +123,7 @@ See [key endpoints](/factories/api-and-sdk/#key-endpoints) for the full set of r ## Related pages -* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the Factory API alongside Slack, GitHub, and Factory MCP. +* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the factory API alongside Slack, GitHub, and Factory MCP. * [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) - A worked example that discovers a factory and dispatches and continues a task from a custom chat integration. * [Factory MCP](/factories/factory-mcp/) - Connect a local coding agent to a factory instead of calling the REST API directly. * [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying Agent API. diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index 0230b4434..4f037a210 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -14,7 +14,7 @@ import { VARS } from '@data/vars'; If you're new to cloud agents, the [Cloud agents quickstart](/platform/quickstart/) gets you to your first run in about ten minutes. :::note -The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing cloud-agent workflows remain available today, so you don't need to migrate immediately. The `oz` CLI retains its legacy name during the transition. See [Transitioning from Oz](/platform/transitioning-from-oz/) for the current guidance. +The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing cloud-agent workflows remain available today, so you don't need to migrate immediately. The `oz` CLI retains its legacy name during the transition. See [Transitioning from the {VARS.WEB_APP}](/platform/transitioning-from-oz/) for the current guidance. ::: <VideoEmbed url="https://youtu.be/poLkJhO7fdo" title={`${VARS.WARP_AUTOMATION_PLATFORM} cloud agents overview video`} /> diff --git a/vercel.json b/vercel.json index 995cb5a8e..605a7bf9e 100644 --- a/vercel.json +++ b/vercel.json @@ -1549,7 +1549,7 @@ }, { "source": "/agent-platform/platform/deployment-patterns(/?)", - "destination": "/platform/deployment-patterns/", + "destination": "/factories/deployment-patterns/", "statusCode": 308 }, { From 0d5b2907c307be0a8dc42c91564f664e59caafb1 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 17 Sep 2026 14:28:40 -0600 Subject: [PATCH 31/46] docs: simplify sidebar overview sections Co-Authored-By: Warp <agent@warp.dev> --- src/sidebar.ts | 25 +++++-------------------- 1 file changed, 5 insertions(+), 20 deletions(-) diff --git a/src/sidebar.ts b/src/sidebar.ts index 75d75298d..918f8bdf1 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -244,12 +244,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ link: '/agents/', icon: 'puzzle', items: [ - { - label: 'Overview', - items: [ - { slug: 'agents', label: 'Overview' }, - ], - }, + { slug: 'agents', label: 'Overview' }, { label: 'Warp Agents', items: [ @@ -402,19 +397,9 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // sidebar. Two of these deliberately mirror the Automation Platform tab // next door, since the underlying concepts are the same. items: [ - { - label: 'Overview', - items: [ - { slug: 'factories', label: 'Overview' }, - { slug: 'factories/how-factories-work', label: 'How Factories work' }, - ], - }, - { - label: 'Get started', - items: [ - { slug: 'factories/quickstart', label: 'Quickstart' }, - ], - }, + { slug: 'factories', label: 'Overview' }, + { slug: 'factories/how-factories-work', label: 'How Factories work' }, + { slug: 'factories/quickstart', label: 'Quickstart' }, { // Parallel to 'Agent configuration' in the Automation Platform tab. // Scoped to the factory itself: who runs the work, how it is defined, @@ -762,7 +747,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ ], }, { - label: 'Get started', + label: 'Getting started', items: [ { slug: 'enterprise/getting-started/quickstart', label: 'Quickstart' }, { slug: 'enterprise/getting-started/getting-started-enterprise', label: 'Getting started for admins' }, From ef3723eb735f6f3606c431db5c620a1cdb3cc92d Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Thu, 17 Sep 2026 14:34:38 -0600 Subject: [PATCH 32/46] docs: address sidebar navigation nits Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/index.mdx | 2 +- src/sidebar.ts | 40 +++++++++++++++++++------------------- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 839a54952..877aeead4 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -12,7 +12,7 @@ Warp is an [open-source](https://github.com/warpdotdev/warp) **Agentic Developme ## Warp -With the [Warp desktop terminal](/), you can run commands, edit code, and work with agents in a local checkout. +With the Warp desktop terminal, you can run commands, edit code, and work with agents in a local checkout. * [Modern terminal editing](/terminal/editor/) - Edit commands, navigate blocks, manage tabs, and customize your terminal. * [Code](/code/overview/) - Review agent changes and edit files alongside your terminal. diff --git a/src/sidebar.ts b/src/sidebar.ts index 918f8bdf1..4f9182ec9 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -345,23 +345,23 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agents/cli/reference', label: 'CLI reference' }, ], }, - { - label: `${VARS.WARP_AGENT_CLI} (legacy)`, - collapsed: true, - items: [ - { slug: 'agents/cli/oz-cli', label: 'Overview' }, - { slug: 'agents/cli/oz-cli/quickstart', label: 'Quickstart' }, - { slug: 'agents/cli/oz-cli/api-keys', label: 'API keys' }, - { slug: 'agents/cli/oz-cli/agent-profiles', label: 'Agent profiles' }, - { slug: 'agents/cli/oz-cli/mcp-servers', label: 'MCP servers' }, - { slug: 'agents/cli/oz-cli/skills', label: 'Skills' }, - { slug: 'agents/cli/oz-cli/warp-drive', label: 'Warp Drive context' }, - { slug: 'agents/cli/oz-cli/integration-setup', label: 'Integration setup' }, - { slug: 'agents/cli/oz-cli/artifacts', label: 'Artifacts' }, - { slug: 'agents/cli/oz-cli/federate', label: 'Federated identity' }, - 'agents/cli/oz-cli/troubleshooting', - ], - }, + { + label: `${VARS.WARP_AGENT_CLI} (legacy)`, + collapsed: true, + items: [ + { slug: 'agents/cli/oz-cli', label: 'Overview' }, + { slug: 'agents/cli/oz-cli/quickstart', label: 'Quickstart' }, + { slug: 'agents/cli/oz-cli/api-keys', label: 'API keys' }, + { slug: 'agents/cli/oz-cli/agent-profiles', label: 'Agent profiles' }, + { slug: 'agents/cli/oz-cli/mcp-servers', label: 'MCP servers' }, + { slug: 'agents/cli/oz-cli/skills', label: 'Skills' }, + { slug: 'agents/cli/oz-cli/warp-drive', label: 'Warp Drive context' }, + { slug: 'agents/cli/oz-cli/integration-setup', label: 'Integration setup' }, + { slug: 'agents/cli/oz-cli/artifacts', label: 'Artifacts' }, + { slug: 'agents/cli/oz-cli/federate', label: 'Federated identity' }, + 'agents/cli/oz-cli/troubleshooting', + ], + }, { label: 'Third-Party CLI Agents', items: [ @@ -422,9 +422,9 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // Integrations subgroup, which would have rendered as // Integrations > Integrations > Slack. // - // 'Connect your factory' leads because it is the overview for this - // group. The direct developer interfaces live in the Developer tools - // group rather than alongside third-party service integrations. + // 'Connect your factory' leads because it is the overview for this + // group. The direct developer interfaces live in the Developer tools + // group rather than alongside third-party service integrations. label: 'Integrations', items: [ { slug: 'factories/connect-your-factory', label: 'Connect your factory' }, From 985283d6829dabe8703b7ed4ce422647cb5253b7 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 18 Sep 2026 10:01:05 -0600 Subject: [PATCH 33/46] docs: clarify factory self-hosting guidance Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/factories/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index abbdd88ac..318e889de 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -55,7 +55,7 @@ Warp Factories is designed for engineering teams with repeatable work that exten * **Integrations and the Factory MCP** - Work flows in from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/), plus [custom webhooks](/factories/webhooks/), direct runs, and schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. * **Model and harness choice** - Each agent can use a different model and [supported harness](/platform/harnesses/), including the Warp Agent, Claude Code, and Codex. * **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs, [Benchmarks](/factories/benchmarks/) compare fixed tasks across configurations, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into follow-up work the factory proposes for review. -* **Infrastructure control** - Run on Warp-hosted infrastructure, or self-host execution on an eligible Enterprise plan. Teams can also connect supported inference providers and scope secrets. See [infrastructure and security](/factories/infrastructure-and-security/) for the available controls. +* **Infrastructure control** - Choose Warp-hosted or managed self-hosted execution on an eligible Enterprise plan. The [infrastructure and security](/factories/infrastructure-and-security/) page compares execution models and links to the self-hosting setup path, as well as available inference and credential controls. ## How Warp Factories relates to other Warp products From 2bba5e24b9e43178b15bb98bea7a691e271ec37c Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 18 Sep 2026 12:23:32 -0600 Subject: [PATCH 34/46] docs: reconcile factories restructure with main Co-Authored-By: Warp <agent@warp.dev> --- .../test_agent_docs_review_workflow.py | 5 ++-- .../test_verify_review_signal.py | 1 + .github/workflows/agent-docs-review.yml | 2 +- .../docs/factories/deployment-patterns.mdx | 13 ++------- .../docs/factories/how-factories-work.mdx | 2 +- src/content/docs/factories/index.mdx | 2 +- .../factories/infrastructure-and-security.mdx | 4 +-- src/content/docs/platform/architecture.mdx | 28 +++++++++---------- .../docs/platform/execution-security.mdx | 2 +- src/sidebar.ts | 4 ++- vercel.json | 14 +++++----- 11 files changed, 37 insertions(+), 40 deletions(-) diff --git a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py index 230d5f826..cbb225c65 100644 --- a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py +++ b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py @@ -33,6 +33,7 @@ def test_all_review_findings_must_supply_actionable_details(self): self.assertIn("actionable_findings", self.workflow) self.assertIn("critical, important, suggestion, or nit", self.workflow) self.assertIn("file and line or quoted text", self.workflow) + def test_review_signal_is_passed_through_a_file(self): self.assertIn('oz "${args[@]}" > /tmp/agent-output.txt', self.workflow) self.assertIn("--agent-output /tmp/agent-output.txt", self.workflow) @@ -41,10 +42,10 @@ def test_review_signal_is_passed_through_a_file(self): "AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}", self.workflow ) - def test_review_uses_a_pinned_signed_oz_package(self): + def test_review_uses_a_signed_oz_package(self): self.assertIn("0913165C78D5B7A41B42AC657FF7AB39D60F803F", self.workflow) self.assertIn("signed-by=/etc/apt/keyrings/warpdotdev.gpg", self.workflow) - self.assertIn("oz-stable=0.2026.09.09.08.26.stable.02", self.workflow) + self.assertIn("sudo apt-get install -y oz-stable", self.workflow) if __name__ == "__main__": diff --git a/.agents/skills/doc_quality_policy/test_verify_review_signal.py b/.agents/skills/doc_quality_policy/test_verify_review_signal.py index b333bdb37..be53282cc 100644 --- a/.agents/skills/doc_quality_policy/test_verify_review_signal.py +++ b/.agents/skills/doc_quality_policy/test_verify_review_signal.py @@ -77,6 +77,7 @@ def test_escaped_action_output_signal_passes(self): with mock.patch.object(vrs.cpc, "_fetch_reviews", return_value=[GOOD_REVIEW]): problems = vrs.check_review_signal("o/r", "1", "sha1", output) self.assertEqual(problems, []) + def test_signal_with_braces_in_an_actionable_finding_passes(self): output = ( '[SIGNAL:pr-review] {"pr":"1","head_sha":"sha1",' diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 2c88e2a75..235912604 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -56,7 +56,7 @@ jobs: deb [arch=amd64 signed-by=/etc/apt/keyrings/warpdotdev.gpg] https://releases.warp.dev/linux/deb stable main EOF sudo apt-get update - sudo apt-get install -y oz-stable=0.2026.09.09.08.26.stable.02 + sudo apt-get install -y oz-stable PROMPT="$(cat <<'EOF' Run the review-docs-pr skill against warpdotdev/docs PR #${{ github.event.pull_request.number }} at head SHA ${{ github.event.pull_request.head.sha }}. This PR carries the warpy-factory agent diff --git a/src/content/docs/factories/deployment-patterns.mdx b/src/content/docs/factories/deployment-patterns.mdx index f993a5e3c..03a47882f 100644 --- a/src/content/docs/factories/deployment-patterns.mdx +++ b/src/content/docs/factories/deployment-patterns.mdx @@ -22,13 +22,6 @@ Choose an execution model for your factory based on where its code must run and Both factory options use the same [factory definition](/factories/factory-as-code/), [runners](/factories/runners/), and [factory dashboard](/factories/factory-dashboard/). The execution host changes the location of checkout, command execution, and the sandbox filesystem. ---- - -## Standalone CLI-only agents - -This is not a factory deployment model. Use it when you already have a system that schedules work and need to run standalone agents from CI, developer infrastructure, or an internal orchestrator. See [Unmanaged execution](/platform/unmanaged-execution/) for the Platform reference. - ---- ## Warp-hosted execution @@ -49,13 +42,13 @@ See the [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-life * You want the simplest path to reproducible, scalable cloud execution. * You want to run many tasks in parallel without building your own sandboxing and scaling layer. -* You want a consistent “production” setup with standardized environments and centralized configuration. +* You want a consistent "production" setup with standardized environments and centralized configuration. ### Common ways to trigger * **First-party integrations (Slack, Linear, etc.)** that create tasks automatically from external events. * **[Scheduled agents](/platform/triggers/scheduled-agents/)** for recurring work (cron-like automation). -* **Custom triggers** from your own systems using Warp’s API/SDK. +* **Custom triggers** from your own systems using Warp's API/SDK. * **On-demand cloud jobs** using CLI commands like `oz agent run-cloud`. ### Example recipe: daily dead-code cleanup @@ -96,7 +89,7 @@ Think of managed self-hosting as **customer-hosted execution with Warp-hosted or Self-hosting has two architectures that differ on **who orchestrates agent runs** (both keep code and execution on your infrastructure): * **[Managed](/factories/self-hosting/#managed-architecture)** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates. You run the `oz-agent-worker` daemon; the {VARS.WARP_AUTOMATION_PLATFORM} routes runs to it from Slack, Linear, schedules, the API, or `oz agent run-cloud`. Tasks execute in Docker containers, Kubernetes Jobs, or directly on the host. -* **[Unmanaged](/platform/unmanaged-execution/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment for standalone-agent work. Route factory work to a managed worker. +* **[Unmanaged](/platform/unmanaged-execution/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment for standalone-agent work. To route factory work to a worker instead, use the managed architecture above. Why teams choose self-hosted execution: diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index d481c0181..9f85f34fb 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -26,7 +26,7 @@ The diagram's components, from intake to improvement: * **Foreman and stage agents** - The foreman holds one conversation per work item and dispatches the Triage, Spec, Implement, and Review agents as the work needs them. See [factory agents](/factories/factory-agents/) and the stages below. * **Human handoff** - The factory opens a pull request with evidence, updates the original work item, and you review and merge. * **Factory definition** - Version-controlled agents, automations, runners, scorers, skills, and webhooks define the factory, either Warp-managed or in a GitHub repository your team owns. See [definitions as code](/factories/factory-as-code/). -* **Execution** - Every stage runs as a cloud agent run on Warp-hosted or [self-hosted](/platform/self-hosting/) compute, with the workspace from the factory's repositories and each stage's configured model and [harness](/platform/harnesses/). +* **Execution** - Every stage runs as a cloud agent run on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, with the workspace from the factory's repositories and each stage's configured model and [harness](/platform/harnesses/). * **Factory dashboard** - Metrics, work items by stage, and runs and costs. See the [factory dashboard](/factories/factory-dashboard/). * **Measure and improve** - [Scorers](/factories/measure-and-improve/) classify completed runs, benchmarks compare configurations, and self-improvement turns repeat failures into follow-up pull requests for your review. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 318e889de..01e21caea 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -11,9 +11,9 @@ import VideoEmbed from '@components/VideoEmbed.astro'; :::note Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. If your team already has access, sign in to the <a href={VARS.FACTORY_WEB_APP_URL}>{VARS.FACTORY_WEB_APP}</a>. +::: The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing workflows remain available today. See [Transitioning from the {VARS.WEB_APP}](/platform/transitioning-from-oz/) for the current transition guidance. -::: A software factory uses a coordinated fleet of agents to take in requests, manage them from triage through review, and turn a growing backlog into mergeable pull requests. Your team stays in the loop to approve specifications and merge each pull request. diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index bd058ab91..a75d50504 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -27,7 +27,7 @@ flowchart LR C --> D["Warp-managed storage"] ``` -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](/factories/deployment-patterns/) and [self-hosting security and networking](/platform/execution-security/) for the broader data model. +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](/factories/deployment-patterns/) and [execution security](/platform/execution-security/) for the broader data model. 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. @@ -35,7 +35,7 @@ The diagram below maps those boundaries for self-hosted execution; factory runs ## 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](/factories/runners/) for the available compute options. +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). The workspace itself — repositories, setup commands, and secrets — comes from the factory's [definition](/factories/factory-as-code/). See the [runner reference](/factories/runners/) for the available compute options. Declare runners as `runners/*.yaml` files. Every agent inherits `agentDefaults.runner`, and an agent or automation can override it. A self-hosted runner must match the worker's operating system and architecture. Warp provisions hosted runners within your plan limits; your team provisions and operates self-hosted compute. diff --git a/src/content/docs/platform/architecture.mdx b/src/content/docs/platform/architecture.mdx index 579efcc4c..26e455d24 100644 --- a/src/content/docs/platform/architecture.mdx +++ b/src/content/docs/platform/architecture.mdx @@ -6,7 +6,7 @@ description: >- --- import { VARS } from '@data/vars'; -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 and [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) change where specific work happens. +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. [Managed self-hosting](/factories/self-hosting/) and [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) change where specific work happens. ## Stack overview @@ -15,11 +15,11 @@ The platform has five layers: clients, the Warp-operated control plane that coor ![Warp stack overview diagram showing clients, the Warp control plane, the data plane, Warp-hosted and customer-hosted execution planes, and external systems](../../../assets/agent-platform/warp-stack-overview.png) * **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/), 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. +* **APIs** - The control plane's entry points: the [Agent API and SDKs](/factories/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, 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 {VARS.WARP_AGENT_CLI} in your CI or orchestrator. See [Self-hosting](/platform/self-hosting/). +* **Warp-hosted execution** - By default, each cloud agent run gets an isolated sandbox prepared from its environment. See [Warp-hosted execution](/factories/warp-hosting/). +* **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 [Managed self-hosting](/factories/self-hosting/) and [unmanaged execution](/platform/unmanaged-execution/). * **External systems** - The platform connects to identity providers, source control, integration providers, model providers, and a payment provider. ## Cloud agent run lifecycle @@ -28,9 +28,9 @@ Every cloud agent run follows the same lifecycle, no matter what started it or w ![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** - 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. +1. **A trigger fires** - A [schedule](/platform/triggers/scheduled-agents/), an [integration](/platform/integrations/) event, an [API or SDK](/factories/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/). +3. **Configuration is resolved** - The platform picks the run's [environment](/platform/environments/), [runner](/factories/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. @@ -54,10 +54,10 @@ Self-hosted execution keeps checkout, commands, and the workspace on your infras ![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** - 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. +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` 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/). +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 [managed backend](/factories/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 [execution security](/platform/execution-security/). 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 [team-managed keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) or [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 {VARS.DASHBOARD} and support [Agent Session Sharing](/agents/local-agents/session-sharing/), the same as Warp-hosted runs. @@ -91,7 +91,7 @@ Every run moves a few distinct classes of data, and each class has its own bound ![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 Warp-managed run-data storage](../../../assets/agent-platform/warp-hosted-data-boundaries.png) -* **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. +* **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 [managed self-hosting](/factories/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. [Team-managed keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) and [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) keep the same route but use 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. * **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. @@ -102,15 +102,15 @@ Every run moves a few distinct classes of data, and each class has its own bound ### 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, routes inference for the Warp Agent, and stores run data. +[Managed self-hosting](/factories/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, routes inference for the Warp Agent, and stores run data. ![Self-hosted data security and boundaries diagram showing what stays in customer infrastructure, what Warp retains, Warp-managed run-data storage, 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. +* [Deployment patterns](/factories/deployment-patterns/) - Choose between CLI-only, Warp-hosted, and self-hosted deployments. +* [Managed self-hosting](/factories/self-hosting/) - Configure a managed worker for factory execution. +* [Execution security](/platform/execution-security/) - 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/execution-security.mdx b/src/content/docs/platform/execution-security.mdx index ae07b84dd..a66f43a03 100644 --- a/src/content/docs/platform/execution-security.mdx +++ b/src/content/docs/platform/execution-security.mdx @@ -38,7 +38,7 @@ 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) +![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):** diff --git a/src/sidebar.ts b/src/sidebar.ts index 4f9182ec9..f422c69ef 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -441,6 +441,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/developer-tools', label: 'Overview' }, { slug: 'factories/factory-api', label: 'Factory API' }, { slug: 'factories/api-and-sdk', label: VARS.API_SDK_NAME }, + { slug: 'factories/api-and-sdk/quickstart', label: 'Quickstart' }, { label: 'API reference', link: '/api' }, { slug: 'factories/api-and-sdk/demo-sentry-monitoring-with-sdk', label: 'Sentry monitoring with the SDK' }, { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'API errors' }, @@ -527,12 +528,13 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ icon: 'cloud-download', items: [ { slug: 'platform/overview', label: 'Overview' }, + { slug: 'platform/architecture', label: 'Architecture' }, { label: 'Cloud Agents', items: [ { slug: 'platform', label: 'Overview' }, { slug: 'platform/quickstart', label: 'Quickstart' }, - { slug: 'platform/transitioning-from-oz', label: 'Transitioning from Oz' }, + { slug: 'platform/transitioning-from-oz', label: `Transitioning from the ${VARS.WEB_APP}` }, { // Runtime (which agent executes the run) is kept separate from // configuration (how any run is set up) -- HYC review, 8/14. diff --git a/vercel.json b/vercel.json index 605a7bf9e..74ef548d5 100644 --- a/vercel.json +++ b/vercel.json @@ -1094,32 +1094,32 @@ }, { "source": "/agent-platform/cloud-agents/managed-worker-reference(/?)", - "destination": "/platform/self-hosting/reference/", + "destination": "/factories/self-hosting/reference/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/direct-backend(/?)", - "destination": "/platform/self-hosting/managed-direct/", + "destination": "/factories/self-hosting/managed-direct/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/docker-connectivity(/?)", - "destination": "/platform/self-hosting/managed-docker/", + "destination": "/factories/self-hosting/managed-docker/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/helm-chart(/?)", - "destination": "/platform/self-hosting/managed-kubernetes/", + "destination": "/factories/self-hosting/managed-kubernetes/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/kubernetes-backend(/?)", - "destination": "/platform/self-hosting/managed-kubernetes/", + "destination": "/factories/self-hosting/managed-kubernetes/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/private-docker-registries(/?)", - "destination": "/platform/self-hosting/managed-docker/", + "destination": "/factories/self-hosting/managed-docker/", "statusCode": 308 }, { @@ -6619,7 +6619,7 @@ }, { "source": "/reference(/?)", - "destination": "/factories/developer-tools/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { From 6c4ebbd409f872e89e154fa826b78eb25207aa52 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 18 Sep 2026 13:26:37 -0600 Subject: [PATCH 35/46] docs: clarify legacy Oz workflow transition Co-Authored-By: Warp <agent@warp.dev> --- .../docs/agents/cli/oz-cli/agent-profiles.mdx | 2 +- .../docs/agents/cli/oz-cli/api-keys.mdx | 2 +- .../docs/agents/cli/oz-cli/artifacts.mdx | 2 +- .../docs/agents/cli/oz-cli/federate.mdx | 2 +- src/content/docs/agents/cli/oz-cli/index.mdx | 2 +- .../agents/cli/oz-cli/integration-setup.mdx | 2 +- .../docs/agents/cli/oz-cli/mcp-servers.mdx | 2 +- .../docs/agents/cli/oz-cli/quickstart.mdx | 2 +- src/content/docs/agents/cli/oz-cli/skills.mdx | 2 +- .../agents/cli/oz-cli/troubleshooting.mdx | 2 +- .../docs/agents/cli/oz-cli/warp-drive.mdx | 2 +- src/content/docs/factories/index.mdx | 2 -- src/content/docs/platform/overview.mdx | 4 --- .../docs/platform/transitioning-from-oz.mdx | 30 +++++++++---------- src/sidebar.ts | 3 +- 15 files changed, 28 insertions(+), 33 deletions(-) diff --git a/src/content/docs/agents/cli/oz-cli/agent-profiles.mdx b/src/content/docs/agents/cli/oz-cli/agent-profiles.mdx index b79d1c77e..b22350238 100644 --- a/src/content/docs/agents/cli/oz-cli/agent-profiles.mdx +++ b/src/content/docs/agents/cli/oz-cli/agent-profiles.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: Agent profiles control what the agent can do, how it behaves, and where it can act when running from the {VARS.WARP_AGENT_CLI}. Create profiles in the Warp app to configure file access, command execution, MCP server usage, model selection, and directory permissions, then reference them by ID in CLI commands. diff --git a/src/content/docs/agents/cli/oz-cli/api-keys.mdx b/src/content/docs/agents/cli/oz-cli/api-keys.mdx index 240b02a53..bda48d596 100644 --- a/src/content/docs/agents/cli/oz-cli/api-keys.mdx +++ b/src/content/docs/agents/cli/oz-cli/api-keys.mdx @@ -8,7 +8,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: API keys let the {VARS.WARP_AGENT_CLI} and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments. diff --git a/src/content/docs/agents/cli/oz-cli/artifacts.mdx b/src/content/docs/agents/cli/oz-cli/artifacts.mdx index 7d36ce629..7a948c1d7 100644 --- a/src/content/docs/agents/cli/oz-cli/artifacts.mdx +++ b/src/content/docs/agents/cli/oz-cli/artifacts.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: Artifacts are files that an agent produces during a run and uploads to Warp — screenshots, generated reports, build outputs, logs, or any other file the agent saves alongside its conversation. Use `oz artifact` to inspect those files from outside the run and pull them down to your machine. diff --git a/src/content/docs/agents/cli/oz-cli/federate.mdx b/src/content/docs/agents/cli/oz-cli/federate.mdx index a2bda5c55..38283ee29 100644 --- a/src/content/docs/agents/cli/oz-cli/federate.mdx +++ b/src/content/docs/agents/cli/oz-cli/federate.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: `oz federate` issues short-lived OIDC identity tokens for the agent that's currently running. Use these tokens to authenticate to cloud providers (AWS, GCP, Azure, and other OIDC-aware systems) without baking long-lived credentials into your environment. diff --git a/src/content/docs/agents/cli/oz-cli/index.mdx b/src/content/docs/agents/cli/oz-cli/index.mdx index f58f2c61b..bb40faeb7 100644 --- a/src/content/docs/agents/cli/oz-cli/index.mdx +++ b/src/content/docs/agents/cli/oz-cli/index.mdx @@ -9,7 +9,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary, which previously shipped as `warp-cli`) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. The [Warp Agent CLI reference](/agents/cli/reference/) does not yet document `warp` equivalents for every workflow on this page. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary, which previously shipped as `warp-cli`) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: The {VARS.WARP_AGENT_CLI} is the command-line tool for running and managing Warp's cloud agents from any terminal, script, or CI pipeline. Use it to start agents locally or in the cloud, connect MCP servers, configure integrations, and authenticate without requiring the Warp desktop app. diff --git a/src/content/docs/agents/cli/oz-cli/integration-setup.mdx b/src/content/docs/agents/cli/oz-cli/integration-setup.mdx index 5cc68e8e6..5bb3b80cd 100644 --- a/src/content/docs/agents/cli/oz-cli/integration-setup.mdx +++ b/src/content/docs/agents/cli/oz-cli/integration-setup.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: This article describes the environment and integration setup that is required before you can trigger agents from external tools, like Slack or Linear. You will learn how to: diff --git a/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx b/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx index 6b109e612..2c2fb78f9 100644 --- a/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx +++ b/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: MCP servers connect agents to external systems like GitHub, Linear, or Sentry. To use a [Model Context Protocol (MCP)](/agents/capabilities/mcp/) server from the CLI, use the `--mcp` flag with `oz agent run` or `oz agent run-cloud`. diff --git a/src/content/docs/agents/cli/oz-cli/quickstart.mdx b/src/content/docs/agents/cli/oz-cli/quickstart.mdx index 3198f28c1..a636edc7a 100644 --- a/src/content/docs/agents/cli/oz-cli/quickstart.mdx +++ b/src/content/docs/agents/cli/oz-cli/quickstart.mdx @@ -9,7 +9,7 @@ import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: This guide walks you through the essentials to get up and running with the {VARS.WARP_AGENT_CLI} in less than 5 minutes: installing the CLI, authenticating, running your first local agent, and optionally connecting MCP servers to give the agent access to external tools. diff --git a/src/content/docs/agents/cli/oz-cli/skills.mdx b/src/content/docs/agents/cli/oz-cli/skills.mdx index e873bb474..460e4d7a6 100644 --- a/src/content/docs/agents/cli/oz-cli/skills.mdx +++ b/src/content/docs/agents/cli/oz-cli/skills.mdx @@ -9,7 +9,7 @@ description: >- import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: [Skills](/agents/capabilities/skills/) are reusable instruction sets that teach agents how to perform specific tasks. Use the `--skill` flag to run an agent from a skill in a repository accessible to your environment. diff --git a/src/content/docs/agents/cli/oz-cli/troubleshooting.mdx b/src/content/docs/agents/cli/oz-cli/troubleshooting.mdx index 1d0cbac60..1c96360fd 100644 --- a/src/content/docs/agents/cli/oz-cli/troubleshooting.mdx +++ b/src/content/docs/agents/cli/oz-cli/troubleshooting.mdx @@ -7,7 +7,7 @@ description: >- import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: Solutions for common {VARS.WARP_AGENT_CLI} errors, including authentication issues, agent failures, environment configuration, GitHub access problems, and Docker image compatibility. Use `oz help` for built-in documentation on any command. diff --git a/src/content/docs/agents/cli/oz-cli/warp-drive.mdx b/src/content/docs/agents/cli/oz-cli/warp-drive.mdx index 6d501db51..e15cb8439 100644 --- a/src/content/docs/agents/cli/oz-cli/warp-drive.mdx +++ b/src/content/docs/agents/cli/oz-cli/warp-drive.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: Reference saved Warp Drive objects in {VARS.WARP_AGENT_CLI} commands to reuse prompts, notebooks, workflows, and rules as agent context. Pass a saved prompt ID with `--saved-prompt` or inline Warp Drive references using `<workflow:id>`, `<notebook:id>`, or `<rule:id>` syntax. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 01e21caea..5242104c6 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -13,8 +13,6 @@ import VideoEmbed from '@components/VideoEmbed.astro'; Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. If your team already has access, sign in to the <a href={VARS.FACTORY_WEB_APP_URL}>{VARS.FACTORY_WEB_APP}</a>. ::: -The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing workflows remain available today. See [Transitioning from the {VARS.WEB_APP}](/platform/transitioning-from-oz/) for the current transition guidance. - A software factory uses a coordinated fleet of agents to take in requests, manage them from triage through review, and turn a growing backlog into mergeable pull requests. Your team stays in the loop to approve specifications and merge each pull request. <VideoEmbed url="https://www.youtube.com/watch?v=0WBk4ai8y1A" title="Introducing Warp Factories" /> diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index 4f037a210..7243c720d 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -13,10 +13,6 @@ import { VARS } from '@data/vars'; If you're new to cloud agents, the [Cloud agents quickstart](/platform/quickstart/) gets you to your first run in about ten minutes. -:::note -The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing cloud-agent workflows remain available today, so you don't need to migrate immediately. The `oz` CLI retains its legacy name during the transition. See [Transitioning from the {VARS.WEB_APP}](/platform/transitioning-from-oz/) for the current guidance. -::: - <VideoEmbed url="https://youtu.be/poLkJhO7fdo" title={`${VARS.WARP_AUTOMATION_PLATFORM} cloud agents overview video`} /> ## How a run works diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx index 9f81aafcc..9712108e9 100644 --- a/src/content/docs/platform/transitioning-from-oz.mdx +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -1,36 +1,36 @@ --- title: Transitioning from the {{WEB_APP}} description: >- - Understand the upcoming {{WEB_APP}} retirement while current cloud-agent - workflows remain available. + Continue supported legacy cloud-agent workflows and decide whether Warp + Factories fits new multi-stage development work. sidebar: label: "Transitioning from the {{WEB_APP}}" --- import { VARS } from '@data/vars'; -The {VARS.WEB_APP} will retire after Warp Factories reaches general availability. Existing cloud agents, integrations, schedules, API keys, and the `oz` CLI remain available today, so you don't need to migrate immediately. +Existing Oz workflows remain supported. You don't need to change an existing workflow to use Warp Factories. -The {VARS.WARP_AUTOMATION_PLATFORM} remains the shared foundation for cloud agents. Warp Factories builds on that foundation for teams that need standing workflows that route work through specialized agents, add review stages, and show the progress of work. +For new multi-stage development workflows, use Warp Factories. A factory builds on the {VARS.WARP_AUTOMATION_PLATFORM} to route work through specialized agents, add review stages, and show the progress of work. -## Choose the right entry point +## Where to manage work -* **{VARS.WARP_AUTOMATION_PLATFORM}** - Configure standalone cloud agents, environments, schedules, integrations, and orchestration. Start with the [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) or [Cloud agents overview](/platform/). -* **Warp Factories** - Build a repeatable workflow that routes work through specialized agents and tracks it in one place. Start with the [Warp Factories overview](/factories/) or the [factory quickstart](/factories/quickstart/). +* **Existing Oz workflows** - Continue using the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> for existing cloud agents, environments, schedules, integrations, and runs. +* **New Factory workflows** - Use the <a href={VARS.FACTORY_WEB_APP_URL}>Factory Dashboard</a> to build and operate multi-stage development workflows. Start with the [Warp Factories overview](/factories/) or the [factory quickstart](/factories/quickstart/). -## What stays available +## CLI, API, and SDK support -These existing workflows and configuration continue to work today: +Existing interfaces remain supported: -* **Cloud agents** - Continue to run from existing events, schedules, integrations, APIs, and the CLI. -* **Configuration** - Existing environments, integrations, schedules, API keys, and secrets remain available. -* **Current tools** - The {VARS.WARP_AGENT_CLI}, API and SDK, and managed self-hosting continue to support their current workflows. +* **{VARS.WARP_AGENT_CLI}** - Existing `oz` commands continue to work. +* **{VARS.API_SDK_NAME}** - Existing API endpoints and SDK packages continue to work. +* **Cloud-agent configuration** - Existing agents, environments, schedules, integrations, API keys, and secrets remain available. -## What comes next +## Moving an existing workflow into a factory -Migration guidance will identify each replacement workflow and its compatibility dates as the transition progresses. Continue using the workflow that fits your work today. +Moving an existing Oz workflow into a factory is optional. Each workflow has different integrations, configuration, and operating requirements, so work with an engineering DRI to evaluate the move. Warp will publish guidance before any support change. ## Related pages -* [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) - Configure the reusable primitives behind cloud-agent workflows. +* [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) - Configure standalone cloud-agent workflows. * [Warp Factories overview](/factories/) - Build and operate a standing software factory. * [Factory dashboard](/factories/factory-dashboard/) - Inspect work items, runs, and factory settings. diff --git a/src/sidebar.ts b/src/sidebar.ts index f422c69ef..73cf1fd28 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -500,13 +500,14 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ }, ], }, - // Troubleshooting sits outside the groups, last in the tab. It was in + // Troubleshooting sits outside the groups near the end of the tab. It was in // 'Management & observability' next to the dashboard and Scorers pages, // which read as a sibling of the measurement surfaces rather than as // the place you go when something is broken. A bare trailing item is // the same shape the Automation Platform tab uses for its leading // 'Overview'. { slug: 'factories/troubleshooting', label: 'Troubleshooting' }, + { slug: 'platform/transitioning-from-oz', label: 'Legacy Oz workflows' }, ], }, { From 71cf2b3f7465f5d13c8397d05b2b3694c85b591b Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 18 Sep 2026 13:44:25 -0600 Subject: [PATCH 36/46] docs: align transition guide terminology Co-Authored-By: Warp <agent@warp.dev> --- src/content/docs/platform/transitioning-from-oz.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx index 9712108e9..9f0686126 100644 --- a/src/content/docs/platform/transitioning-from-oz.mdx +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -8,14 +8,14 @@ sidebar: --- import { VARS } from '@data/vars'; -Existing Oz workflows remain supported. You don't need to change an existing workflow to use Warp Factories. +Existing {VARS.WARP_AUTOMATION_PLATFORM} workflows remain supported. You don't need to change an existing workflow to use Warp Factories. For new multi-stage development workflows, use Warp Factories. A factory builds on the {VARS.WARP_AUTOMATION_PLATFORM} to route work through specialized agents, add review stages, and show the progress of work. ## Where to manage work -* **Existing Oz workflows** - Continue using the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> for existing cloud agents, environments, schedules, integrations, and runs. -* **New Factory workflows** - Use the <a href={VARS.FACTORY_WEB_APP_URL}>Factory Dashboard</a> to build and operate multi-stage development workflows. Start with the [Warp Factories overview](/factories/) or the [factory quickstart](/factories/quickstart/). +* **Existing {VARS.WARP_AUTOMATION_PLATFORM} workflows** - Continue using the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> for existing cloud agents, environments, schedules, integrations, and runs. +* **New factory workflows** - Use the <a href={VARS.FACTORY_WEB_APP_URL}>factory dashboard</a> to build and operate multi-stage development workflows. Start with the [Warp Factories overview](/factories/) or the [factory quickstart](/factories/quickstart/). ## CLI, API, and SDK support @@ -27,7 +27,7 @@ Existing interfaces remain supported: ## Moving an existing workflow into a factory -Moving an existing Oz workflow into a factory is optional. Each workflow has different integrations, configuration, and operating requirements, so work with an engineering DRI to evaluate the move. Warp will publish guidance before any support change. +Moving an existing {VARS.WARP_AUTOMATION_PLATFORM} workflow into a factory is optional. Each workflow has different integrations, configuration, and operating requirements, so work with an engineering DRI to evaluate the move. Warp will publish guidance before any support change. ## Related pages From 3dd3e1977cc282e9c67128eeb4a998c84cb1c4eb Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 18 Sep 2026 16:12:39 -0600 Subject: [PATCH 37/46] docs: unify platform API guidance Co-Authored-By: Warp <agent@warp.dev> --- developers/agent-api-openapi.yaml | 4 +- .../docs/agents/agent-memory/index.mdx | 2 +- .../capabilities/computer-use/index.mdx | 4 +- .../docs/agents/cli/oz-cli/artifacts.mdx | 4 +- src/content/docs/agents/cli/oz-cli/index.mdx | 2 +- src/content/docs/changelog/2026.mdx | 2 +- .../demo-sentry-monitoring-with-sdk.mdx | 2 +- .../docs/factories/api-and-sdk/index.mdx | 67 ++++++----- .../docs/factories/api-and-sdk/quickstart.mdx | 14 +-- .../errors/authentication-required.mdx | 2 +- .../troubleshooting/errors/conflict.mdx | 2 +- .../troubleshooting/errors/index.mdx | 6 +- .../errors/invalid-request.mdx | 2 +- .../troubleshooting/errors/not-authorized.mdx | 2 +- .../errors/operation-not-supported.mdx | 2 +- .../docs/factories/connect-your-factory.mdx | 6 +- .../docs/factories/developer-tools.mdx | 28 ++--- src/content/docs/factories/factory-api.mdx | 30 ++--- .../docs/factories/factory-as-code.mdx | 2 +- .../docs/factories/how-factories-work.mdx | 4 +- src/content/docs/factories/index.mdx | 32 ++---- src/content/docs/factories/quickstart.mdx | 2 +- .../how-to-run-multiple-ai-coding-agents.mdx | 6 +- .../how-to-run-unattended-agents.mdx | 6 +- .../run-a-software-factory-in-the-cloud.mdx | 2 +- ...ld-a-mattermost-bot-for-warp-factories.mdx | 10 +- src/content/docs/platform/agents.mdx | 4 +- src/content/docs/platform/architecture.mdx | 2 +- src/content/docs/platform/index.mdx | 6 +- .../platform/integrations/cloud-providers.mdx | 2 +- .../docs/platform/orchestration/index.mdx | 12 +- .../orchestration/multi-agent-runs.mdx | 12 +- src/content/docs/platform/overview.mdx | 4 +- src/content/docs/platform/oz-web-app.mdx | 2 +- src/content/docs/platform/quickstart.mdx | 2 +- src/content/docs/platform/secrets.mdx | 2 +- .../docs/platform/skills-as-agents.mdx | 4 +- .../team-access-billing-and-identity.mdx | 2 +- .../docs/platform/transitioning-from-oz.mdx | 36 +++--- .../docs/platform/unmanaged-execution.mdx | 2 +- .../plans-and-billing/credits.mdx | 2 +- src/data/vars.ts | 26 ++--- src/pages/api.astro | 24 ++-- src/pages/openapi.yaml.ts | 2 +- src/sidebar.ts | 104 +++++++++--------- 45 files changed, 242 insertions(+), 253 deletions(-) diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml index eef3209a8..7f7c59d71 100644 --- a/developers/agent-api-openapi.yaml +++ b/developers/agent-api-openapi.yaml @@ -1,8 +1,8 @@ openapi: 3.0.0 info: - title: Warp Agent API + title: Warp Platform API version: 1.0.0 - description: "API for creating, managing, and querying Warp cloud agent runs.\n\nThese endpoints allow users to programmatically spawn agents, list runs, \nand retrieve detailed run information.\n" + description: "API for creating, managing, and querying factory and cloud agent runs.\n\nThese endpoints allow users to send work to factories, start standalone agents, list runs, \nand retrieve detailed run information.\n" contact: name: Warp Support url: https://docs.warp.dev diff --git a/src/content/docs/agents/agent-memory/index.mdx b/src/content/docs/agents/agent-memory/index.mdx index 1f63001e3..f4c8b38cb 100644 --- a/src/content/docs/agents/agent-memory/index.mdx +++ b/src/content/docs/agents/agent-memory/index.mdx @@ -85,7 +85,7 @@ Attach stores to agents with read-only or read-write access. Each attachment inc These capabilities aren't part of the research preview yet, but they're on the way: -* **Programmatic API access** - Read and manage memories and stores through the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/), in addition to managing them in the {VARS.WEB_APP}. +* **Programmatic API access** - Read and manage memories and stores through the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), in addition to managing them in the {VARS.WEB_APP}. * **Self-hosting support** - Run Agent Memory on a [self-hosted {VARS.WARP_AUTOMATION_PLATFORM}](/factories/self-hosting/) instance to meet security, privacy, and compliance requirements. ## Join the waitlist diff --git a/src/content/docs/agents/capabilities/computer-use/index.mdx b/src/content/docs/agents/capabilities/computer-use/index.mdx index 4f3a915be..8f4dc46d8 100644 --- a/src/content/docs/agents/capabilities/computer-use/index.mdx +++ b/src/content/docs/agents/capabilities/computer-use/index.mdx @@ -53,7 +53,7 @@ oz agent run-cloud --no-computer-use --prompt "<task>" ### API -When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp's built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run: +When creating a cloud agent run with the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp's built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run: ```json { @@ -65,7 +65,7 @@ When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/factories/api-an } ``` -For full API documentation, see the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) reference. +For full API documentation, see the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) reference. ### Web app diff --git a/src/content/docs/agents/cli/oz-cli/artifacts.mdx b/src/content/docs/agents/cli/oz-cli/artifacts.mdx index 7a948c1d7..cf2acab1a 100644 --- a/src/content/docs/agents/cli/oz-cli/artifacts.mdx +++ b/src/content/docs/agents/cli/oz-cli/artifacts.mdx @@ -22,7 +22,7 @@ Use artifacts when you need to retrieve files an agent produced after a run comp * **Local inspection** - Pull a generated file (HTML, image, CSV) onto your laptop to review. * **CI integration** - Fetch an agent-produced build artifact from a pipeline step that runs after the agent finishes. -Artifacts are referenced by an artifact UID. You can find UIDs in the agent's run detail view, in the JSON returned by [`oz run get`](/agents/cli/oz-cli/), or in the response from the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/). +Artifacts are referenced by an artifact UID. You can find UIDs in the agent's run detail view, in the JSON returned by [`oz run get`](/agents/cli/oz-cli/), or in the response from the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/). ## `oz artifact get` @@ -78,5 +78,5 @@ oz artifact download "$ARTIFACT_UID" --out ./latest-report.html ## Related -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - retrieve artifacts programmatically over HTTP. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - retrieve artifacts programmatically over HTTP. * [Scheduled cloud agents](/platform/triggers/scheduled-agents/) - common producer of recurring artifacts that downstream tooling consumes. diff --git a/src/content/docs/agents/cli/oz-cli/index.mdx b/src/content/docs/agents/cli/oz-cli/index.mdx index bb40faeb7..6fa1b9bb5 100644 --- a/src/content/docs/agents/cli/oz-cli/index.mdx +++ b/src/content/docs/agents/cli/oz-cli/index.mdx @@ -306,7 +306,7 @@ The `--name` flag assigns a config name to the run. Use it to group related runs **Why naming matters:** -When your team runs many agents across schedules, integrations, and ad-hoc triggers, `name` lets you answer questions like "how many distinct workflows are we running?" and "how often does this particular workflow run?" You can filter runs by name using the `name` query parameter on `GET /agent/runs` in the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/). +When your team runs many agents across schedules, integrations, and ad-hoc triggers, `name` lets you answer questions like "how many distinct workflows are we running?" and "how often does this particular workflow run?" You can filter runs by name using the `name` query parameter on `GET /agent/runs` in the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/). **Examples:** diff --git a/src/content/docs/changelog/2026.mdx b/src/content/docs/changelog/2026.mdx index b52f9e911..9d8a85995 100644 --- a/src/content/docs/changelog/2026.mdx +++ b/src/content/docs/changelog/2026.mdx @@ -1673,7 +1673,7 @@ Oz is Warp's orchestration platform for cloud agents: launch parallel agents, au * **Cloud environments for consistent execution** — configure Docker-based environments (unlimited repos + setup commands) and run agents in isolated cloud sandboxes. [Environments docs →](https://docs.warp.dev/platform/environments) * **Track agents from the web** — manage runs, create schedules, configure environments, and set up integrations from any browser in the <a href="https://oz.warp.dev">Oz web app</a>. * **Schedule agents based on Skills** — run agents automatically on a cron schedule for code cleanup, dependency updates, and issue triage. See [Scheduled Agents](/platform/triggers/scheduled-agents/). -* **Programmable by default** — orchestrate agents via the CLI and integrate Oz into tools and services via the [API and CLI reference](/factories/developer-tools/). +* **Programmable by default** — orchestrate agents via the CLI and integrate Oz into tools and services via the [API reference](/factories/developer-tools/). #### Warp Upgrades diff --git a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index 51250f461..b45b694f7 100644 --- a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -18,7 +18,7 @@ Example repository: [**Sentry monitor example repository**](https://github.com/w In this demo, Ben builds a small TypeScript “Sentry monitor” service that listens for specific Sentry alerts (like a Go nil pointer dereference) and triggers a Warp cloud agent to investigate. The server validates the webhook, extracts the stack trace, and injects it into an agent run inside a Warp Environment so the agent can inspect the repo and propose a fix. -To route the alert through a factory's named agents and workflow instead, use the [factory API](/factories/factory-api/) to dispatch the request. This example remains useful for custom standalone cloud-agent intake. +To route the alert through a factory's named agents and workflow instead, use [factory endpoints](/factories/factory-api/) to dispatch the request. This example remains useful for custom standalone cloud-agent intake. He also covers the task lifecycle basics in the TypeScript SDK (running an agent, polling task state to fetch a session link for debugging), and shows the end result: a draft GitHub pull request created from the Sentry event for a maintainer to review. diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx index b1f54b026..7746f0776 100644 --- a/src/content/docs/factories/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -1,29 +1,24 @@ --- topic: factories -title: "{{API_SDK_NAME}} reference" +title: Agent & run endpoints sidebar: - label: "{{API_SDK_NAME}}" + label: "Agent & run endpoints" description: >- - Create and operate factory and cloud agent runs over HTTP, or use the Python - and TypeScript SDKs for typed requests, retries, and error handling. + Start, manage, and inspect cloud agent runs with the Agent and run endpoints + in the Warp Platform API. --- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Use the {VARS.API_SDK_NAME} to start standalone cloud-agent runs, or to monitor, continue, and cancel any run after it starts. To find a factory and send it new work, use the [factory API](/factories/factory-api/). - -| API | Use it for | -| --- | --- | -| **factory API** | Find a factory and dispatch new work to its foreman. | -| **{VARS.API_SDK_NAME}** | Start standalone cloud-agent runs, and manage factory or standalone runs after they begin. | +Agent & run endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to start standalone cloud agent runs and to monitor, continue, or cancel any run after it starts. To find a factory and send it new work, use [factory endpoints](/factories/factory-api/). :::note -Some examples in this reference and the [CLI reference](/agents/cli/oz-cli/) use `oz` commands (for example, `oz environment list`) from the {VARS.WARP_AGENT_CLI}. Those commands remain available during the transition. The [Warp Agent CLI reference](/agents/cli/reference/) does not yet document a `warp` equivalent. +Some examples use `oz` commands, such as `oz environment list`, from the {VARS.WARP_AGENT_CLI}. Existing commands remain supported during the transition. ::: -### API overview +## Use Agent & run endpoints -The {VARS.API_SDK_NAME} lets you create and inspect [Cloud Agent](/platform/) runs over HTTP from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app. +Agent & run endpoints let you create and inspect [cloud agent](/platform/) runs over HTTP from CI, cron, backend services, and internal tools, without requiring the Warp desktop app. **With the API you can:** @@ -34,14 +29,14 @@ The {VARS.API_SDK_NAME} lets you create and inspect [Cloud Agent](/platform/) ru :::caution This page is a high-level overview.\ \ -For full API endpoint details, refer to the [**Agents API Reference**](/api). For schema definitions, see the SDK repos: [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript). +For endpoint details, use the [**Warp Platform API reference**](/api). For SDK schemas, use the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript) repositories. ::: -To send work to a [Warp factory](/factories/), use the [factory API](/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/run` with a foreman's `agent_identity_uid`. Everything on this page - follow-ups, cancellation, status - still applies once a factory run is dispatched. +To send work to a [Warp factory](/factories/), use [factory endpoints](/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/run` with a foreman's `agent_identity_uid`. The follow-up, cancellation, and status endpoints still apply after a factory run is dispatched. -### SDK overview +## SDKs -Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs that wrap the {VARS.API_SDK_NAME} with: +Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs that wrap the {VARS.WARP_PLATFORM_API} with: * **Typed requests and responses** (editor autocomplete, fewer schema mistakes) * **Built-in retries and timeouts** (with per-request overrides) @@ -50,7 +45,7 @@ Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. -<VideoEmbed url="https://www.youtube.com/watch?v=0cf7383MZSk" title={`${VARS.API_SDK_NAME} reference overview video`} /> +<VideoEmbed url="https://www.youtube.com/watch?v=0cf7383MZSk" title={`${VARS.WARP_PLATFORM_API} reference overview video`} /> **SDK vs raw REST** @@ -63,9 +58,7 @@ For the full SDK surface area and latest usage, refer to the GitHub repos: [**Py --- -## API reference - -### REST API base URL +## API base URL All endpoints are served over HTTPS: @@ -73,9 +66,7 @@ All endpoints are served over HTTPS: https://app.warp.dev/api/v1 ``` -### Core concepts - -#### **Agent runs** +### Agent runs An agent run represents a single execution of a cloud agent, created with a prompt and optional configuration. Each run has: @@ -87,9 +78,9 @@ An agent run represents a single execution of a cloud agent, created with a prom * Optional session information (`session_id`, `session_link`) * Optional resolved configuration (`agent_config`) -See the [**Agents API Reference**](/api) for details on how runs are created and listed. +See the [**Warp Platform API reference**](/api) for details on how runs are created and listed. -#### **Agent configuration** +### Agent configuration You can influence how an agent runs using AmbientAgentConfig, including: @@ -97,6 +88,7 @@ You can influence how an agent runs using AmbientAgentConfig, including: * `model_id` for LLM selection * `base_prompt` to shape behavior * `environment_id` to choose a `CloudEnvironment` +* `worker_host` to run a standalone cloud agent on a [self-hosted worker](/factories/self-hosting/) * `skill_spec` to use a [skill](/agents/capabilities/skills/) as the base prompt (format: `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md`) * `mcp_servers` to enable specific tools via MCP @@ -104,9 +96,24 @@ See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**Type --- -### Key endpoints +## Route a run to a self-hosted worker + +Set `worker_host` in the request configuration to select a connected self-hosted worker. Omit it, or set it to `warp`, to use Warp-hosted workers. + +```json +{ + "prompt": "Run the dependency audit", + "config": { + "worker_host": "WORKER_HOST" + } +} +``` + +Replace `WORKER_HOST` with the ID of a connected worker. For factory work, set `workerHost` in the [factory definition](/factories/factory-as-code/#agentdefaultsworkerhost) instead. + +## Key endpoints -**The Agents API exposes these primary endpoints:** +Agent & run endpoints include: * `POST /agent/run` @@ -124,11 +131,11 @@ See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**Type Cancel a run that is currently queued or in progress. Returns the ID of the cancelled run. -All endpoint semantics, query parameters, and [error codes](/factories/api-and-sdk/troubleshooting/errors/) are documented on the [Agents API Reference](/api). +All endpoint semantics, query parameters, and [error codes](/factories/api-and-sdk/troubleshooting/errors/) are documented in the [Warp Platform API reference](/api). --- -#### Models reference +## Models The API shares a set of reusable models across endpoints. Detailed JSON schemas, types, and enums are available in the SDK repos ([Python](https://github.com/warpdotdev/oz-sdk-python), [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript)). Key models include: diff --git a/src/content/docs/factories/api-and-sdk/quickstart.mdx b/src/content/docs/factories/api-and-sdk/quickstart.mdx index 725c5f9bd..89533d3fc 100644 --- a/src/content/docs/factories/api-and-sdk/quickstart.mdx +++ b/src/content/docs/factories/api-and-sdk/quickstart.mdx @@ -1,8 +1,8 @@ --- topic: factories -title: "API & SDK quickstart" +title: "Warp Platform API quickstart" description: >- - Create and monitor your first cloud agent run via the {{API_SDK_NAME}} in ~5 + Create and monitor your first cloud agent run via the {{WARP_PLATFORM_API}} in ~5 minutes. sidebar: label: "Quickstart" @@ -10,12 +10,12 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -The {VARS.API_SDK_NAME} lets you run and manage cloud agents from anywhere — CI/CD pipelines, backend services, scripts, or custom tooling — without the Warp desktop app. This quickstart walks you through creating your first run and checking its status. +The {VARS.WARP_PLATFORM_API} lets you run and manage cloud agents from CI/CD pipelines, backend services, scripts, or custom tooling without the Warp desktop app. This quickstart walks you through creating your first run and checking its status. -To dispatch work through a factory's named agents and workflow, use the [factory API](/factories/factory-api/) after this quickstart. The run-management steps below also apply to the factory run that API creates. +To dispatch work through a factory's named agents and workflow, use [factory endpoints](/factories/factory-api/) after this quickstart. The run-management steps below also apply to the factory run those endpoints create. Watch this short demo of how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team: -<VideoEmbed url="https://youtu.be/N6qMe641K34" title={`${VARS.API_SDK_NAME} quickstart video`} /> +<VideoEmbed url="https://youtu.be/N6qMe641K34" title={`${VARS.WARP_PLATFORM_API} quickstart video`} /> --- @@ -76,7 +76,7 @@ The `state` has the following possible values: * `SUCCEEDED` - The run completed successfully. * `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/factories/api-and-sdk/troubleshooting/errors/) to interpret the error code. -These are the most common states. See the [full API reference](/factories/api-and-sdk/) for all possible values. +These are the most common states. See the [Agent & run endpoints](/factories/api-and-sdk/) and [Warp Platform API reference](/api) for all possible values. To list all recent runs: @@ -95,7 +95,7 @@ You can also view and manage all runs in the <a href={`${VARS.WEB_APP_URL}/runs` ## Next steps -* **Read the full API reference** - [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) documents all endpoint parameters, query filters, and response schemas. +* **Read the endpoint guide** - [Agent & run endpoints](/factories/api-and-sdk/) documents the configuration and run lifecycle, while the [Warp Platform API reference](/api) lists all parameters, query filters, and response schemas. * **Explore the SDKs** - [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) include typed request/response models, retries, and error handling. * **See a real-world example** - [Demo: Sentry monitoring with SDK](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors. * **Schedule and automate** - See [Scheduled Agents Quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or [Integrations Quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear. diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx index 332140f14..af1d74d29 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx @@ -58,5 +58,5 @@ This error is returned when: ## Related -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API authentication +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API authentication * [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) — API key management diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx index 3cf340fdb..344c0f5d1 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx @@ -58,4 +58,4 @@ For task cancellation specifically, wait until the task moves from **pending** t ## Related * [Managing Cloud Agents](/platform/managing-cloud-agents/) — Viewing and managing agent tasks -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API reference for managing agent tasks +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API reference for managing agent tasks diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx index ef969c79d..7dfbfd57f 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx @@ -2,13 +2,13 @@ topic: factories title: API errors description: >- - Reference for all error codes returned by the {{API_SDK_NAME}}. Each error + Reference for all error codes returned by the {{WARP_PLATFORM_API}}. Each error includes an HTTP status, machine-readable code, and actionable resolution steps. --- import { VARS } from '@data/vars'; -When the {VARS.API_SDK_NAME} encounters an error, it returns a structured JSON response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807). Every error response includes a machine-readable error code, HTTP status, human-readable message, and resolution details. +When the {VARS.WARP_PLATFORM_API} encounters an error, it returns a structured JSON response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807). Every error response includes a machine-readable error code, HTTP status, human-readable message, and resolution details. --- @@ -88,6 +88,6 @@ When an error response includes a `trace_id`, you can include it when [contactin ## Related -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API reference for creating and managing agent tasks +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API reference for creating and managing agent tasks * [Cloud Agents Overview](/platform/) — How cloud agents work * [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Plan requirements and billing details diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx index 3bce443c3..67bd7db3f 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx @@ -59,4 +59,4 @@ The `detail` field in the response will describe the specific validation issue. ## Related -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API request format and parameters +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API request format and parameters diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx index df721242f..fd42806e3 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx @@ -57,4 +57,4 @@ This error is returned when: ## Related * [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Permission model and identity -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API authentication and authorization +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API authentication and authorization diff --git a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx index b88945263..d2ee357e0 100644 --- a/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx @@ -58,4 +58,4 @@ This error is returned when: * [Cloud Agents Overview](/platform/) — How cloud agent tasks work * [Self-hosting](/factories/self-hosting/) — Self-hosted agent configuration -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — API reference for managing agent tasks +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API reference for managing agent tasks diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index 78cea5336..7b9dca2fa 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -25,7 +25,7 @@ Once a source is connected, here's the concrete action that hands it work — ea | [Linear](/factories/integrations/linear/) | Planned issues | [Assigning the issue to the factory, or mentioning the Warp app in a comment](/factories/integrations/linear/#route-agent-sessions) | The Linear issue and its agent session | | [Jira](/factories/integrations/jira/) | Work items assigned to Warp | [Assigning or mentioning **Warp** on a work item](/factories/integrations/jira/#connect-jira-and-add-an-automation) | The Jira agent session | | [Custom webhooks](/factories/webhooks/) | Any system that can POST JSON: CI, monitoring, alerting, and internal tools | [Posting JSON to the webhook's URL from the external system](/factories/webhooks/#configure-the-sender) | The factory work item | -| [Factory API](/factories/factory-api/) | Custom integrations and scripts that dispatch by factory UID | [Calling `POST /factory/{uid}/runs` with a prompt](/factories/factory-api/#dispatch-a-run-to-a-factory) | The factory work item | +| [factory endpoints](/factories/factory-api/) | Custom integrations and scripts that dispatch by factory UID | [Calling `POST /factory/{uid}/runs` with a prompt](/factories/factory-api/#dispatch-a-run-to-a-factory) | The factory work item | | [Factory MCP](/factories/factory-mcp/) | Exchanging work with a local coding agent, in both directions | [Calling `send_task` from a connected coding agent](/factories/factory-mcp/#send-new-work-to-a-factory) | The factory work item | | Direct runs and schedules | One-off or recurring work | [Clicking **New** on the factory's Runs page, or adding a schedule trigger](#direct-runs-and-schedules) | The factory work item | @@ -69,9 +69,9 @@ These defaults are starting points. Review each automation's filters, agent, and A [custom webhook](/factories/webhooks/) gives the factory an authenticated URL that any system can POST JSON to, and an automation decides which deliveries start work by filtering on the payload. Use it for tools Warp doesn't connect to directly, such as your CI system, PagerDuty, Sentry, or Stripe, without writing any code on your side. -## Factory API +## factory endpoints -The [factory API](/factories/factory-api/) lets your own code discover a factory and dispatch a task to it by UID, without knowing which agent handles the work. Use it to build a custom integration for a tool Warp doesn't connect to directly - see [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) for a worked example. +[factory endpoints](/factories/factory-api/) let your own code discover a factory and dispatch a task to it by UID, without knowing which agent handles the work. Use them to build a custom integration for a tool Warp doesn't connect to directly - see [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) for a worked example. ## Factory MCP diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx index 8e92a677f..e845a1254 100644 --- a/src/content/docs/factories/developer-tools.mdx +++ b/src/content/docs/factories/developer-tools.mdx @@ -1,28 +1,28 @@ --- -title: Developer tools for Warp Factories +title: Warp Platform API & SDKs description: >- - Use APIs, SDKs, webhooks, and MCP to integrate Warp Factories with your - services, tools, and development workflows. + Use the Warp Platform API, SDKs, Factory MCP, and webhooks to integrate + factories and cloud agent runs with your tools and services. sidebar: - label: "Developer tools" + label: "Overview" --- import { VARS } from '@data/vars'; -Warp Factories provides programmatic interfaces for sending work to a factory, integrating external systems, and inspecting the runs a factory produces. +The {VARS.WARP_PLATFORM_API} serves both factories and standalone cloud agent runs. factory endpoints send work to a factory; agent and run endpoints start and manage standalone runs. Both endpoint families use the same API key, API reference, SDKs, and error model. -## Choose an interface +## Choose an API surface -* **[Factory API](/factories/factory-api/)** - Find a factory and send work to it by UID from your own application or service. -* **[{VARS.API_SDK_NAME}](/factories/api-and-sdk/)** - Create, monitor, and manage cloud agent runs from scripts, CI, and backend services. -* **[API reference](/api)** - Look up the full HTTP API schema, parameters, and responses. +* **[factory endpoints](/factories/factory-api/)** - Find a factory and send work to it by UID from your application or service. +* **[Agent & run endpoints](/factories/api-and-sdk/)** - Start, monitor, continue, and cancel cloud agent runs from scripts, CI, and backend services. +* **[Warp Platform API reference](/api)** - Look up the full HTTP schema, parameters, and responses. +* **[Python SDK](https://github.com/warpdotdev/oz-sdk-python)** - Make typed requests from Python. The current package retains its `oz-sdk-python` name. +* **[TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript)** - Make typed requests from TypeScript. The current package retains its `oz-sdk-typescript` name. +* **[API errors](/factories/api-and-sdk/troubleshooting/errors/)** - Resolve error responses by HTTP status and machine-readable code. * **[Factory MCP](/factories/factory-mcp/)** - Exchange work between a factory and a connected coding agent or MCP client. * **[Webhooks](/factories/webhooks/)** - Receive events from systems that can send JSON and route matching deliveries into factory automations. +## Get started -## Use the API and SDK - -Use the API and SDK for typed requests, retries, and error handling. Start with the [API and SDK quickstart](/factories/api-and-sdk/quickstart/) to create and inspect a run, or use the [Sentry monitoring example](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) to connect an external event source. - -For request errors, see [API errors](/factories/api-and-sdk/troubleshooting/errors/). +Start with the [API & SDK quickstart](/factories/api-and-sdk/quickstart/) to create and inspect a run. For a production event source, use the [Sentry monitoring example](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) to connect a webhook handler. ## Related pages diff --git a/src/content/docs/factories/factory-api.mdx b/src/content/docs/factories/factory-api.mdx index 40a03c247..a713b479c 100644 --- a/src/content/docs/factories/factory-api.mdx +++ b/src/content/docs/factories/factory-api.mdx @@ -1,14 +1,14 @@ --- -title: Use the factory API +title: Factory endpoints description: >- - Discover factories and dispatch tasks by UID with the public factory API, + Discover factories and dispatch tasks by UID with factory endpoints, without learning the foreman agent's internals. sidebar: - label: "Factory API" + label: "Factory endpoints" --- import { VARS } from '@data/vars'; -Use the factory API to find a factory and start work from a custom integration without managing agent details. Build it into a chat bot, script, or service for any tool Warp doesn't connect to directly. +The factory endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to find a factory and start work from a custom integration without managing agent details. Build them into a chat bot, script, or service for any tool Warp doesn't connect to directly. :::note Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. @@ -20,21 +20,21 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ * `GET /factory/{uid}` - get one factory by UID. * `POST /factory/{uid}/runs` - dispatch a run to the factory's foreman agent. Pass a `prompt`; the server resolves the foreman for you. -A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [Agent API](/factories/api-and-sdk/) you'd use for any run. +A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [agent and run endpoints](/factories/api-and-sdk/) used for any run. -## When to use the factory API vs the Agent API +## Choosing an endpoint family -Use the factory API to find or start work on a factory. Use the Agent API for everything else - a standalone cloud agent, run management, or orchestration. +Use factory endpoints to find or start work on a factory. Use Agent & run endpoints for everything else: a standalone cloud agent, run management, or orchestration. | Task | Recommended API | | --- | --- | -| Find a factory by name before dispatching to it | factory API - `GET /factory?search=` | -| Start a new task on a factory | factory API - `POST /factory/{uid}/runs` | -| Continue, monitor, or cancel a run (factory or standalone) | Agent API - `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` | -| Run a standalone cloud agent with no factory involved | Agent API - `POST /agent/run` | -| Build a multi-agent orchestration | Agent API - see [multi-agent orchestration](/platform/orchestration/) | +| Find a factory by name before dispatching to it | factory endpoints - `GET /factory?search=` | +| Start a new task on a factory | factory endpoints - `POST /factory/{uid}/runs` | +| Continue, monitor, or cancel a run (factory or standalone) | Agent & run endpoints - `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` | +| Run a standalone cloud agent with no factory involved | Agent & run endpoints - `POST /agent/run` | +| Build a multi-agent orchestration | Agent & run endpoints - see [multi-agent orchestration](/platform/orchestration/) | -The Agent API isn't deprecated: every factory run is still an ordinary run, so the same endpoints handle status, follow-ups, and cancellation no matter which API started it. +Every factory run is still an ordinary run, so Agent & run endpoints handle status, follow-ups, and cancellation no matter which endpoint family started it. ## Discover a factory @@ -123,8 +123,8 @@ See [key endpoints](/factories/api-and-sdk/#key-endpoints) for the full set of r ## Related pages -* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the factory API alongside Slack, GitHub, and Factory MCP. +* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including factory endpoints alongside Slack, GitHub, and Factory MCP. * [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) - A worked example that discovers a factory and dispatches and continues a task from a custom chat integration. * [Factory MCP](/factories/factory-mcp/) - Connect a local coding agent to a factory instead of calling the REST API directly. -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying Agent API. +* [Agent & run endpoints](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying Warp Platform API. * [How Warp Factories work](/factories/how-factories-work/) - The stages a dispatched task moves through after the foreman picks it up. diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 113eed296..f0aa1d243 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -257,7 +257,7 @@ harness: ### `agentDefaults.harness` -The harness and model that runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude`, `codex`, or `gemini` — the values the definition schema validates. `claude-code` is also accepted as an alias for `claude`; prefer `claude`, the canonical [harness identifier](/platform/harnesses/#harness-identifiers) that the CLI and the Agent API use for the same harness. For what each harness does and which ones your team can run, see [supported harnesses](/platform/harnesses/). +The harness and model that runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude`, `codex`, or `gemini` — the values the definition schema validates. `claude-code` is also accepted as an alias for `claude`; prefer `claude`, the canonical [harness identifier](/platform/harnesses/#harness-identifiers) that the CLI and the Warp Platform API use for the same harness. For what each harness does and which ones your team can run, see [supported harnesses](/platform/harnesses/). ```yaml harness: diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index 9f85f34fb..daa8b4c55 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -11,7 +11,7 @@ sidebar: Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: -A factory is a team of cloud agents that ships software the way your team does: a request comes in, moves through the stages it needs, and comes back as a pull request ready for review. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle. +A factory is a standing software development workflow that connects your repositories and engineering tools to a team of agents and execution infrastructure. It takes in requests, moves them through the stages they need, and turns them into pull requests ready for review. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle. Deciding which repositories belong in this factory is a separate question. See [sizing a factory](/factories/#sizing-a-factory) for that guidance. @@ -21,7 +21,7 @@ A **work item** is a single request the factory acts on, such as an issue, suppo The diagram's components, from intake to improvement: -* **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 [custom webhooks](/factories/webhooks/) and the [factory API](/factories/factory-api/), from local coding agents through the [Factory MCP](/factories/factory-mcp/), or from direct runs and schedules. +* **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 [custom webhooks](/factories/webhooks/) and [factory endpoints](/factories/factory-api/), from local coding agents through the [Factory MCP](/factories/factory-mcp/), or from direct runs and schedules. * **Automations** - [Automations](/factories/automations/) filter provider events and decide which agent handles them. Schedules fire them on a timer; direct requests go straight to the foreman. * **Foreman and stage agents** - The foreman holds one conversation per work item and dispatches the Triage, Spec, Implement, and Review agents as the work needs them. See [factory agents](/factories/factory-agents/) and the stages below. * **Human handoff** - The factory opens a pull request with evidence, updates the original work item, and you review and merge. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 5242104c6..9c03453b1 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -13,7 +13,7 @@ import VideoEmbed from '@components/VideoEmbed.astro'; Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. If your team already has access, sign in to the <a href={VARS.FACTORY_WEB_APP_URL}>{VARS.FACTORY_WEB_APP}</a>. ::: -A software factory uses a coordinated fleet of agents to take in requests, manage them from triage through review, and turn a growing backlog into mergeable pull requests. Your team stays in the loop to approve specifications and merge each pull request. +A factory is a standing software development workflow that connects your repositories and engineering tools to a team of agents and execution infrastructure. It takes in requests, manages them from triage through review, and turns a growing backlog into mergeable pull requests. Your team stays in the loop to approve specifications and merge each pull request. <VideoEmbed url="https://www.youtube.com/watch?v=0WBk4ai8y1A" title="Introducing Warp Factories" /> @@ -21,7 +21,7 @@ A software factory uses a coordinated fleet of agents to take in requests, manag In practice, that means tracking each request as a work item, such as an issue, ticket, or triggered task, and moving it through specialized agents that triage it, write a specification when one is needed, implement the change, and review the result. -A factory is one deployed instance of that pattern, connecting your repositories and engineering tools to a team of agents, execution infrastructure, and a measurable workflow. Each factory applies a single policy across all of its work sources, so deploy separate factories for repository groups that need different policies. +Each factory applies a single policy across its work sources, so deploy separate factories for repository groups that need different policies. ### Sizing a factory @@ -55,33 +55,21 @@ Warp Factories is designed for engineering teams with repeatable work that exten * **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs, [Benchmarks](/factories/benchmarks/) compare fixed tasks across configurations, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into follow-up work the factory proposes for review. * **Infrastructure control** - Choose Warp-hosted or managed self-hosted execution on an eligible Enterprise plan. The [infrastructure and security](/factories/infrastructure-and-security/) page compares execution models and links to the self-hosting setup path, as well as available inference and credential controls. -## How Warp Factories relates to other Warp products +## How Warp Factories fits into Warp -| Product | How it relates | -| --- | --- | -| **Warp** | The interactive terminal where you develop locally with agents and code review. A factory runs independently in the cloud. | -| **Warp Agent** | Warp's built-in agent harness. A factory's agents can run on it or on another supported harness. | -| **{VARS.WARP_CLI}** | Runs the Warp Agent in any terminal and exchanges work with a factory through the Factory MCP. | -| **{VARS.WARP_AUTOMATION_PLATFORM}** | Provides the cloud runs, runners, integrations, secrets, [multi-agent orchestration](/platform/orchestration/), and APIs that a factory assembles into one workflow. | - -## The platform behind a factory - -Warp Factories is built on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/), Warp's programmable system for running and coordinating agents at scale. A factory doesn't replace the platform; it assembles the platform's primitives into one standing workflow, so what you already know about cloud agents carries over: +Warp Factories builds on the same agent infrastructure used across Warp. Every factory agent produces a standard [cloud agent run](/platform/), so the same APIs, runners, models, security controls, and observability apply. -* **Runs** - Every factory agent executes as a [cloud agent run](/platform/), with the same run records and [session sharing](/platform/viewing-cloud-agent-runs/) as any other cloud agent. -* **Execution** - [Runners](/factories/runners/) provide the compute each agent works on, and eligible Enterprise teams can route execution to [managed self-hosted workers](/factories/self-hosting/). -* **Agent configuration** - Each agent runs on a supported [harness](/platform/harnesses/) and model, with [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/) scoping what it can reach. -* **Billing** - A factory's runs consume [platform credits](/support-and-community/plans-and-billing/platform-credits/) the same way as any other cloud agent run. - -The factory layer adds the workflow on top: the foreman and its agents, work items that carry each request across runs, definitions as code, default automations for connected tools, and the Scorer and Self-improvement loop. - -Use a standalone [cloud agent](/platform/) for a single task or one-trigger automation. Any agent can spawn children with [multi-agent orchestration](/platform/orchestration/) without a factory. Use a factory for standing, multi-stage work that needs named agents with separate configuration and one place to route, measure, and improve the process. +| Product | Role | +| --- | --- | +| **Warp** | The interactive development experience for local work with agents and code review. | +| **Warp Agent** | The built-in agent harness that can power an individual factory agent. | +| **Warp Factories** | Standing multi-agent workflows for software development. | ## Key terms Setup gives a factory and its foreman the same name by default, so it's easy to mistake one for the other. Here's how the terms differ: -* **factory** - An individual deployed software factory, built on Warp Factories infrastructure and connecting your repositories and tools to a team of agents. Distinct from Warp Factories, the product, and from the foreman, its coordinating agent. +* **factory** - A standing software development workflow that connects repositories, tools, agents, execution infrastructure, and a measurable workflow. Distinct from Warp Factories, the product, and from the foreman, its coordinating agent. * **foreman** - The coordinating agent inside a factory, and the only one you talk to. It dispatches the other [factory agents](/factories/factory-agents/) and reports back. Every factory has exactly one. * **Foreman name** - The handle your team @-mentions in Slack and Linear to reach the foreman. Setup copies it from the factory's name, so the two usually match even though they're different things. See [Foreman name](/factories/factory-agents/#foreman-name). diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index b27d2a317..b9a3ef57b 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -12,7 +12,7 @@ import { VARS } from '@data/vars'; Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: -A factory is a group of cloud agents that turns incoming requests into pull requests. You talk to one agent, the **foreman**. It picks up the request from wherever it starts, such as Slack, an issue tracker, or a code host, then dispatches the factory's other agents, each owning one part of the software development lifecycle. People stay in the loop at the points that matter: approving specs when needed and merging pull requests. +A factory is a standing software development workflow that connects your repositories and engineering tools to a team of agents and execution infrastructure. You talk to one agent, the **foreman**. It picks up the request from wherever it starts, such as Slack, an issue tracker, or a code host, then dispatches the factory's other agents, each owning one part of the software development lifecycle. People stay in the loop at the points that matter: approving specs when needed and merging pull requests. In this quickstart, you will create a factory and take one small work item from prompt to pull request in less than 10 minutes. diff --git a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx index a7a3ff042..0a70e0ddf 100644 --- a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx @@ -17,7 +17,7 @@ Use multiple coding agents, including Warp Agent, Claude Code, Codex, and other * **Local parallel sessions** - run Warp Agent, Claude Code, Codex, OpenCode, or another CLI agent in separate tabs or panes. * **Isolated worktrees** - give each agent its own Git worktree and branch so parallel edits do not collide. -* **{VARS.WARP_AUTOMATION_PLATFORM} cloud orchestration** - use `/orchestrate`, `/plan`, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.API_SDK_NAME} to fan work out to child agents in cloud environments. +* **{VARS.WARP_AUTOMATION_PLATFORM} cloud orchestration** - use `/orchestrate`, `/plan`, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.WARP_PLATFORM_API} to fan work out to child agents in cloud environments. The best multi-agent workflows have one thing in common: each agent owns a clear slice of work, reports back with validation results, and hands off a branch, diff, PR, or concise finding you can review. @@ -217,7 +217,7 @@ Use cloud agents when the work is long-running, resource-intensive, easy to shar ``` 2. Use `/plan` for larger changes where you want to review the plan, orchestration config, child ownership, and merge strategy before agents launch. -3. For repeatable or unattended workflows, start the parent from the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.API_SDK_NAME}. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) for launch options. +3. For repeatable or unattended workflows, start the parent from the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.WARP_PLATFORM_API}. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) for launch options. 4. Inspect parent and child runs from the [{VARS.WEB_APP}](/platform/oz-web-app/) or the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app. Cloud orchestration is the best fit when you need: @@ -255,7 +255,7 @@ Explore related guides and features: * [How to review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/) — review and refine the code your agents produced * [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) — give reviewers the agent context behind a PR * [Multi-agent orchestration](/platform/orchestration/) — coordinate parent and child agents across local and cloud runs -* [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) — start orchestrated runs from Warp, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.API_SDK_NAME} +* [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) — start orchestrated runs from Warp, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.WARP_PLATFORM_API} * [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) — install both agents if you haven't already * [Claude Code in Warp](https://www.warp.dev/agents/claude-code) — overview of Claude Code support in Warp * [Codex in Warp](https://www.warp.dev/agents/codex) — overview of Codex support in Warp diff --git a/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx index b41efbb88..3cddbfada 100644 --- a/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx @@ -29,7 +29,7 @@ Use this table to decide where an unattended agent should start. | GitHub | Someone should delegate work by mentioning `@warp-agent` on an issue, pull request, or review comment. | [GitHub integration](/platform/integrations/github/) | GitHub thread comments, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and the shared run session | | GitHub Actions | A repository event, PR workflow, issue workflow, or CI failure should start the agent. | [GitHub Actions](/platform/integrations/github-actions/) | GitHub Actions logs, PR or issue comments, {VARS.WEB_APP}, and cloud agent runs | | {VARS.WARP_AGENT_CLI} | You want to start a named cloud run from a terminal, script, or local automation. | [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/#running-agents-remotely-oz-agent-run-cloud) | CLI output, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and cloud agent session links | -| {VARS.API_SDK_NAME} | Your internal system should create, query, or monitor runs programmatically. | [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) | Your system, API results, {VARS.WEB_APP}, and run sessions | +| {VARS.WARP_PLATFORM_API} | Your internal system should create, query, or monitor runs programmatically. | [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) | Your system, API results, {VARS.WEB_APP}, and run sessions | ## Choose a workflow pattern @@ -82,7 +82,7 @@ The GitHub Action can pass event data, prior step output, and repository context ### Start runs from scripts or internal systems -Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/#running-agents-remotely-oz-agent-run-cloud) for scripts and terminal workflows. Use the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) when another service should create or monitor runs. This is useful for: +Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/#running-agents-remotely-oz-agent-run-cloud) for scripts and terminal workflows. Use the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) when another service should create or monitor runs. This is useful for: * internal dashboards * custom webhooks @@ -112,7 +112,7 @@ Unattended does not mean invisible. Use these surfaces to review what happened: * [{VARS.WEB_APP}](/platform/oz-web-app/) - View runs, schedules, run metadata, and session transcripts from a browser or mobile device. * [Managing cloud agents](/platform/managing-cloud-agents/) - Filter runs by source, status, day, creator, or trigger. * [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) - Inspect the prompt, plan, commands, logs, output, and follow-up messages where available. -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Query runs and build internal monitoring around status, runtime, or outcomes. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - Query runs and build internal monitoring around status, runtime, or outcomes. When a run creates a PR, include the cloud run link in the PR description or a comment. See [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) for a template. diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx index 55588cff3..28cbe86a2 100644 --- a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -67,7 +67,7 @@ With GitHub Actions, your factory already has event-based triggers. The {VARS.WA * **Slack** — Teammates can kick off a run by mentioning `@warp` in a Slack thread. Useful for one-off requests that don't need the full label workflow. See [Slack integration](/platform/integrations/slack). * **Linear** — When an issue in Linear reaches a specific status, a cloud agent run starts automatically. Useful for teams that track work in Linear rather than GitHub Issues. See [Linear integration](/platform/integrations/linear). * **Scheduled agents** — For the outer improvement loop (which runs on a cadence rather than an event), use a scheduled cloud agent. See [Scheduled agents](/platform/triggers/scheduled-agents). -* **{VARS.API_SDK_NAME}** — For custom triggers — webhooks, internal dashboards, other events — use the [{VARS.API_SDK_NAME}](/factories/api-and-sdk) to start runs programmatically. +* **{VARS.WARP_PLATFORM_API}** — For custom triggers — webhooks, internal dashboards, other events — use the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk) to start runs programmatically. ## 4. Monitor factory runs diff --git a/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx b/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx index d5641e581..c54df95a2 100644 --- a/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx +++ b/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx @@ -8,14 +8,14 @@ sidebar: --- import { VARS } from '@data/vars'; -Build a Mattermost bot that sends work to a [Warp factory](/factories/) and posts progress back into the thread where it started, the same experience Warp's own [Slack integration](/factories/integrations/slack/) gives teams that use Slack. Warp doesn't ship a Mattermost integration directly, so this guide uses the [factory API](/factories/factory-api/) to build the equivalent yourself. It takes about 20 minutes if you already have a Mattermost bot account and a factory set up. +Build a Mattermost bot that sends work to a [Warp factory](/factories/) and posts progress back into the thread where it started, the same experience Warp's own [Slack integration](/factories/integrations/slack/) gives teams that use Slack. Warp doesn't ship a Mattermost integration directly, so this guide uses [factory endpoints](/factories/factory-api/) to build the equivalent yourself. It takes about 20 minutes if you already have a Mattermost bot account and a factory set up. ## Prerequisites * **A Warp Factories factory** - [Set up a factory](/factories/quickstart/) before starting; this guide dispatches work to an existing factory rather than creating one. * **A Warp API key** - Create an [agent API key](/agents/cli/oz-cli/api-keys/#personal-vs-agent-keys) rather than a personal key, so the bot's requests aren't tied to your individual account. * **A Mattermost bot account and access token** - Create one from your Mattermost System Console under **Integrations** > **Bot Accounts**, and generate a personal access token for it. Mattermost's own [bot accounts documentation](https://developers.mattermost.com/integrate/reference/bot-accounts/) covers the exact steps, since they vary by Mattermost version and hosting setup. -* **The {VARS.API_SDK_NAME} Python SDK** - Install it with `pip install oz-agent-sdk`. If you're working in another language, the [factory API page](/factories/factory-api/) shows the equivalent REST calls. +* **The {VARS.WARP_PLATFORM_API} Python SDK** - Install it with `pip install oz-agent-sdk`. If you're working in another language, [factory endpoints](/factories/factory-api/) show the equivalent REST calls. ## 1. Store your credentials @@ -28,7 +28,7 @@ export MATTERMOST_WEBHOOK_TOKEN=YOUR_MATTERMOST_WEBHOOK_TOKEN export MATTERMOST_URL=https://YOUR_MATTERMOST_SERVER ``` -The bot uses the Warp API key to call the factory API, the bot token to post replies back into the channel, and the webhook token to confirm each inbound request actually came from Mattermost. +The bot uses the Warp API key to call factory endpoints, the bot token to post replies back into the channel, and the webhook token to confirm each inbound request actually came from Mattermost. ## 2. Create an outgoing webhook in Mattermost @@ -167,6 +167,6 @@ Call `check_and_report` from a scheduled job (a cron-triggered script, or a ligh You've built a Mattermost bot that discovers a factory by name, dispatches tasks with source context attached, and routes replies to the run that's already in progress. From here: -* [Use the factory API](/factories/factory-api/) - The full discover-and-dispatch reference this guide builds on. +* [Use factory endpoints](/factories/factory-api/) - The full discover-and-dispatch reference this guide builds on. * [Connect your factory](/factories/connect-your-factory/) - Compare this custom integration against Warp's built-in intake sources. -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Full endpoint reference for run status, follow-ups, and cancellation. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - Full endpoint reference for run status, follow-ups, and cancellation. diff --git a/src/content/docs/platform/agents.mdx b/src/content/docs/platform/agents.mdx index 7ac6aa772..a6ffb6406 100644 --- a/src/content/docs/platform/agents.mdx +++ b/src/content/docs/platform/agents.mdx @@ -18,7 +18,7 @@ A run executes as a cloud agent when it's authenticated with an [agent API key]( * **Schedules** — Cron-style recurring runs. See [Scheduled agents](/platform/triggers/scheduled-agents/). * **Integrations** — Slack mentions, Linear issue updates, GitHub Actions workflow steps. See [Integrations](/platform/integrations/). -* **API and SDK** — Programmatic runs from your own backend, scripts, or webhooks via the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/). +* **API and SDK** — Programmatic runs from your own backend, scripts, or webhooks via the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/). * **CLI** — `oz agent run-cloud` from a developer machine, CI pipeline, or self-hosted worker. See the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/). Each run is tracked in the <a href={`${VARS.WEB_APP_URL}/runs`}>{VARS.DASHBOARD}</a> with its trigger source, the environment it ran in, and the full transcript. @@ -76,7 +76,7 @@ Cloud agents — and individual runs — can also be granted specific capabiliti * [Environments](/platform/environments/) - The runtime context (Docker image, repos, setup commands) a cloud agent uses. * [Multi-agent orchestration](/platform/orchestration/) - Coordinate a parent cloud agent and its children across local and cloud runs. * [API keys](/agents/cli/oz-cli/api-keys/) - Create personal and agent API keys. -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - Programmatic access to the cloud agent endpoints. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - Programmatic access to the cloud agent endpoints. * [Federated identity tokens](/agents/cli/oz-cli/federate/) - Issue OIDC tokens from inside a run. * [{VARS.WEB_APP}](/platform/oz-web-app/) - Manage cloud agents and inspect their runs in the web UI. * [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls. diff --git a/src/content/docs/platform/architecture.mdx b/src/content/docs/platform/architecture.mdx index 26e455d24..a14e8f706 100644 --- a/src/content/docs/platform/architecture.mdx +++ b/src/content/docs/platform/architecture.mdx @@ -15,7 +15,7 @@ The platform has five layers: clients, the Warp-operated control plane that coor ![Warp stack overview diagram showing clients, the Warp control plane, the data plane, Warp-hosted and customer-hosted execution planes, and external systems](../../../assets/agent-platform/warp-stack-overview.png) * **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/), 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](/factories/api-and-sdk/), a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. +* **APIs** - The control plane's entry points: the [Warp Platform API and SDKs](/factories/developer-tools/), 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, 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](/factories/warp-hosting/). diff --git a/src/content/docs/platform/index.mdx b/src/content/docs/platform/index.mdx index a50628c65..ae7e6747d 100644 --- a/src/content/docs/platform/index.mdx +++ b/src/content/docs/platform/index.mdx @@ -98,7 +98,7 @@ For details on configuring MCP servers for cloud agents, see [MCP Servers](/plat #### API access to tasks -The {VARS.WARP_AUTOMATION_PLATFORM} exposes task visibility via the [**{VARS.API_SDK_NAME}**](/factories/api-and-sdk/), so teams can: +The {VARS.WARP_AUTOMATION_PLATFORM} exposes task visibility via the [**{VARS.WARP_PLATFORM_API}**](/factories/api-and-sdk/), so teams can: * Query which tasks are running or have run. * Fetch task metadata and outcomes. @@ -155,7 +155,7 @@ If your credit balance reaches zero, cloud agent runs will not be able to execut ### Learn more * [Cloud agents quickstart](/platform/quickstart/) — run your first cloud agent with an environment in ~10 minutes. -* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) — CLI, {VARS.API_SDK_NAME}, orchestration, tasks, environments, hosts, integrations, and more. +* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) — CLI, {VARS.WARP_PLATFORM_API}, orchestration, tasks, environments, hosts, integrations, and more. * [Warp Factories](/factories/) — assemble cloud agents into a standing triage-to-merge workflow with named agents, automations, and measurement. * [Harnesses](/platform/harnesses/) — pick between Warp Agent, Claude Code, and Codex for any cloud agent run. * [Agents](/platform/agents/) — cloud agents that own and execute runs on your team. @@ -163,7 +163,7 @@ If your credit balance reaches zero, cloud agent runs will not be able to execut * [Skills as Agents](/platform/skills-as-agents/) — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule. * [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — shows how to run agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. * [Environments](/platform/environments/) — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks. -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. * [Agent Secrets](/platform/secrets/) — covers how to store, scope, and inject credentials into agent runs safely. * [MCP Servers](/platform/mcp/) — how to configure MCP servers for agent tool access and how MCP configuration is applied across runs. * [Deployment Patterns](/factories/deployment-patterns/) (beta) — compares common ways to deploy cloud agents and when to use each. diff --git a/src/content/docs/platform/integrations/cloud-providers.mdx b/src/content/docs/platform/integrations/cloud-providers.mdx index 19fb399b0..16320d869 100644 --- a/src/content/docs/platform/integrations/cloud-providers.mdx +++ b/src/content/docs/platform/integrations/cloud-providers.mdx @@ -300,7 +300,7 @@ Team ID: xyz789 Team Name: My Team ``` -You can also check the user IDs from past runs using the {VARS.API_SDK_NAME}: +You can also check the user IDs from past runs using the {VARS.WARP_PLATFORM_API}: ```bash curl https://app.warp.dev/api/v1/agent/runs -H "Authorization: Bearer $WARP_API_KEY" diff --git a/src/content/docs/platform/orchestration/index.mdx b/src/content/docs/platform/orchestration/index.mdx index a0c97d2cd..82b5b5b2a 100644 --- a/src/content/docs/platform/orchestration/index.mdx +++ b/src/content/docs/platform/orchestration/index.mdx @@ -7,7 +7,7 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent's output. The parent/child model works from the Warp app, the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), and the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/), and supports local, cloud, and mixed execution. +Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent's output. The parent/child model works from the Warp app, the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), and the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), and supports local, cloud, and mixed execution. Watch this walkthrough to see how a cloud agent can coordinate a team of agents in the cloud. @@ -15,7 +15,7 @@ Watch this walkthrough to see how a cloud agent can coordinate a team of agents To start an orchestrated run, see [Running orchestrated agents](/platform/orchestration/multi-agent-runs/). -To orchestrate work inside a [Warp factory](/factories/), dispatch through the [factory API](/factories/factory-api/) instead of calling `POST /agent/runs` with the foreman's `agent_identity_uid` directly. The server resolves the foreman for you, and everything on this page still applies to the run it starts. +To orchestrate work inside a [Warp factory](/factories/), dispatch through [factory endpoints](/factories/factory-api/) instead of calling `POST /agent/runs` with the foreman's `agent_identity_uid` directly. The server resolves the foreman for you, and everything on this page still applies to the run it starts. ## The parent/child model @@ -24,7 +24,7 @@ An orchestrated workflow always has one **parent agent** and one or more **child * **Parent agent** - the agent that decides what work needs to be done, spawns child agents, and (optionally) merges their results. Any agent can become a parent the first time it spawns a child. * **Child agent** - an agent spawned by a parent with its own prompt, environment, and (optionally) a different model or agent runtime. A child runs its own work and reports back; it does not spawn its own children. -Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [{VARS.WEB_APP}](/platform/oz-web-app/), and the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. +Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [{VARS.WEB_APP}](/platform/oz-web-app/), and the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. ### Where parent and child agents can run @@ -63,7 +63,7 @@ Track run state transitions in these places: * **The parent's transcript** - the parent agent receives child state transitions as it runs and reflects them in its own conversation. * **The orchestration pill bar** - in the Warp app, while you're viewing the parent agent, a horizontal pill bar above the agent view header shows the parent on the left and one pill per child. Each pill displays the child's name and a status badge that updates live. Click a pill to switch the pane to that child's conversation in place; click the parent pill to switch back. * **The {VARS.WEB_APP}** - cloud children appear under the parent on the <a href={`${VARS.WEB_APP_URL}/runs`}>Runs page</a> and in the parent's **Sub-agents** tab, with their status updating live. -* **The {VARS.API_SDK_NAME}** - `GET /agent/runs/{runId}` returns the latest state of any run, and `GET /agent/runs?ancestor_run_id=PARENT_RUN_ID` lists every descendant in one call. +* **The {VARS.WARP_PLATFORM_API}** - `GET /agent/runs/{runId}` returns the latest state of any run, and `GET /agent/runs?ancestor_run_id=PARENT_RUN_ID` lists every descendant in one call. ## Messaging between agents @@ -124,13 +124,13 @@ Because every parent and child is tracked as its own conversation or run, the ex * **[Managing cloud agents](/platform/managing-cloud-agents/)** - in the Warp app, the orchestration pill bar above the agent view header lets you switch between the parent and each child while you're viewing the parent. Cloud children also appear as their own rows in the Agent Management Panel list. * **[{VARS.WEB_APP}](/platform/oz-web-app/)** - the Runs page groups cloud children under the parent's row, and the parent's detail pane adds a **Sub-agents** tab. -* **[{VARS.API_SDK_NAME}](/factories/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts). +* **[{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts). * **[Agent notifications](/agents/capabilities/agent-notifications/)** - in-app notifications fire on the parent agent's conversation only. Use the pill bar or the **Sub-agents** tab to drill into a specific child. ## Related pages * [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) - how to start an orchestrated run from the CLI, slash command, web app, or API. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical guidance for splitting tasks, assigning worktrees, validating child output, and handing work off for review. -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - REST endpoints for runs, conversations, and artifacts. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - REST endpoints for runs, conversations, and artifacts. * [Cloud agents overview](/platform/) - what a cloud agent run is and how it fits into the {VARS.WARP_AUTOMATION_PLATFORM}. * [Deployment patterns](/factories/deployment-patterns/) - higher-level deployment models that orchestration composes with. diff --git a/src/content/docs/platform/orchestration/multi-agent-runs.mdx b/src/content/docs/platform/orchestration/multi-agent-runs.mdx index efbf2e416..9878a7f2f 100644 --- a/src/content/docs/platform/orchestration/multi-agent-runs.mdx +++ b/src/content/docs/platform/orchestration/multi-agent-runs.mdx @@ -1,13 +1,13 @@ --- title: Running orchestrated agents -description: Start multi-agent orchestrations from the Warp app, the {{WARP_AGENT_CLI}}, the {{WEB_APP}}, or the {{API_SDK_NAME}}, and inspect parent and child conversations and artifacts. +description: Start multi-agent orchestrations from the Warp app, the {{WARP_AGENT_CLI}}, the {{WEB_APP}}, or the {{WARP_PLATFORM_API}}, and inspect parent and child conversations and artifacts. sidebar: label: "Running orchestrated agents" --- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -An orchestrated run starts with a parent agent that spawns one or more child agents. You can start a parent from the Warp app, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.API_SDK_NAME}. Use orchestrated runs to review a plan before fan-out, execute children locally or in the cloud, and inspect parent and child conversations as they work. +An orchestrated run starts with a parent agent that spawns one or more child agents. You can start a parent from the Warp app, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.WARP_PLATFORM_API}. Use orchestrated runs to review a plan before fan-out, execute children locally or in the cloud, and inspect parent and child conversations as they work. Watch this walkthrough to see how to start and inspect an orchestrated agent run from Warp. @@ -18,7 +18,7 @@ Watch this walkthrough to see how to start and inspect an orchestrated agent run Pick where the parent will run. Every orchestration starts with a single parent that spawns children: * **Parent in the Warp app** - use the `/orchestrate` or `/plan` slash command. This is the fastest way to try orchestration. -* **Parent in the cloud** - trigger the parent through the {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/), any [integration](/platform/integrations/) such as [Slack](/platform/integrations/slack/) or [Linear](/platform/integrations/linear/), or a [schedule](/platform/triggers/scheduled-agents/). The parent runs in an environment and spawns children from there. +* **Parent in the cloud** - trigger the parent through the {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), any [integration](/platform/integrations/) such as [Slack](/platform/integrations/slack/) or [Linear](/platform/integrations/linear/), or a [schedule](/platform/triggers/scheduled-agents/). The parent runs in an environment and spawns children from there. Cloud parents that spawn cloud children need access to one or more [environments](/platform/environments/) the children can run in. To keep child execution on your own infrastructure, route those children to a [self-hosted worker](/factories/self-hosting/). @@ -79,7 +79,7 @@ The parent run starts and children appear in the Runs list as the parent spawns Spawn the parent with `POST /agent/runs`. Children can either be spawned by the parent agent at runtime, or you can spawn each child explicitly from your code and link it to the parent with `parent_run_id`. Once they're running, coordination between the parent and its children flows through Warp's durable agent-to-agent messaging - see [Messaging between agents](/platform/orchestration/#messaging-between-agents) for the model. -This section spawns a standalone parent run. If the parent you want to start is a [Warp factory](/factories/)'s foreman, use the [factory API](/factories/factory-api/) to dispatch by factory UID instead of looking up the foreman's `agent_identity_uid` and calling `POST /agent/run` directly. +This section spawns a standalone parent run. If the parent you want to start is a [Warp factory](/factories/)'s foreman, use [factory endpoints](/factories/factory-api/) to dispatch by factory UID instead of looking up the foreman's `agent_identity_uid` and calling `POST /agent/run` directly. ### Agent-driven orchestration @@ -151,7 +151,7 @@ done ## Retrieving conversations and artifacts -Every parent and child started through the {VARS.API_SDK_NAME} is tracked as a {VARS.PLATFORM_RUN}. Run responses include the run's `state`, `parent_run_id` (set on children only), `conversation_id`, `session_link`, and an `artifacts` array of any pull requests, plans, screenshots, or files the run produced. Use the same endpoints you'd use for any other run: +Every parent and child started through the {VARS.WARP_PLATFORM_API} is tracked as a {VARS.PLATFORM_RUN}. Run responses include the run's `state`, `parent_run_id` (set on children only), `conversation_id`, `session_link`, and an `artifacts` array of any pull requests, plans, screenshots, or files the run produced. Use the same endpoints you'd use for any other run: * **List every descendant of a parent** - `GET /api/v1/agent/runs?ancestor_run_id=YOUR_PARENT_RUN_ID`. From the CLI: `oz run list --ancestor-run YOUR_PARENT_RUN_ID`. * **Get one run's details and artifacts** - `GET /api/v1/agent/runs/YOUR_RUN_ID`. @@ -194,7 +194,7 @@ Self-hosted, local, and GitHub Action runs cannot be cancelled through this endp * [Multi-agent orchestration](/platform/orchestration/) - parent/child model, run state transitions, and common patterns. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical task decomposition, worktree ownership, validation, and review handoff guidance. * [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) - command reference for `oz agent run-cloud` and `oz run`. -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - full HTTP reference and typed SDKs. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - full HTTP reference and typed SDKs. * [Managing cloud agents](/platform/managing-cloud-agents/) - how parent and child runs appear in the Agent Management Panel in the Warp app and the Runs page in the {VARS.WEB_APP}. * [Scheduled agents](/platform/triggers/scheduled-agents/) - start a recurring cloud parent that fans out children on a cron cadence. * [Self-hosting](/factories/self-hosting/) - keep parent or child execution on your infrastructure while Warp tracks the runs. diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index 7243c720d..aa656eee6 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -54,7 +54,7 @@ The [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) starts and manages runs where t ## API and SDKs -The [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) creates and inspects tasks over HTTP: submit a prompt with optional configuration, poll status, and fetch results with full provenance. Teams use it to start agents from incident tooling and internal systems, build dashboards over run history, and coordinate large batches of runs. Official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs add typed requests and responses, built-in retries, and consistent errors. Start with an SDK unless you need full control over your HTTP client. +The [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) creates and inspects tasks over HTTP: submit a prompt with optional configuration, poll status, and fetch results with full provenance. Teams use it to start agents from incident tooling and internal systems, build dashboards over run history, and coordinate large batches of runs. Official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs add typed requests and responses, built-in retries, and consistent errors. Start with an SDK unless you need full control over your HTTP client. ## Secrets @@ -74,4 +74,4 @@ Runs pick up your team's shared setup no matter what triggered them: [MCP server * [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. -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) - drive the platform programmatically. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - drive the platform programmatically. diff --git a/src/content/docs/platform/oz-web-app.mdx b/src/content/docs/platform/oz-web-app.mdx index 131cfca2e..12fc8807d 100644 --- a/src/content/docs/platform/oz-web-app.mdx +++ b/src/content/docs/platform/oz-web-app.mdx @@ -252,4 +252,4 @@ For detailed integration setup instructions, see [Slack](/platform/integrations/ * [Environments](/platform/environments/) — Configure runtime context for cloud agents * [Managing Cloud Agents](/platform/managing-cloud-agents/) — Monitor agent activity and inspect runs * [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Command-line interface for running agents -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — Programmatic access to cloud agents +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — Programmatic access to cloud agents diff --git a/src/content/docs/platform/quickstart.mdx b/src/content/docs/platform/quickstart.mdx index 45bbc2d73..dc62652c9 100644 --- a/src/content/docs/platform/quickstart.mdx +++ b/src/content/docs/platform/quickstart.mdx @@ -114,7 +114,7 @@ Now that you've run your first cloud agent, try these next steps: * [**Trigger agents from Slack or Linear**](/platform/integrations/quickstart/) - Connect Warp to team tools so mentions and issue updates can launch cloud agent runs. * [**Orchestrate multiple agents**](/platform/orchestration/multi-agent-runs/) - Fan work out across parent and child agents for large refactors, PR review swarms, and parallel package migrations. * [**Turn successful prompts into reusable skills**](/platform/skills-as-agents/) - Save repeatable agent workflows and run them again from the CLI, web app, API, or a schedule. -* [**Build programmatic automations**](/factories/api-and-sdk/quickstart/) - Start cloud agent runs from your own systems with the {VARS.API_SDK_NAME}. +* [**Build programmatic automations**](/factories/api-and-sdk/quickstart/) - Start cloud agent runs from your own systems with the {VARS.WARP_PLATFORM_API}. For example, schedule a recurring agent from the CLI: diff --git a/src/content/docs/platform/secrets.mdx b/src/content/docs/platform/secrets.mdx index 528e53d30..d11582d61 100644 --- a/src/content/docs/platform/secrets.mdx +++ b/src/content/docs/platform/secrets.mdx @@ -292,7 +292,7 @@ Individual runs can override which secrets the run receives by listing them on t * **Explicit list of secret names** - Only the listed secrets are injected. Any other secrets the caller can access are skipped for this run. * **Empty list** - The run opts out of all secret injection. No managed secrets are injected, even for triggers that would otherwise receive them. -Run-level scoping is exposed through the public REST API on the run config. See the [{VARS.API_SDK_NAME} reference](/factories/api-and-sdk/) for the exact field and shape. +Run-level scoping is exposed through the public REST API on the run config. See the [{VARS.WARP_PLATFORM_API} reference](/factories/api-and-sdk/) for the exact field and shape. :::note Secret names that don't exist in the caller's scope are silently skipped at injection time rather than failing the run. The run detail view surfaces any references that were requested but not resolved so you can spot typos or stale names. diff --git a/src/content/docs/platform/skills-as-agents.mdx b/src/content/docs/platform/skills-as-agents.mdx index 56ec7cb5c..d70e0fa49 100644 --- a/src/content/docs/platform/skills-as-agents.mdx +++ b/src/content/docs/platform/skills-as-agents.mdx @@ -54,7 +54,7 @@ For cloud agent runs (`oz agent run-cloud`), skills are discovered from reposito 3. **The skill appears** in the Agents list in the {VARS.WEB_APP} :::note -You can also list available skills programmatically using the `GET /agent` endpoint. See the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) reference for details. +You can also list available skills programmatically using the `GET /agent` endpoint. See the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) reference for details. ::: ### Extra skill directories in cloud runs @@ -167,4 +167,4 @@ Suggested skills appear on the Agents page under the **Suggested** filter. * [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [{VARS.WEB_APP}](/platform/oz-web-app/) — Visual interface for managing cloud agents * [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Command-line interface for running agents -* [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) — Programmatic access to cloud agents +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — Programmatic access to cloud agents diff --git a/src/content/docs/platform/team-access-billing-and-identity.mdx b/src/content/docs/platform/team-access-billing-and-identity.mdx index 413c04936..0ff3590b0 100644 --- a/src/content/docs/platform/team-access-billing-and-identity.mdx +++ b/src/content/docs/platform/team-access-billing-and-identity.mdx @@ -38,7 +38,7 @@ Individual users can run cloud agents via the CLI or API without being part of a **How it works:** -* Run agents using `oz agent run-cloud` or the {VARS.API_SDK_NAME} +* Run agents using `oz agent run-cloud` or the {VARS.WARP_PLATFORM_API} * Credits are drawn from your Warp credits (including cloud agent credits, when applicable) * Agents execute on Warp-hosted infrastructure diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx index 9f0686126..f70d419d6 100644 --- a/src/content/docs/platform/transitioning-from-oz.mdx +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -1,36 +1,42 @@ --- title: Transitioning from the {{WEB_APP}} description: >- - Continue supported legacy cloud-agent workflows and decide whether Warp - Factories fits new multi-stage development work. + Understand how legacy web app, CLI, SDK, and API workflows remain supported + while Warp Factories becomes the path for new software factories. sidebar: label: "Transitioning from the {{WEB_APP}}" --- import { VARS } from '@data/vars'; -Existing {VARS.WARP_AUTOMATION_PLATFORM} workflows remain supported. You don't need to change an existing workflow to use Warp Factories. +Existing users do not need to take action to keep using their current workflows. Warp Factories is the path for new standing, multi-stage software development workflows. -For new multi-stage development workflows, use Warp Factories. A factory builds on the {VARS.WARP_AUTOMATION_PLATFORM} to route work through specialized agents, add review stages, and show the progress of work. +## Current status and future direction -## Where to manage work +| Surface | Current status | Future direction | +| --- | --- | --- | +| **{VARS.WEB_APP}** | Existing workflows continue to work. | Existing workflows remain supported. Migration guidance will be available over time. | +| **{VARS.WARP_AGENT_CLI} (`oz`)** | Existing commands continue to work. | Relevant functionality moves toward the {VARS.WARP_CLI}. Warp will publish migration guidance before support changes. | +| **{VARS.WARP_CLI} (`warp`)** | Available for its current supported functionality. | The preferred direction for CLI functionality. | +| **`oz-sdk-python` and `oz-sdk-typescript`** | Existing SDK packages continue to work. | Packages may be renamed or repackaged under Warp with migration guidance. | +| **{VARS.WARP_PLATFORM_API}** | Existing endpoints continue to work; no endpoint migration is required. | Documentation and naming may change while compatibility remains. | +| **New software factories** | Use [Warp Factories](https://platform.warp.dev) for new multi-stage development workflows. | Warp Factories remains the primary product experience for software factories. | -* **Existing {VARS.WARP_AUTOMATION_PLATFORM} workflows** - Continue using the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> for existing cloud agents, environments, schedules, integrations, and runs. -* **New factory workflows** - Use the <a href={VARS.FACTORY_WEB_APP_URL}>factory dashboard</a> to build and operate multi-stage development workflows. Start with the [Warp Factories overview](/factories/) or the [factory quickstart](/factories/quickstart/). +## Moving an existing workflow -## CLI, API, and SDK support +### Existing web app workflows -Existing interfaces remain supported: +Continue using the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> for existing cloud agents, environments, schedules, integrations, and runs. Moving an existing workflow into a factory is optional and evaluated case by case with an engineering DRI. -* **{VARS.WARP_AGENT_CLI}** - Existing `oz` commands continue to work. -* **{VARS.API_SDK_NAME}** - Existing API endpoints and SDK packages continue to work. -* **Cloud-agent configuration** - Existing agents, environments, schedules, integrations, API keys, and secrets remain available. +### CLI functionality -## Moving an existing workflow into a factory +Continue using `oz` commands for existing workflows. Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) for current command reference and the [{VARS.WARP_CLI}](/agents/cli/) for current `warp` functionality. -Moving an existing {VARS.WARP_AUTOMATION_PLATFORM} workflow into a factory is optional. Each workflow has different integrations, configuration, and operating requirements, so work with an engineering DRI to evaluate the move. Warp will publish guidance before any support change. +### SDK packages and API + +The official SDK repositories retain their current package names: [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript). Existing API integrations remain compatible as documentation moves to the [{VARS.WARP_PLATFORM_API}](/factories/developer-tools/). ## Related pages * [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) - Configure standalone cloud-agent workflows. * [Warp Factories overview](/factories/) - Build and operate a standing software factory. -* [Factory dashboard](/factories/factory-dashboard/) - Inspect work items, runs, and factory settings. +* [{VARS.WARP_PLATFORM_API} & SDKs](/factories/developer-tools/) - Use factory endpoints, Agent & run endpoints, SDKs, and API errors. diff --git a/src/content/docs/platform/unmanaged-execution.mdx b/src/content/docs/platform/unmanaged-execution.mdx index eadd5dc62..15df82c37 100644 --- a/src/content/docs/platform/unmanaged-execution.mdx +++ b/src/content/docs/platform/unmanaged-execution.mdx @@ -123,7 +123,7 @@ Unmanaged agents are tracked on Warp's backend. Each run creates a persistent se * **View** in the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>. * **Attach to** via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer. -* **Query** through the [{VARS.API_SDK_NAME}](/factories/api-and-sdk/) for custom dashboards or monitoring. +* **Query** through the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) for custom dashboards or monitoring. Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/platform/mcp/), [secrets](/platform/secrets/), Warp Drive context, and saved prompts all apply. diff --git a/src/content/docs/support-and-community/plans-and-billing/credits.mdx b/src/content/docs/support-and-community/plans-and-billing/credits.mdx index 4d4cdf2dc..6d42f9ee4 100644 --- a/src/content/docs/support-and-community/plans-and-billing/credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/credits.mdx @@ -129,7 +129,7 @@ The following scenarios use compute credits: * **First-party integrations** - Running agents through Warp's integrations (Slack, Linear, GitHub, and others) * **Cloud agent runs** - Using `oz agent run-cloud` via the CLI -* **{VARS.API_SDK_NAME}** - Running agents through Warp's API +* **{VARS.WARP_PLATFORM_API}** - Running agents through Warp's API * **Cloud Mode** - Running an agent from Cloud Mode in the Warp app ### Not eligible for compute credits diff --git a/src/data/vars.ts b/src/data/vars.ts index eb2dab80c..41058f032 100644 --- a/src/data/vars.ts +++ b/src/data/vars.ts @@ -7,9 +7,8 @@ // Use the future/conceptual name as the key; the value holds the current string. export const VARS = { - // Platform — renamed 8/18. The remaining Oz-valued keys below are the - // deliberate 10/6 holdouts: the `oz` binary and the Oz v1 webapp keep their - // names until that date, so they are NOT stale, they are pending. + // The `oz` binary and Oz web app are supported legacy surfaces. Their names + // remain in place while Warp publishes transition guidance for each surface. // // IMPORTANT: "Automation Platform" is a common-noun phrase, not a proper // noun like "Oz" was. Referential uses need a definite article in the prose @@ -17,9 +16,9 @@ export const VARS = { // attributive uses do not ("{{…}} settings", "{{…}}-hosted"). style_lint // enforces this. Do not add a bare referential use. WARP_AUTOMATION_PLATFORM: "Automation Platform", - WARP_AGENT_CLI: "Oz CLI", // the `oz` binary — holds until 10/6, then "Warp Agent CLI" - WEB_APP: "Oz web app", // legacy Oz v1 webapp (oz.warp.dev) — holds until 10/6 - WEB_APP_URL: "https://oz.warp.dev", // holds until 10/6, then "https://app.warp.dev" + WARP_AGENT_CLI: "Oz CLI", + WEB_APP: "Oz web app", + WEB_APP_URL: "https://oz.warp.dev", // Renamed per HYC (8/17), same shape as PLATFORM_RUN below: a plain // platform-level term, with "factory dashboard" written directly on pages // that are specifically about a factory. Lowercase: "Warp Factories" is the @@ -41,7 +40,7 @@ export const VARS = { // Kept singular so `{VARS.PLATFORM_RUN}s` pluralizes correctly at the call // sites that do that. PLATFORM_RUN: "cloud agent run", - API_SDK_NAME: "Oz API & SDK", // holds until 10/6, then "Warp API & SDK" + WARP_PLATFORM_API: "Warp Platform API", // Warp Factories web app — a net-new product surface at platform.warp.dev // (soft launch ~2026-08-18), separate from the legacy Oz v1 webapp above. @@ -50,17 +49,8 @@ export const VARS = { FACTORY_WEB_APP: "Warp Factories web app", FACTORY_WEB_APP_URL: "https://platform.warp.dev", - // Warp Agent CLI — the standalone terminal front-end (the `warp` binary). - // Launch name confirmed via the launch blog draft (2026-07-28). - // - // NOTE: the WARP_AGENT_CLI key above was reserved for renaming the Oz CLI to - // this same name. That overlap is now resolved by product direction: on - // 2026-10-06 (the same holdout date as the WARP_AGENT_CLI value above, not - // the 8/18 platform rename) the Oz CLI is retired and wrapped into the Warp - // Agent CLI, leaving a single CLI. The two keys are expected to collapse - // into one at that point. Keeping them separate until the convergence - // ships, since merging them now would rewrite prose across both CLI doc - // surfaces. + // Warp Agent CLI — the preferred direction for CLI functionality (the + // `warp` binary). Relevant Oz CLI functionality will move here over time. WARP_CLI: "Warp Agent CLI", // Feature names (stable — keys and values expected to remain unchanged) diff --git a/src/pages/api.astro b/src/pages/api.astro index 4701d9132..68fd401c4 100644 --- a/src/pages/api.astro +++ b/src/pages/api.astro @@ -36,24 +36,24 @@ const specBaseUrl = (specObject.servers as Array<{ url?: string }> | undefined)? <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <title>Agent API Reference | Warp - + Warp Platform API reference | Warp + - - + + - + - - + + @@ -199,17 +199,17 @@ const specBaseUrl = (specObject.servers as Array<{ url?: string }> | undefined)? document.body.classList.add(resolved === 'dark' ? 'dark-mode' : 'light-mode'); })(); - + llms.txt. -

Warp Automation Platform HTTP API reference

+

Warp Platform API reference

-
+

{specInfo?.title}

{specInfo?.description}

Base URL: {specBaseUrl}

@@ -261,8 +261,8 @@ const specBaseUrl = (specObject.servers as Array<{ url?: string }> | undefined)? // doesn't show a fake "interactive" affordance (per scalar/scalar#5079). defaultOpenAllTags: true, metaData: { - title: 'Agent API Reference', - description: 'Interactive API reference for the Agent API.', + title: 'Warp Platform API reference', + description: 'Interactive reference for the Warp Platform API.', }, // --------------------------------------------------------------- // Scalar consumes `customCss` as a runtime string, so we can't diff --git a/src/pages/openapi.yaml.ts b/src/pages/openapi.yaml.ts index 801660a5b..b846187a1 100644 --- a/src/pages/openapi.yaml.ts +++ b/src/pages/openapi.yaml.ts @@ -4,7 +4,7 @@ import fs from 'node:fs'; export const prerender = true; /** - * Serves the raw Oz Agent API OpenAPI spec at /openapi.yaml so LLMs, crawlers, + * Serves the raw Warp Platform API OpenAPI spec at /openapi.yaml so LLMs, crawlers, * and developer tooling can consume the machine-readable definition directly. * * The spec source of truth is `developers/agent-api-openapi.yaml` (same file diff --git a/src/sidebar.ts b/src/sidebar.ts index 73cf1fd28..5fccca855 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -397,9 +397,23 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // sidebar. Two of these deliberately mirror the Automation Platform tab // next door, since the underlying concepts are the same. items: [ - { slug: 'factories', label: 'Overview' }, - { slug: 'factories/how-factories-work', label: 'How Factories work' }, - { slug: 'factories/quickstart', label: 'Quickstart' }, + { + label: 'Overview', + items: [ + { slug: 'factories', label: 'Overview' }, + { slug: 'factories/how-factories-work', label: 'How Factories work' }, + { slug: 'factories/quickstart', label: 'Quickstart' }, + ], + }, + { + label: 'Measure and improve', + items: [ + { slug: 'factories/measure-and-improve', label: 'Overview' }, + { slug: 'factories/measure-and-improve/scorers', label: 'Scorers' }, + { slug: 'factories/measure-and-improve/self-improvement', label: 'Self-improvement' }, + { slug: 'factories/benchmarks', label: 'Benchmarks' }, + ], + }, { // Parallel to 'Agent configuration' in the Automation Platform tab. // Scoped to the factory itself: who runs the work, how it is defined, @@ -413,6 +427,29 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // agents and Factory skills, not just a filters reference. { slug: 'factories/automations', label: 'Factory automations' }, { slug: 'factories/factory-as-code', label: 'Definitions as code' }, + { + label: 'Infrastructure', + items: [ + { slug: 'factories/infrastructure-and-security', label: 'Overview' }, + { slug: 'factories/deployment-patterns', label: 'Deployment patterns' }, + { slug: 'factories/warp-hosting', label: 'Warp-hosted execution' }, + { slug: 'factories/runners', label: 'Runners' }, + { + label: 'Managed self-hosting', + collapsed: false, + items: [ + { slug: 'factories/self-hosting', label: 'Overview' }, + { slug: 'factories/self-hosting/quickstart', label: 'Quickstart' }, + { slug: 'factories/self-hosting/managed-docker', label: 'Docker backend' }, + { slug: 'factories/self-hosting/managed-kubernetes', label: 'Kubernetes backend' }, + { slug: 'factories/self-hosting/managed-direct', label: 'Direct backend' }, + 'factories/self-hosting/monitoring', + { slug: 'factories/self-hosting/reference', label: 'Worker reference' }, + 'factories/self-hosting/troubleshooting', + ], + }, + ], + }, ], }, { @@ -423,7 +460,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // Integrations > Integrations > Slack. // // 'Connect your factory' leads because it is the overview for this - // group. The direct developer interfaces live in the Developer tools + // group. The direct developer interfaces live in the API & SDKs // group rather than alongside third-party service integrations. label: 'Integrations', items: [ @@ -436,15 +473,15 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ ], }, { - label: 'Developer tools', + label: 'API & SDKs', items: [ { slug: 'factories/developer-tools', label: 'Overview' }, - { slug: 'factories/factory-api', label: 'Factory API' }, - { slug: 'factories/api-and-sdk', label: VARS.API_SDK_NAME }, - { slug: 'factories/api-and-sdk/quickstart', label: 'Quickstart' }, + { slug: 'factories/factory-api', label: 'Factory endpoints' }, + { slug: 'factories/api-and-sdk', label: 'Agent & run endpoints' }, { label: 'API reference', link: '/api' }, - { slug: 'factories/api-and-sdk/demo-sentry-monitoring-with-sdk', label: 'Sentry monitoring with the SDK' }, - { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'API errors' }, + { label: 'Python SDK', link: 'https://github.com/warpdotdev/oz-sdk-python' }, + { label: 'TypeScript SDK', link: 'https://github.com/warpdotdev/oz-sdk-typescript' }, + { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'Errors' }, { slug: 'factories/factory-mcp', label: 'Factory MCP' }, { label: 'Webhooks', @@ -457,55 +494,16 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ ], }, { - label: 'Infrastructure & security', - items: [ - { slug: 'factories/infrastructure-and-security', label: 'Overview' }, - { slug: 'factories/deployment-patterns', label: 'Deployment patterns' }, - { slug: 'factories/warp-hosting', label: 'Warp-hosted execution' }, - { slug: 'factories/runners', label: 'Runners' }, - { - label: 'Managed self-hosting', - collapsed: false, - items: [ - { slug: 'factories/self-hosting', label: 'Overview' }, - { slug: 'factories/self-hosting/quickstart', label: 'Quickstart' }, - { slug: 'factories/self-hosting/managed-docker', label: 'Docker backend' }, - { slug: 'factories/self-hosting/managed-kubernetes', label: 'Kubernetes backend' }, - { slug: 'factories/self-hosting/managed-direct', label: 'Direct backend' }, - 'factories/self-hosting/monitoring', - { slug: 'factories/self-hosting/reference', label: 'Worker reference' }, - 'factories/self-hosting/troubleshooting', - ], - }, - ], - }, - { - // Same label as the Automation Platform tab's group for watching and - // steering runs, because it covers the same ground one level up: the - // factory dashboard is where you watch a factory, and scorers are how - // you measure it. + // The factory dashboard and inbox are operational surfaces. Measurement + // and optimization pages live earlier under 'Measure and improve'. label: 'Management & observability', items: [ { slug: 'factories/factory-inbox', label: 'Factory inbox' }, { slug: 'factories/factory-dashboard', label: 'Factory dashboard' }, - { - label: 'Measure and improve', - collapsed: false, - items: [ - { slug: 'factories/measure-and-improve', label: 'Overview' }, - { slug: 'factories/measure-and-improve/scorers', label: 'Scorers' }, - { slug: 'factories/measure-and-improve/self-improvement', label: 'Self-improvement' }, - { slug: 'factories/benchmarks', label: 'Benchmarks' }, - ], - }, ], }, - // Troubleshooting sits outside the groups near the end of the tab. It was in - // 'Management & observability' next to the dashboard and Scorers pages, - // which read as a sibling of the measurement surfaces rather than as - // the place you go when something is broken. A bare trailing item is - // the same shape the Automation Platform tab uses for its leading - // 'Overview'. + // Keep troubleshooting and legacy transition guidance as direct trailing + // items rather than creating singleton groups. { slug: 'factories/troubleshooting', label: 'Troubleshooting' }, { slug: 'platform/transitioning-from-oz', label: 'Legacy Oz workflows' }, ], From 67f005cd5b4241ca25fd1d0d97c4569cddef7ca6 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 18 Sep 2026 16:35:17 -0600 Subject: [PATCH 38/46] docs: clarify transition review metadata Co-Authored-By: Warp --- .github/workflows/agent-docs-review.yml | 2 ++ src/content/docs/factories/developer-tools.mdx | 3 ++- src/content/docs/platform/transitioning-from-oz.mdx | 2 +- src/data/vars.ts | 6 +++++- 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 235912604..5ea082e98 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -45,6 +45,8 @@ jobs: sudo apt-get install -y gpg curl --fail --location https://releases.warp.dev/linux/keys/warp.asc \ --output /tmp/warpdotdev.asc + # Verified against releases.warp.dev/linux/keys/warp.asc on 2026-09-18. + # Reverify this fingerprint before updating the Warp signing key. test "$( gpg --show-keys --with-colons /tmp/warpdotdev.asc | awk -F: '/^fpr:/ { print $10; exit }' diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx index e845a1254..5f8d2da0b 100644 --- a/src/content/docs/factories/developer-tools.mdx +++ b/src/content/docs/factories/developer-tools.mdx @@ -8,7 +8,7 @@ sidebar: --- import { VARS } from '@data/vars'; -The {VARS.WARP_PLATFORM_API} serves both factories and standalone cloud agent runs. factory endpoints send work to a factory; agent and run endpoints start and manage standalone runs. Both endpoint families use the same API key, API reference, SDKs, and error model. +The {VARS.WARP_PLATFORM_API} serves both factories and standalone cloud agent runs. The factory endpoints send work to a factory; agent and run endpoints start and manage standalone runs. Both endpoint families use the same API key, API reference, SDKs, and error model. ## Choose an API surface @@ -20,6 +20,7 @@ The {VARS.WARP_PLATFORM_API} serves both factories and standalone cloud agent ru * **[API errors](/factories/api-and-sdk/troubleshooting/errors/)** - Resolve error responses by HTTP status and machine-readable code. * **[Factory MCP](/factories/factory-mcp/)** - Exchange work between a factory and a connected coding agent or MCP client. * **[Webhooks](/factories/webhooks/)** - Receive events from systems that can send JSON and route matching deliveries into factory automations. + ## Get started Start with the [API & SDK quickstart](/factories/api-and-sdk/quickstart/) to create and inspect a run. For a production event source, use the [Sentry monitoring example](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) to connect a webhook handler. diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx index f70d419d6..cf0df5846 100644 --- a/src/content/docs/platform/transitioning-from-oz.mdx +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -25,7 +25,7 @@ Existing users do not need to take action to keep using their current workflows. ### Existing web app workflows -Continue using the {VARS.WEB_APP} for existing cloud agents, environments, schedules, integrations, and runs. Moving an existing workflow into a factory is optional and evaluated case by case with an engineering DRI. +Continue using the {VARS.WEB_APP} for existing cloud agents, environments, schedules, integrations, and runs. Moving an existing workflow into a factory is optional. Contact your account team to evaluate the move for your workflow. ### CLI functionality diff --git a/src/data/vars.ts b/src/data/vars.ts index 41058f032..36ff3f24c 100644 --- a/src/data/vars.ts +++ b/src/data/vars.ts @@ -16,6 +16,8 @@ export const VARS = { // attributive uses do not ("{{…}} settings", "{{…}}-hosted"). style_lint // enforces this. Do not add a bare referential use. WARP_AUTOMATION_PLATFORM: "Automation Platform", + // Legacy key retained for existing Oz CLI references. It refers only to the + // `oz` binary; use WARP_CLI for the separate Warp Agent CLI (`warp` binary). WARP_AGENT_CLI: "Oz CLI", WEB_APP: "Oz web app", WEB_APP_URL: "https://oz.warp.dev", @@ -50,7 +52,9 @@ export const VARS = { FACTORY_WEB_APP_URL: "https://platform.warp.dev", // Warp Agent CLI — the preferred direction for CLI functionality (the - // `warp` binary). Relevant Oz CLI functionality will move here over time. + // `warp` binary). This is distinct from WARP_AGENT_CLI, which references + // the legacy Oz CLI (`oz` binary). Relevant Oz CLI functionality will move + // here over time. WARP_CLI: "Warp Agent CLI", // Feature names (stable — keys and values expected to remain unchanged) From 82a60ec498b8cb720d3142936437b46d758e8415 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 18 Sep 2026 16:52:56 -0600 Subject: [PATCH 39/46] docs: tokenize API transition references Co-Authored-By: Warp --- src/content/docs/factories/developer-tools.mdx | 4 ++-- src/content/docs/platform/transitioning-from-oz.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx index 5f8d2da0b..b0e515296 100644 --- a/src/content/docs/factories/developer-tools.mdx +++ b/src/content/docs/factories/developer-tools.mdx @@ -1,7 +1,7 @@ --- -title: Warp Platform API & SDKs +title: "{{WARP_PLATFORM_API}} & SDKs" description: >- - Use the Warp Platform API, SDKs, Factory MCP, and webhooks to integrate + Use the {{WARP_PLATFORM_API}}, SDKs, Factory MCP, and webhooks to integrate factories and cloud agent runs with your tools and services. sidebar: label: "Overview" diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx index cf0df5846..3e094e7bd 100644 --- a/src/content/docs/platform/transitioning-from-oz.mdx +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -19,7 +19,7 @@ Existing users do not need to take action to keep using their current workflows. | **{VARS.WARP_CLI} (`warp`)** | Available for its current supported functionality. | The preferred direction for CLI functionality. | | **`oz-sdk-python` and `oz-sdk-typescript`** | Existing SDK packages continue to work. | Packages may be renamed or repackaged under Warp with migration guidance. | | **{VARS.WARP_PLATFORM_API}** | Existing endpoints continue to work; no endpoint migration is required. | Documentation and naming may change while compatibility remains. | -| **New software factories** | Use [Warp Factories](https://platform.warp.dev) for new multi-stage development workflows. | Warp Factories remains the primary product experience for software factories. | +| **New software factories** | Use Warp Factories for new multi-stage development workflows. | Warp Factories remains the primary product experience for software factories. | ## Moving an existing workflow From d3aa969fa2049a6bb820d53961c35410f8e73b4e Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Fri, 18 Sep 2026 17:26:09 -0600 Subject: [PATCH 40/46] docs: refine factories navigation and transition copy Co-Authored-By: Warp --- .../docs/factories/developer-tools.mdx | 2 +- .../docs/platform/transitioning-from-oz.mdx | 6 ++--- src/sidebar.ts | 27 +++++++++++-------- 3 files changed, 20 insertions(+), 15 deletions(-) diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx index b0e515296..d6dfa9ecf 100644 --- a/src/content/docs/factories/developer-tools.mdx +++ b/src/content/docs/factories/developer-tools.mdx @@ -12,7 +12,7 @@ The {VARS.WARP_PLATFORM_API} serves both factories and standalone cloud agent ru ## Choose an API surface -* **[factory endpoints](/factories/factory-api/)** - Find a factory and send work to it by UID from your application or service. +* **[Factory endpoints](/factories/factory-api/)** - Find a factory and send work to it by UID from your application or service. * **[Agent & run endpoints](/factories/api-and-sdk/)** - Start, monitor, continue, and cancel cloud agent runs from scripts, CI, and backend services. * **[Warp Platform API reference](/api)** - Look up the full HTTP schema, parameters, and responses. * **[Python SDK](https://github.com/warpdotdev/oz-sdk-python)** - Make typed requests from Python. The current package retains its `oz-sdk-python` name. diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx index 3e094e7bd..9a132166c 100644 --- a/src/content/docs/platform/transitioning-from-oz.mdx +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -1,14 +1,14 @@ --- title: Transitioning from the {{WEB_APP}} description: >- - Understand how legacy web app, CLI, SDK, and API workflows remain supported - while Warp Factories becomes the path for new software factories. + Keep existing legacy web app, CLI, SDK, and API workflows while using Warp + Factories for new multi-stage software development workflows. sidebar: label: "Transitioning from the {{WEB_APP}}" --- import { VARS } from '@data/vars'; -Existing users do not need to take action to keep using their current workflows. Warp Factories is the path for new standing, multi-stage software development workflows. +Warp Factories supports new multi-stage software development workflows. Existing users can continue using their current workflows without taking action. ## Current status and future direction diff --git a/src/sidebar.ts b/src/sidebar.ts index 5fccca855..c1f73c83d 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -460,8 +460,8 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // Integrations > Integrations > Slack. // // 'Connect your factory' leads because it is the overview for this - // group. The direct developer interfaces live in the API & SDKs - // group rather than alongside third-party service integrations. + // group. The direct developer interfaces live in Developer tools + // rather than alongside third-party service integrations. label: 'Integrations', items: [ { slug: 'factories/connect-your-factory', label: 'Connect your factory' }, @@ -473,15 +473,20 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ ], }, { - label: 'API & SDKs', + label: 'Developer tools', items: [ - { slug: 'factories/developer-tools', label: 'Overview' }, - { slug: 'factories/factory-api', label: 'Factory endpoints' }, - { slug: 'factories/api-and-sdk', label: 'Agent & run endpoints' }, - { label: 'API reference', link: '/api' }, - { label: 'Python SDK', link: 'https://github.com/warpdotdev/oz-sdk-python' }, - { label: 'TypeScript SDK', link: 'https://github.com/warpdotdev/oz-sdk-typescript' }, - { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'Errors' }, + { + label: 'API & SDKs', + items: [ + { slug: 'factories/developer-tools', label: 'Overview' }, + { slug: 'factories/factory-api', label: 'Factory endpoints' }, + { slug: 'factories/api-and-sdk', label: 'Agent & run endpoints' }, + { label: 'API reference', link: '/api' }, + { label: 'Python SDK', link: 'https://github.com/warpdotdev/oz-sdk-python' }, + { label: 'TypeScript SDK', link: 'https://github.com/warpdotdev/oz-sdk-typescript' }, + { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'Errors' }, + ], + }, { slug: 'factories/factory-mcp', label: 'Factory MCP' }, { label: 'Webhooks', @@ -533,7 +538,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ items: [ { slug: 'platform', label: 'Overview' }, { slug: 'platform/quickstart', label: 'Quickstart' }, - { slug: 'platform/transitioning-from-oz', label: `Transitioning from the ${VARS.WEB_APP}` }, + { slug: 'platform/transitioning-from-oz', label: 'Transitioning from Oz' }, { // Runtime (which agent executes the run) is kept separate from // configuration (how any run is set up) -- HYC review, 8/14. From e61c205c099f847e88d951412d727e58a0515785 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Sat, 19 Sep 2026 17:06:35 -0600 Subject: [PATCH 41/46] docs: audit self-hosting redirect and review CLI Co-Authored-By: Warp --- .../doc_quality_policy/test_agent_docs_review_workflow.py | 1 + .github/workflows/agent-docs-review.yml | 1 + vercel.json | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py index cbb225c65..483bb47cd 100644 --- a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py +++ b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py @@ -46,6 +46,7 @@ def test_review_uses_a_signed_oz_package(self): self.assertIn("0913165C78D5B7A41B42AC657FF7AB39D60F803F", self.workflow) self.assertIn("signed-by=/etc/apt/keyrings/warpdotdev.gpg", self.workflow) self.assertIn("sudo apt-get install -y oz-stable", self.workflow) + self.assertIn("oz --version", self.workflow) if __name__ == "__main__": diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 5ea082e98..fa6946366 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -59,6 +59,7 @@ jobs: EOF sudo apt-get update sudo apt-get install -y oz-stable + oz --version PROMPT="$(cat <<'EOF' Run the review-docs-pr skill against warpdotdev/docs PR #${{ github.event.pull_request.number }} at head SHA ${{ github.event.pull_request.head.sha }}. This PR carries the warpy-factory agent diff --git a/vercel.json b/vercel.json index 74ef548d5..1ee6a3c17 100644 --- a/vercel.json +++ b/vercel.json @@ -5204,7 +5204,7 @@ }, { "source": "/agent-platform/cloud-agents/self-hosting/managed-worker-reference", - "destination": "/platform/self-hosting/", + "destination": "/factories/self-hosting/", "statusCode": 308 }, { From 503bc5feb991e02414dc40054077000e242ccbce Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Sat, 19 Sep 2026 17:36:56 -0600 Subject: [PATCH 42/46] docs: collapse managed self-hosting navigation Co-Authored-By: Warp --- src/sidebar.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/sidebar.ts b/src/sidebar.ts index c1f73c83d..8d87e7333 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -436,7 +436,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/runners', label: 'Runners' }, { label: 'Managed self-hosting', - collapsed: false, + collapsed: true, items: [ { slug: 'factories/self-hosting', label: 'Overview' }, { slug: 'factories/self-hosting/quickstart', label: 'Quickstart' }, From 0cc080553146840ea5fec2e63819737a9b886730 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Sat, 19 Sep 2026 17:45:20 -0600 Subject: [PATCH 43/46] docs: reorder measure and improve navigation Co-Authored-By: Warp --- src/sidebar.ts | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/sidebar.ts b/src/sidebar.ts index 8d87e7333..6adbdebe5 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -405,15 +405,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/quickstart', label: 'Quickstart' }, ], }, - { - label: 'Measure and improve', - items: [ - { slug: 'factories/measure-and-improve', label: 'Overview' }, - { slug: 'factories/measure-and-improve/scorers', label: 'Scorers' }, - { slug: 'factories/measure-and-improve/self-improvement', label: 'Self-improvement' }, - { slug: 'factories/benchmarks', label: 'Benchmarks' }, - ], - }, { // Parallel to 'Agent configuration' in the Automation Platform tab. // Scoped to the factory itself: who runs the work, how it is defined, @@ -452,6 +443,15 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ }, ], }, + { + label: 'Measure & improve', + items: [ + { slug: 'factories/measure-and-improve', label: 'Overview' }, + { slug: 'factories/measure-and-improve/scorers', label: 'Scorers' }, + { slug: 'factories/measure-and-improve/self-improvement', label: 'Self-improvement' }, + { slug: 'factories/benchmarks', label: 'Benchmarks' }, + ], + }, { // 'Integrations' per HYC (8/17), replacing 'Work intake'. // From 8c63ed6c40f85c97ad3e8979e92e9295c587c679 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Sat, 19 Sep 2026 17:50:52 -0600 Subject: [PATCH 44/46] docs: clarify factory definition Co-Authored-By: Warp --- src/content/docs/factories/how-factories-work.mdx | 2 +- src/content/docs/factories/index.mdx | 6 +++--- src/content/docs/factories/quickstart.mdx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index daa8b4c55..435685dcb 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -11,7 +11,7 @@ sidebar: Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: -A factory is a standing software development workflow that connects your repositories and engineering tools to a team of agents and execution infrastructure. It takes in requests, moves them through the stages they need, and turns them into pull requests ready for review. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle. +A factory is a fleet of agents wired to your software development lifecycle. It connects your repositories and tools to move requests through triage, specification, implementation, review, and verification, while people stay in control of key decisions. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle. Deciding which repositories belong in this factory is a separate question. See [sizing a factory](/factories/#sizing-a-factory) for that guidance. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 9c03453b1..afb0a702d 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -13,7 +13,7 @@ import VideoEmbed from '@components/VideoEmbed.astro'; Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. If your team already has access, sign in to the {VARS.FACTORY_WEB_APP}. ::: -A factory is a standing software development workflow that connects your repositories and engineering tools to a team of agents and execution infrastructure. It takes in requests, manages them from triage through review, and turns a growing backlog into mergeable pull requests. Your team stays in the loop to approve specifications and merge each pull request. +A factory is a cloud automation loop around your software development lifecycle. It combines repositories, tools, agents, and execution infrastructure to move requests through triage, specification, implementation, review, and verification, while people stay in control of key decisions. @@ -63,13 +63,13 @@ Warp Factories builds on the same agent infrastructure used across Warp. Every f | --- | --- | | **Warp** | The interactive development experience for local work with agents and code review. | | **Warp Agent** | The built-in agent harness that can power an individual factory agent. | -| **Warp Factories** | Standing multi-agent workflows for software development. | +| **Warp Factories** | Multi-agent workflows for software development. | ## Key terms Setup gives a factory and its foreman the same name by default, so it's easy to mistake one for the other. Here's how the terms differ: -* **factory** - A standing software development workflow that connects repositories, tools, agents, execution infrastructure, and a measurable workflow. Distinct from Warp Factories, the product, and from the foreman, its coordinating agent. +* **factory** - A cloud automation loop around your software development lifecycle. It combines repositories, tools, agents, and execution infrastructure to move requests through the factory workflow. Distinct from Warp Factories, the product, and from the foreman, its coordinating agent. * **foreman** - The coordinating agent inside a factory, and the only one you talk to. It dispatches the other [factory agents](/factories/factory-agents/) and reports back. Every factory has exactly one. * **Foreman name** - The handle your team @-mentions in Slack and Linear to reach the foreman. Setup copies it from the factory's name, so the two usually match even though they're different things. See [Foreman name](/factories/factory-agents/#foreman-name). diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index b9a3ef57b..1babd4d2e 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -12,7 +12,7 @@ import { VARS } from '@data/vars'; Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: -A factory is a standing software development workflow that connects your repositories and engineering tools to a team of agents and execution infrastructure. You talk to one agent, the **foreman**. It picks up the request from wherever it starts, such as Slack, an issue tracker, or a code host, then dispatches the factory's other agents, each owning one part of the software development lifecycle. People stay in the loop at the points that matter: approving specs when needed and merging pull requests. +A factory is a fleet of agents wired to your software development lifecycle. It connects your repositories and tools to move requests through triage, specification, implementation, review, and verification, while people stay in control of key decisions. You talk to one agent, the **foreman**. It picks up the request from wherever it starts, such as Slack, an issue tracker, or a code host, then dispatches the factory's other agents, each owning one part of the software development lifecycle. In this quickstart, you will create a factory and take one small work item from prompt to pull request in less than 10 minutes. From 86d7fe36ce10ac996f3812c6668701e95bdcdf98 Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Sat, 19 Sep 2026 18:04:00 -0600 Subject: [PATCH 45/46] docs: condense factories quickstart Co-Authored-By: Warp --- src/content/docs/factories/quickstart.mdx | 46 +++++++++-------------- 1 file changed, 17 insertions(+), 29 deletions(-) diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 1babd4d2e..412390ea0 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -18,20 +18,13 @@ In this quickstart, you will create a factory and take one small work item from ## What you'll decide -Warp walks you through factory setup. Along the way, you decide: - -* The code host and repositories the factory works on. -* The factory's name and its foreman's @-mention alias. -* Which default agents the foreman can dispatch. -* Whether to connect a chat tool and an issue tracker, or add them later. - -You can change any of these after setup, so a best guess is fine for now. +Setup connects your code host, selects repositories, names the factory and its foreman, and chooses default agents. You can also connect Slack and an issue tracker now or add them later. Every choice can be changed after setup. ## Prerequisites -* **Warp Factories access** - Warp Factories is in Early Access. [Request access](https://www.warp.dev/factories/request-access) for your team. -* **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/). Factory agents consume the team's [credits](/support-and-community/plans-and-billing/platform-credits/). -* **Repository access** - You authorize a code host during setup and choose which repositories the factory can reach. If your organization restricts app installations, ask an owner to approve the connection. See the [GitHub](/factories/integrations/github/) and [GitLab](/factories/integrations/gitlab/) integration guides. +* **Warp Factories access** - [Request Early Access](https://www.warp.dev/factories/request-access) for your team. +* **A Warp team with credits** - The team's [credits](/support-and-community/plans-and-billing/platform-credits/) are consumed by factory agents. +* **Repository access** - Authorize GitHub or GitLab during setup. If your organization restricts app installations, ask an owner to approve the connection. ## Set up your factory @@ -50,40 +43,35 @@ Warp walks you through a setup wizard:
Click + next to Factories to open the setup wizard.
-2. Click **I want to use repos from GitHub** or **I want to use repos from GitLab**, then choose the organization or group you want to connect. +2. Click **I want to use repos from GitHub** or **I want to use repos from GitLab**, then choose the organization or group to connect.
![The Connect a GitHub organization screen, with an already-connected organization shown as an option.](../../../assets/factories/quickstart-connect-organization.png)
Choose the organization or group whose repositories the factory will use. GitLab shows an equivalent screen for groups.
-3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. - - :::note - Group repositories by product surface, not by team or task. For example, group all the repos behind one application. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. - ::: +3. On **Select your repos**, select the repositories the factory works in, then click **Add repos**. Start with one or two repositories that ship together, and add more later. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers.
![The Select your repos screen, searching for repositories by name.](../../../assets/factories/quickstart-select-repos.png)
Search for and select the repositories the factory works in.
-4. Name the factory. This also sets its [**Foreman name**](/factories/factory-agents/#foreman-name), the handle your team @-mentions in Slack and Linear. Keep it short and recognizable, or set your own. The two match by default, but they name different things: the handle reaches the factory's foreman, the agent that coordinates its work. +4. Name the factory. This also sets its [**Foreman name**](/factories/factory-agents/#foreman-name), the handle your team @-mentions in Slack and Linear. The factory and foreman names match by default, but the foreman is the agent that coordinates its work.
![The Give your factory some personality screen, with Factory name and Foreman name fields filled in.](../../../assets/factories/quickstart-name-factory.png)
Name the factory and, optionally, add a description and avatar.
-5. Optionally, connect a chat tool so teammates can hand work to the factory from Slack. You can also skip this step and connect Slack later. See [connect your factory](/factories/connect-your-factory/). -6. Toggle the agents the foreman can dispatch: **Triage**, **Spec**, **Implement**, and **Review**. All four start enabled, and at least one is required. Leave **Implement** on so this quickstart can end in a pull request. See [factory agents](/factories/factory-agents/) for what each does. +5. Toggle the agents the foreman can dispatch: **Triage**, **Spec**, **Implement**, and **Review**. All four start enabled. Leave **Implement** on so this quickstart can end in a pull request. See [factory agents](/factories/factory-agents/) for details.
![The Pick your factory agents screen, with the Foreman and all four default agents shown as enabled.](../../../assets/factories/quickstart-pick-agents.png)
Toggle which default agents the foreman can dispatch.
-7. Optionally, connect an issue tracker so teammates can hand work to the factory from Linear or Jira. You can also skip this step and connect one later. See [connect your factory](/factories/connect-your-factory/). +6. Optionally connect Slack and an issue tracker so teammates can hand work to the factory from the tools they already use. You can add either later from [connect your factory](/factories/connect-your-factory/). Warp creates the factory and opens its [dashboard](/factories/factory-dashboard/). @@ -91,7 +79,7 @@ Warp creates the factory and opens its [dashboard](/factories/factory-dashboard/ _~5 minutes_ -You can request work from the tools your team already uses. Mention the factory in a Slack channel, or assign it an issue in your tracker, and it replies right there. If you skipped the integrations, start a run from the **Runs** page of the factory's [dashboard](/factories/factory-dashboard/) instead. +Send work from Slack or an issue tracker. If you skipped integrations, start a run from the **Runs** page of the factory's [dashboard](/factories/factory-dashboard/). 1. Describe one small, verifiable change and send it: @@ -101,9 +89,9 @@ You can request work from the tools your team already uses. Mention the factory repo's lint check, and open a pull request. ``` - Adapt the pattern to your repository: name the file, the change you expect, and the command that verifies it. A narrow, explicit request makes the first run easy to judge. + Name the file, expected change, and verification command. -2. The foreman picks up the request, dispatches the factory's agents as child runs, and posts progress and questions back where the request started. Follow the foreman's run and the child runs it dispatches on the factory's [Runs page](/factories/factory-dashboard/#inspect-runs). If anything needs your input, such as a spec approval or a finished pull request to review, it also appears in your [inbox](/factories/factory-inbox/). +2. The foreman dispatches the agents needed for the request and posts progress where it started. Follow the foreman and child runs on the factory's [Runs page](/factories/factory-dashboard/#inspect-runs). Requests for input also appear in your [inbox](/factories/factory-inbox/). If you connected Slack, you can follow along there instead: @@ -112,12 +100,12 @@ You can request work from the tools your team already uses. Mention the factory
The factory's Slack app posting progress updates back in the thread where you sent the request.
-3. When the Implement agent finishes, the work item links to the pull request. Review and merge it the way you would any other: a factory hands off at the pull request and never merges for you. +3. When the Implement agent finishes, review and merge the linked pull request as you would any other. ## Next steps -* [**Connect your factory**](/factories/connect-your-factory/) - Route work in from Slack threads, Linear issues, and other intake paths. -* [**Factory MCP**](/factories/factory-mcp/) - Send work to the factory from a coding agent or MCP client. -* [**How Warp Factories work**](/factories/how-factories-work/) - The work-item lifecycle and where people stay in the loop. +* [**Connect your factory**](/factories/connect-your-factory/) - Configure intake sources. +* [**Factory MCP**](/factories/factory-mcp/) - Send work from a coding agent or MCP client. +* [**How Warp Factories work**](/factories/how-factories-work/) - Understand the work-item lifecycle. * [**warp-factory-examples**](https://github.com/warpdotdev/warp-factory-examples) - Complete working definitions to copy, from a single-repo quickstart to the full issue-to-PR lifecycle. -* [**Troubleshooting Warp Factories**](/factories/troubleshooting/) - Fixes for common issues during setup and your first runs. +* [**Troubleshooting Warp Factories**](/factories/troubleshooting/) - Fix common setup and run issues. From e9d18857c86a383750495b75d56c13d382e0a03b Mon Sep 17 00:00:00 2001 From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com> Date: Sat, 19 Sep 2026 18:08:04 -0600 Subject: [PATCH 46/46] docs: remove stale LLM reference set Co-Authored-By: Warp --- astro.config.mjs | 1 - 1 file changed, 1 deletion(-) diff --git a/astro.config.mjs b/astro.config.mjs index 3393454db..0e7f43640 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -228,7 +228,6 @@ export default defineConfig({ { label: 'Enterprise', description: 'Enterprise features, SSO, team management, and security.', paths: ['enterprise/**'] }, { label: 'Getting Started', description: 'Installation, quickstart, and migration guides.', paths: ['index', 'quickstart', 'getting-started/**'] }, { label: 'Knowledge and Collaboration', description: 'Warp Drive, teams, and the Admin Panel.', paths: ['knowledge-and-collaboration/**'] }, - { label: 'API & Reference', description: 'CLI and API reference.', paths: ['reference/**'] }, // All support-and-community/ pages. open-source-licenses.mdx is excluded // globally above (stack overflow in hast-util-to-text); the patch ensures // it's excluded from this custom set as well.