diff --git a/.agents/references/terminology.md b/.agents/references/terminology.md
index 07d5a6af3..d706e963c 100644
--- a/.agents/references/terminology.md
+++ b/.agents/references/terminology.md
@@ -366,7 +366,7 @@ Docs match the screen; the fix belongs in the app.
*Usage note:* Not a second concept. Use "task" only where the MCP surface forces it, and say once on the page that a task is the factory's work item. Never introduce "task" as a distinct unit of work.
- **stages** — The phases a work item moves through, named as the factory dashboard's **Activity** view names them: **Triage**, **Planning**, **Building**, and **Reviewing**, plus the terminal stages **Complete** and **Cancelled**.
- *Usage note:* Stage names are not agent names. The spec agent works the Planning stage, the implement agent works the Building stage, and the review agent works the Reviewing stage. Write stages with the dashboard's names so docs and screen agree; write agents with their own names (triage, spec, implement, review).
+ *Usage note:* Stage names are not agent names. The spec agent works the planning stage, the implement agent works the building stage, and the review agent works the reviewing stage. Use lowercase for stages in explanatory prose. Preserve the displayed spelling and capitalization when referencing exact UI labels, filters, or status values; sentence-initial and diagram labels may also begin with capitals. Write agents with their own names (triage, spec, implement, review).
- **foreman agent** — The foreman is the agent that coordinates a factory's work and communicates with you. It delegates work to other agents, asks for your decisions when needed, and returns results.
*Usage note:* Lowercase "foreman" in prose. The foreman is an agent inside a factory, not the factory itself — never use the two interchangeably, and never call the foreman "the factory" even though setup gives them the same name by default.
@@ -434,6 +434,8 @@ Docs match the screen; the fix belongs in the app.
## Billing and credits
- **usage** — the general term for metered inference, Warp-hosted compute, and platform activity. Explain dollars versus credits when that distinction affects the task; use ordinary plan names elsewhere.
+- **usage balance** — usage available to the user or team billed for the work, subject to the applicable billing rules.
+ *Usage note:* Use "add usage" for the action of funding the balance, with "if needed" when an existing allowance may cover the work. Do not imply that every workflow uses a shared team balance or requires a new purchase.
- **included usage** — the allowance included with a plan; distinguish it from purchased usage and contract-specific pools.
- **purchased usage** — additional usage bought on an eligible plan. Distinguish the usage added to the balance from the payment amount.
- **dollar usage** — a usage balance expressed in US dollars, not the subscription price or necessarily the amount paid for a purchase.
diff --git a/AGENTS.md b/AGENTS.md
index 2ff2d36b1..2fb699320 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -346,6 +346,7 @@ Captions orient the reader — they identify what the image shows so the reader
- ❌ `The input toolbelt, from left to right: model selector, voice input, image attachments, and conversation controls.` (exhaustive list)
### Links, embeds, and cross-references
+- When link text uses a destination's full page title, match that title's wording and capitalization, even within a sentence. Descriptive link phrases follow normal sentence capitalization and don't need to reproduce the title.
- Use descriptive link text that explains what users will find. The anchor text should describe the destination or task, not the action of clicking.
- ✅ "Learn more about [Codebase Context](...)" / "See [configuring environments](...)"
- ❌ "Click [here](...)" / "See [this page](...)" / "Read [more](...)"
@@ -567,6 +568,7 @@ These rules apply regardless of content type:
5. Troubleshooting for common issues (optional but recommended)
**Rules**:
+- **Keep prerequisites concise.** State requirements in unbolded bullets rather than bold labels followed by explanations. Link setup details, and put conditional instructions beside the step that needs them. Keep required access, credential types, and technical constraints explicit. This also applies to quickstarts.
- **Keep steps focused, not artificially atomic.** Aim for one primary action per step, but group tightly related actions together when they share the same UI context and doing so keeps the procedure at a readable length. Up to ~3 related actions per step is acceptable. Use judgment: a simple task shouldn't require 10+ steps, but a single step shouldn't be a mini-procedure either.
- Acceptable groupings: actions on the same form (entering a name and choosing an expiration date), a click that reveals the next target (clicking to expand a section, then clicking the revealed item), or a short natural sequence within the same UI area.
- Avoid grouping actions that span different areas of the UI or that would make a step hard to scan at a glance.
@@ -955,6 +957,24 @@ Match a control's shipped label without letting that label define all surroundin
Scope credential claims by configuration: personal device keys, team-managed keys and endpoints, connected subscriptions, and third-party harness credentials are different paths. Don't apply "not stored by Warp" or "not available to cloud agents" to all customer credentials. See the glossary's [inference configuration terms](.agents/references/terminology.md#inference-configuration).
+#### Usage prerequisites and setup instructions
+
+State the funding requirement, give a short action if needed, and link to the canonical billing page. Prefer "usage balance" and "add usage" to vague conditions such as "sufficient eligible usage." Do not imply that every reader must make a purchase when included usage or a contract allowance may already cover the work.
+
+* **Separate access from funding** - Team membership, plan access, and available usage are different requirements. Keep required access visible; link to its reference rather than copying plan tables.
+* **Match the balance to the workflow** - Use team-balance wording for factory setup. Standalone cloud runs can be individual or team runs; don't add a team requirement to individual workflows. For schedules and API-triggered runs, preserve or link to which user or team is billed.
+* **Keep exceptions with their owner** - Billing pages own balance eligibility, spending controls, charge components, and Enterprise terms. Preserve a condition needed for the current task, but don't duplicate those rules in every prerequisite list. Don't apply standalone integration restrictions to factory integrations without verification.
+* **Preserve technical precision** - "Eligible" can be necessary when distinguishing usable balances in billing references. Keep credit-named UI labels, identifiers, error codes, URLs, and credit-billed contexts; this is not a blanket terminology replacement.
+
+Examples to adapt, not mandatory boilerplate:
+
+* **Factory setup** - "Available usage in your team's balance for factory runs. Add usage if needed. See access and billing requirements."
+* **Individual or team cloud runs** - "Available usage for cloud runs. Add usage if needed. See access and billing requirements."
+* **Scheduled runs** - "Available usage for the user or team billed for the schedule. Add usage if needed. See run identity before choosing which agent runs it."
+
+In published copy, link the billing-reference phrase to the owning page or section. If the funding source or access rule is unverified, ask the product or billing owner; do not invent a uniform policy for consistent wording.
+
+
### UI elements
- **Settings** (capitalized when referring to the Settings panel)
- **Command Palette** (capitalized)
diff --git a/scripts/test_check_redirects.py b/scripts/test_check_redirects.py
index 113d6009e..cdb54a964 100644
--- a/scripts/test_check_redirects.py
+++ b/scripts/test_check_redirects.py
@@ -65,6 +65,23 @@ def test_live_session_sharing_page_has_no_redirect(self):
self.assertEqual(matching_sources, [])
+ def test_factory_agent_pages_have_no_redirect(self):
+ routes = (
+ "/factories/factory-agents",
+ "/factories/factory-agents/configuration",
+ "/factories/factory-agents/creating-custom-agents",
+ )
+ redirects = load_redirects()
+ for route in routes:
+ with self.subTest(route=route):
+ self.assertIsNotNone(url_to_content_path(route))
+ for source in (route, route + "/"):
+ self.assertEqual(
+ [r["source"] for r in redirects
+ if redirect_source_matches_path(r["source"], source)],
+ [],
+ )
+
def test_restored_transition_page_has_no_redirect(self):
route = "/platform/transitioning-from-oz"
self.assertIsNotNone(url_to_content_path(route))
diff --git a/src/assets/factories/factory-agent-auth-secret.png b/src/assets/factories/factory-agent-auth-secret.png
index 2970940d9..b41ba53cf 100644
Binary files a/src/assets/factories/factory-agent-auth-secret.png and b/src/assets/factories/factory-agent-auth-secret.png differ
diff --git a/src/assets/factories/factory-agent-edit.png b/src/assets/factories/factory-agent-edit.png
new file mode 100644
index 000000000..2a56bbdfb
Binary files /dev/null and b/src/assets/factories/factory-agent-edit.png differ
diff --git a/src/assets/factories/quickstart-connect-code-forges.png b/src/assets/factories/quickstart-connect-code-forges.png
new file mode 100644
index 000000000..2609c4a94
Binary files /dev/null and b/src/assets/factories/quickstart-connect-code-forges.png differ
diff --git a/src/assets/factories/quickstart-connect-repo.png b/src/assets/factories/quickstart-connect-repo.png
new file mode 100644
index 000000000..05b7a93da
Binary files /dev/null and b/src/assets/factories/quickstart-connect-repo.png differ
diff --git a/src/assets/factories/quickstart-factory-details.png b/src/assets/factories/quickstart-factory-details.png
new file mode 100644
index 000000000..71f547238
Binary files /dev/null and b/src/assets/factories/quickstart-factory-details.png differ
diff --git a/src/assets/factories/quickstart-pick-agents.png b/src/assets/factories/quickstart-pick-agents.png
index 50bd325aa..23a65caf8 100644
Binary files a/src/assets/factories/quickstart-pick-agents.png and b/src/assets/factories/quickstart-pick-agents.png differ
diff --git a/src/content/docs/agents/capabilities/computer-use/index.mdx b/src/content/docs/agents/capabilities/computer-use/index.mdx
index 36791db22..f7994095d 100644
--- a/src/content/docs/agents/capabilities/computer-use/index.mdx
+++ b/src/content/docs/agents/capabilities/computer-use/index.mdx
@@ -136,5 +136,5 @@ Computer Use can also help with general web tasks: browsing websites, filling ou
* [Images as Context](/agents/local-agents/agent-context/images-as-context/) - Pass design mockups and screenshots as context
* [Full Terminal Use](/agents/capabilities/full-terminal-use/) - Let agents drive interactive terminal apps, see live output, and run commands
* [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open the cloud run transcript and artifacts after a Computer Use session finishes
-* [Factory agents](/factories/factory-agents/) - Roles and responsibilities for factory agents
+* [About factory agents](/factories/factory-agents/) - Roles and responsibilities for factory agents
* [Self-hosted agent data storage](/platform/data-storage/) - Storage options for agent run data
diff --git a/src/content/docs/agents/cli/oz-cli/quickstart.mdx b/src/content/docs/agents/cli/oz-cli/quickstart.mdx
index f64be2d33..366bcc3c9 100644
--- a/src/content/docs/agents/cli/oz-cli/quickstart.mdx
+++ b/src/content/docs/agents/cli/oz-cli/quickstart.mdx
@@ -17,6 +17,11 @@ This guide walks you through the essentials to get up and running with the {VARS
Watch this short demo of the {VARS.WARP_AGENT_CLI} workflow:
+## Prerequisites
+
+* A [Warp account](https://app.warp.dev/signup).
+* A computer running macOS, Linux, or Windows.
+
## 1. Install the CLI
If you already have the [Warp desktop app installed](/getting-started/quickstart/installation-and-setup/), the **CLI is included** and available in Warp.
@@ -67,7 +72,7 @@ What happens:
Cloud agents run in a remote environment with your repositories cloned and dependencies installed, making them useful for tasks that need full codebase access.
-If you haven't already created an environment, run `/create-environment` in Warp or follow the [Cloud Agents Quickstart](/platform/quickstart/). Then run the following command:
+If you haven't already created an environment, run `/create-environment` in Warp or follow the [Cloud agents quickstart](/platform/quickstart/). Then run the following command:
```sh
oz agent run-cloud --environment --prompt "Scan this repo for outdated dependencies"
diff --git a/src/content/docs/agents/cli/quickstart.mdx b/src/content/docs/agents/cli/quickstart.mdx
index 0baf3237f..252f8b0ac 100644
--- a/src/content/docs/agents/cli/quickstart.mdx
+++ b/src/content/docs/agents/cli/quickstart.mdx
@@ -11,8 +11,8 @@ This guide takes you from installing the {VARS.WARP_CLI} to your first agent con
## Prerequisites
-* **A Warp account** - The login step opens your browser, where you can sign in or [create an account](https://app.warp.dev/signup). The CLI uses the same account as the Warp app, but doesn't require the app to be installed.
-* **A supported platform** - macOS (Apple Silicon or Intel), Linux (x64 or Arm64), or Windows (x64 or Arm64).
+* A [Warp account](https://app.warp.dev/signup).
+* A computer running macOS (Apple Silicon or Intel), Linux (x64 or Arm64), or Windows (x64 or Arm64).
## 1. Install the Warp Agent CLI
@@ -63,13 +63,13 @@ To turn off update checks, set `general.autoupdate_enabled` to `false` in the [s
## 2. Log in
-Log in once so the CLI can access your Warp account, models, and saved context. Start the CLI:
+The CLI uses the same account as the Warp app, but doesn't require the app to be installed. Log in once so the CLI can access your account, models, and saved context. Start the CLI:
```bash
warp
```
-The CLI shows a verification link and a device code, and opens the link in your browser. Approve the login there and the CLI unlocks automatically, so you don't need to restart it. If the browser doesn't open, visit the link shown in the CLI and enter the code.
+The CLI shows a verification link and a device code, and opens the link in your browser. Sign in or [create an account](https://app.warp.dev/signup), then approve the login. The CLI unlocks automatically, so you don't need to restart it. If the browser doesn't open, visit the link shown in the CLI and enter the code.
When login completes, the CLI shows its start screen with the version, a short "What's new" list, and the rules, skills, and MCP servers it discovered for your current directory. You stay signed in across sessions. To sign out later, run `/logout`, which returns the CLI to its login screen and signs out your browser session too.
diff --git a/src/content/docs/enterprise/support-and-resources/billing.mdx b/src/content/docs/enterprise/support-and-resources/billing.mdx
index c26dd786c..c29cac04e 100644
--- a/src/content/docs/enterprise/support-and-resources/billing.mdx
+++ b/src/content/docs/enterprise/support-and-resources/billing.mdx
@@ -37,7 +37,7 @@ Local and cloud usage draw from the shared Enterprise pool. Applicable charges d
Agent API key runs use shared team usage. User-created schedules run as their creator by default, or as a cloud agent when configured to do so. Enterprise funding follows your contract.
-For more details, see [Access, Billing, and Identity](/platform/team-access-billing-and-identity/).
+For more details, see [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/).
## BYOLLM billing
diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx
index e028bcf98..990315903 100644
--- a/src/content/docs/factories/api-and-sdk/index.mdx
+++ b/src/content/docs/factories/api-and-sdk/index.mdx
@@ -89,6 +89,8 @@ See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**Type
The Conversation API returns skill loads as `read_skill` actions. When `input.bundled_skill_id` is present, it identifies a Warp-provided bundled reference. `input.skill_path` is the path used to resolve a skill, but doesn't prove ownership: file-based skills and path-referenced bundled skills, including skills from a remote host, can both use this field.
+To measure team-owned skill usage, exclude actions with `input.bundled_skill_id`. Count a path-only load only after confirming the path belongs to a skill root your team manages, such as the [factory-wide or agent-specific skill directories](/factories/factory-skills/#add-or-edit-a-skill).
+
The following stable, user-facing IDs are bundled directly with Warp:
| Bundled skill ID | Purpose |
diff --git a/src/content/docs/factories/api-and-sdk/quickstart.mdx b/src/content/docs/factories/api-and-sdk/quickstart.mdx
index 7b4aecc01..08fb27fa4 100644
--- a/src/content/docs/factories/api-and-sdk/quickstart.mdx
+++ b/src/content/docs/factories/api-and-sdk/quickstart.mdx
@@ -19,11 +19,13 @@ 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 {VARS.WEB_APP} 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.
+* A Warp API key from the {VARS.WEB_APP} settings. See [API keys](/agents/cli/oz-cli/api-keys/).
+* A configured [cloud environment](/platform/environments/) with the required repositories and dependencies. See the [Cloud agents quickstart](/platform/quickstart/).
## 1. Set your API key
+Use a personal key to attribute runs to you, or an agent key to attribute them to a [cloud agent](/platform/agents/).
+
Export your API key so the API can authenticate your requests automatically — all commands in this guide reference the `WARP_API_KEY` environment variable.
```bash
@@ -94,4 +96,4 @@ You created a cloud agent run over HTTP and tracked it from `QUEUED` to `SUCCEED
* **Read the endpoint guide** - [Agent & run endpoints](/factories/api-and-sdk/) documents the configuration and run lifecycle, while the [{VARS.WARP_PLATFORM_API} reference](/api) lists all parameters, query filters, and response schemas.
* **Explore the SDKs** - [`warp-platform-sdk` for Python](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` for TypeScript](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) 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 the [Scheduled agents quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or the [Integrations quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear.
+* **Schedule and automate** - See the [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or the [Integrations quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear.
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 52a7740fa..dbe29467d 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
@@ -58,6 +58,6 @@ This error is returned when:
## Related
-* [Cloud Agents Overview](/platform/) — How cloud agent tasks work
+* [Cloud agents overview](/platform/) — How cloud agent tasks work
* [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/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx
index cecf4fc26..5dd01ef5b 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
@@ -55,4 +55,4 @@ If you are not a team admin, contact your team admin to adjust the budget.
## Related
-* [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Budget configuration and billing details
+* [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/) — Budget configuration and billing details
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 344c0f5d1..33f295dd2 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
@@ -57,5 +57,5 @@ 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
+* [Managing cloud agents](/platform/managing-cloud-agents/) — Viewing and 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/content-policy-violation.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx
index c27645de9..9f0ea2977 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
@@ -57,5 +57,5 @@ For security reasons, the error message is intentionally generic and does not de
## Related
-* [Cloud Agents Overview](/platform/) — How cloud agent tasks work
+* [Cloud agents overview](/platform/) — How cloud agent tasks work
* [Environments](/platform/environments/) — Configuring setup commands
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 fb9013b2d..f346a0b73 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
@@ -50,11 +50,11 @@ The `title` field in the response will describe the specific feature that is una
2. Upgrade to a plan that includes the required feature.
3. Retry the operation.
-For plan comparisons and feature availability, see [Access, Billing, and Identity](/platform/team-access-billing-and-identity/).
+For plan comparisons and feature availability, see [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/).
---
## Related
-* [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Plan requirements and feature availability
+* [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/) — Plan requirements and feature availability
* [Integrations](/platform/integrations/) — Integration requirements by plan
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 746cec1cd..239e67a9b 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
@@ -81,5 +81,5 @@ When an error response includes a `trace_id`, you can include it when [contactin
## Related pages
* [{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
+* [Cloud agents overview](/platform/) — How cloud agents work
+* [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/) — Plan requirements and billing details
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 7e213ad0c..66c36e7e8 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
@@ -58,6 +58,6 @@ This error is returned when:
## Related
-* [Cloud Agents Overview](/platform/) — How cloud agent tasks work
+* [Cloud agents overview](/platform/) — How cloud agent tasks work
* [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/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx
index 59c8e2307..8a08ce9ec 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
@@ -27,7 +27,7 @@ This error is returned when:
* The billed user's or team's eligible balance is too low to start the run.
* Auto-reload is off or cannot replenish the balance, such as when a purchase is blocked by the team's limit.
-See [purchasing additional usage](/support-and-community/plans-and-billing/add-on-credits/) for prices and purchase limits.
+See [Purchasing additional usage](/support-and-community/plans-and-billing/add-on-credits/) for prices and purchase limits.
---
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 e5da179e4..9e93e5dcf 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
@@ -66,5 +66,5 @@ This error includes extra fields beyond the standard response format:
## Related
* [Integrations](/platform/integrations/) — Integration setup guides
-* [Slack Integration](/platform/integrations/slack/) — Slack-specific setup
-* [Linear Integration](/platform/integrations/linear/) — Linear-specific setup
+* [Slack integration](/platform/integrations/slack/) — Slack-specific setup
+* [Linear integration](/platform/integrations/linear/) — Linear-specific setup
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 02a121076..7b4d31441 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
@@ -57,5 +57,5 @@ If the error persists:
## Related
-* [Cloud Agents Overview](/platform/) — How cloud agent tasks work
+* [Cloud agents overview](/platform/) — How cloud agent tasks work
* [Cloud Agents FAQs](/platform/faqs/) — Common questions about cloud agents
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 fd42806e3..71175a146 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
@@ -56,5 +56,5 @@ This error is returned when:
## Related
-* [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Permission model and identity
+* [Access, billing, and identity permissions](/platform/team-access-billing-and-identity/) — Permission model and identity
* [{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 d2ee357e0..d683a7d0d 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
@@ -56,6 +56,6 @@ This error is returned when:
## Related
-* [Cloud Agents Overview](/platform/) — How cloud agent tasks work
+* [Cloud agents overview](/platform/) — How cloud agent tasks work
* [Self-hosting](/factories/self-hosting/) — Self-hosted agent configuration
* [{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/resource-not-found.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx
index a75992bd0..71c1b3841 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
@@ -58,4 +58,4 @@ The `detail` field in the response will describe which resource was not found.
## Related
* [Environments](/platform/environments/) — Managing cloud agent environments
-* [Managing Cloud Agents](/platform/managing-cloud-agents/) — Viewing and managing agent tasks
+* [Managing cloud agents](/platform/managing-cloud-agents/) — Viewing and managing agent tasks
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 d0feae9af..a2fcee12c 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
@@ -72,5 +72,5 @@ If the error persists after retries:
## Related
-* [Cloud Agents Overview](/platform/) — How cloud agent execution works
+* [Cloud agents overview](/platform/) — How cloud agent execution works
* [Deployment Patterns](/factories/deployment-patterns/) — Execution models and infrastructure
diff --git a/src/content/docs/factories/automations.mdx b/src/content/docs/factories/automations.mdx
index c70651013..c6a02049f 100644
--- a/src/content/docs/factories/automations.mdx
+++ b/src/content/docs/factories/automations.mdx
@@ -1,84 +1,72 @@
---
title: Factory automations
description: >-
- An automation starts factory runs from a trigger, routes them to an agent,
- and filters which events start a run.
+ Configure factory automations with triggers and filters to control which
+ events start runs and which agent handles the work.
sidebar:
label: Factory automations
---
-An **automation** is a factory resource that starts runs from a trigger and routes them to an agent. Triggers fired by a connected tool or a [custom webhook](/factories/webhooks/) also carry filters that decide which events start a run. Every default automation Warp creates when you connect a provider, and every custom one you add, is this same resource. See [`automations//automation.md`](/factories/factory-as-code/#automationsnameautomationmd) for the full schema.
-
-Automation filters decide which events from your connected tools start factory work. Every trigger on an automation carries filters (e.g., a repository, channel, team, project, label, author, or webhook payload field) and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them.
+An **automation** starts factory runs from a trigger and routes them to an agent. Filters narrow which events start work. For example, an automation can send newly opened pull requests to a review agent, but only for one repository's `main` branch.
## How matching works
An event starts an automation only when it matches the trigger's provider, event type, and filters:
-* **Every filter must match.** A trigger that sets both a team and a label matches only events carrying both.
-* **Within an inclusion filter, any value matches.** A **Labels** filter listing `bug` and `regression` matches an issue with either label.
-* **An empty optional list filter doesn't restrict matching.** Provider defaults still apply: [GitHub triggers skip bot events by default](/factories/integrations/github/#events-from-bots-dont-start-work).
+* **Every filter must match** - A trigger that sets both a team and a label matches only events carrying both.
+* **Any included value can match** - A **Labels** filter listing `bug` and `regression` matches an issue with either label.
+* **Empty optional list filters don't restrict matching** - Provider defaults still apply: [GitHub triggers skip bot events by default](/factories/integrations/github/#events-from-bots-dont-start-work), with `skip_bots` set to `all` when omitted.
One event can match more than one automation, and each match starts its own run. If a single action starts duplicate runs, narrow or remove one of the overlapping triggers.
## Filters don't control access
-Filters decide when work starts, not what a running agent can reach. Access comes from what you authorize on each provider: the GitHub App installation, the GitLab bot's project membership, the Slack app's authorization, the Microsoft Teams installation, the Linear OAuth scope, or the Jira app installation. Tightening a filter never shrinks that access, and removing one never widens it. To change what an integration can reach, change what you authorize for that provider.
+Filters decide when work starts, not what an integration or running agent can access. To change an integration's access, change its permissions with the provider, not its filters.
-Filters narrow which activity starts runs; provider account and access requirements still apply. Slack mentions and direct messages additionally require a Slack account linked to an active member of the factory's Warp team. Microsoft Teams mentions require a Microsoft account linked to an active member of the factory's Warp workspace. A custom webhook authenticates each delivery with the webhook's own secret or the sender's signature, so anyone holding that credential can start work; its filters only decide which deliveries do.
+Provider account requirements still apply. See [who can start work in Slack](/factories/integrations/slack/#who-can-start-work) and [account linking in Microsoft Teams](/factories/integrations/teams/#test-the-connection). Custom webhooks instead authenticate deliveries with a [token or signature](/factories/webhooks/#authentication-modes); filters aren't a substitute for that authentication.
## What each source can filter on
-Every source filters on where the event happened: a repository, project, conversation, or team. The remaining filters vary by source and event type:
+The table summarizes filter categories. Each linked integration guide lists the filters available for each event type.
| Source | Filters |
| --- | --- |
-| [Slack](/factories/integrations/slack/) | Conversations, authors or members, keywords, emoji, and reacted-message authors |
-| [Microsoft Teams](/factories/integrations/teams/) | Team, channels (standard picker; shared by channel ID), authors, and keywords |
-| [GitHub](/factories/integrations/github/) | Repository, branches, base branches, paths, labels, authors, assignees, mentioned users or teams, reviewers, review states, workflows, and conclusions |
+| [Slack](/factories/integrations/slack/) | Conversations, people, keywords, and emoji |
+| [Microsoft Teams](/factories/integrations/teams/) | Team, channels, authors, and keywords |
+| [GitHub](/factories/integrations/github/) | Repository, branches, paths, labels, people, reviews, and workflow results |
| [GitLab](/factories/integrations/gitlab/) | Project, actions, and base branch |
-| [Azure DevOps](/factories/integrations/azure-devops/) | Repository, branches, work item types, labels, assignees, authors, and mentioned identities |
-| [Linear](/factories/integrations/linear/) | Teams, labels, project, workflow state, assignee, mentioned user, and, for comment events, a specific issue |
-| [Jira](/factories/integrations/jira/) | Jira projects and assignment keywords |
-| [Custom webhooks](/factories/webhooks/) | The webhooks the trigger listens to, and a pattern over the delivery's JSON payload |
+| [Azure DevOps](/factories/integrations/azure-devops/) | Repository, branches, work item types, labels, and people |
+| [Linear](/factories/integrations/linear/) | Team, project, issue, labels, workflow state, and people |
+| [Jira](/factories/integrations/jira/) | Projects |
+| [Custom webhooks](/factories/webhooks/) | Webhook and JSON payload |
-Each integration guide lists which filters appear on which event types. Webhook payload patterns follow their own grammar, described in [payload filters for webhook triggers](#payload-filters-for-webhook-triggers).
+For webhook pattern syntax, see [Payload filters for webhook triggers](#payload-filters-for-webhook-triggers).
## Edit filters on an automation
-1. In the factory's dashboard, open **Automations**, then create an automation or edit an existing one.
-2. Under **Triggers**, open a trigger and set the filters shown for its event. Click **More filters** for the event-specific options.
-3. Click **Save**. To confirm the routing works, send a matching test event, such as opening a test issue, and check that a work item starts in the factory dashboard.
+You can edit custom automations and the defaults Warp creates when you connect a provider. If your definition lives in an external repository, the Automations page is read-only; edit the [definition files](#filters-in-definitions-as-code) instead.
-{/* VISUAL: An automation's trigger editor with More filters expanded. */}
+To edit an existing automation's filters:
-Review the default automations Warp creates when you connect a provider, too: their filters are starting points, not fixed rules.
+1. In the web app sidebar, expand your factory and click **Automations**.
+2. Click the name of the automation you want to edit to open its settings.
+3. In the "Triggers" section, adjust the filters for the relevant trigger. Click **More filters** for additional options.
+4. Click **Save** in the top-right corner.
+5. Send a matching test event, such as opening a test issue, and confirm that a work item appears in the factory dashboard.
-## Filters in definitions as code
-
-In a [factory definition](/factories/factory-as-code/), each entry under an automation's `triggers` takes an optional `filter` whose keys mirror the filters in the automation editor:
+{/* VISUAL: An automation's trigger editor with More filters expanded. */}
-```markdown title="automations/labeled-issue/automation.md"
----
-enabled: true
-agent: foreman
-triggers:
- - provider: github
- event: issue_labeled
- filter:
- repos: [acme/payments-service]
- labels: [factory-ready]
----
-Review the labeled issue and decide the next required stage.
-```
+## Filters in definitions as code
-The same matching rules apply: every field must match, and an `in` list matches any listed value. Omitted optional list filters don't restrict matching; GitHub's `skip_bots` policy defaults to `all` when omitted. Each integration guide shows the keys its provider accepts.
+In a factory definition, an automation's `triggers` entries declare the provider, event, and filters. Start with the [labeled-issue example](/factories/factory-as-code/#automationsnameautomationmd), then look up supported keys in the [trigger filter reference](/factories/factory-as-code/#triggersfilter).
-For example, this automation from [`04-code-review-only`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/04-code-review-only) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository scopes reviews to one base branch and excludes work-in-progress PRs with a `not_in` list:
+This example reviews pull requests in `acme/api-service` targeting `main`, excluding those labeled `wip`:
```markdown title="automations/pr-opened/automation.md"
---
+enabled: true
+agent: foreman
triggers:
- provider: github
event: pull_request_opened
@@ -93,17 +81,11 @@ stop silently. Otherwise review it and post your findings and verdict on
the PR.
```
-For more automations that use these filters, including branches, paths, workflow conclusions, and emoji reactions, see [`06-common-automations`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/06-common-automations).
+Plain lists include matching values; `not_in` excludes them. The [same matching rules](#how-matching-works) apply as in the editor. For complete definitions, see [`04-code-review-only`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/04-code-review-only) and [`06-common-automations`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/06-common-automations).
## Payload filters for webhook triggers
-A [custom webhook](/factories/webhooks/) trigger (`provider: webhook`, `event: received`) binds an automation to exactly one webhook. `webhook_ids` is required, takes a one-item list containing that webhook's UID, and supports only `in`. To listen to multiple webhooks, add one trigger with provider `webhook` and event `received` per UID. The optional `payload` filter is a pattern that mirrors the shape of the delivery's JSON body, so you can route on the payload without running an agent to decide:
-
-* Payload filters match against the webhook's JSON body.
-* Fields are ANDed together: every key in the pattern must match.
-* An array means "match any of these values."
-* `in`, `not_in`, and `exists` are supported as operators on a field.
-* Nested objects let you filter on nested payload fields.
+A webhook trigger's optional `payload` filter matches the delivery's JSON body. Each key names a field that must match; an array lists allowed values. Use nested objects for nested fields and `in`, `not_in`, or `exists` for explicit conditions.
This trigger starts a run for opened or reopened pull requests from a GitHub webhook, skipping drafts and bot authors:
@@ -122,19 +104,17 @@ triggers:
not_in: [Bot]
```
-In the dashboard, the **Webhook** trigger's JSON editor validates a pattern as you type, and **Test filter** evaluates it against a stored delivery. See [add a Webhook trigger to an automation](/factories/webhooks/#add-a-webhook-trigger-to-an-automation).
-
-For exact matching semantics, limits, and validation rules, see [payload filter reference](#payload-filter-reference).
+Replace `WEBHOOK_UID` with the webhook's UID. For selecting webhooks and testing patterns against stored deliveries, see [Add a Webhook trigger to an automation](/factories/webhooks/#add-a-webhook-trigger-to-an-automation). The [definition reference](/factories/factory-as-code/#triggersfilter) covers the required `webhook_ids` filter.
-## Payload filter reference
+### Payload filter reference
-* **Values match by type.** Strings match exactly and case-sensitively, numbers match numerically (`1` equals `1.0`), and booleans and `null` are matchable values.
-* **A missing key fails `in` and passes `not_in`.** A field the payload doesn't carry can't be in any set, so `{"env": {"not_in": ["dev"]}}` matches a delivery with no `env` field. A nested pattern object requires its key to be present.
-* **Arrays of objects match on any element.** When the payload value is an array of objects, a nested pattern matches if any element matches; when it's an array of scalars, `in` matches on any overlap and `not_in` requires none.
-* **Operators on the same field AND together.** For example, combining `in` and `exists: true` on one field requires both to hold.
+* **Values match by type** - Strings match exactly and case-sensitively, numbers match numerically (`1` equals `1.0`), and booleans and `null` are matchable values.
+* **Missing keys** - A missing key fails `in` and passes `not_in`. For example, `{"env": {"not_in": ["dev"]}}` matches a delivery with no `env` field. A nested pattern object requires its key to be present.
+* **Arrays** - For an array of objects, a nested pattern matches if any element matches. For an array of scalars, `in` matches on any overlap and `not_in` requires none.
+* **Combined operators** - Operators on the same field must all match. For example, combining `in` and `exists: true` requires both to hold.
* **Limits** - A pattern nests up to 10 levels deep, holds up to 64 leaf fields, and lists up to 32 values per set.
* **Validation** - Warp rejects a pattern that lists the same value in both `in` and `not_in` on one field, or that combines `exists: false` with a non-empty `in`.
-* **Fail closed** - A filter that can't be evaluated never matches, so a broken filter keeps an automation silent rather than firing it.
+* **Fail closed** - A filter that can't be evaluated never matches.
## Troubleshooting
@@ -143,9 +123,7 @@ For exact matching semantics, limits, and validation rules, see [payload filter
## Related pages
-* [**Connect your factory**](/factories/connect-your-factory/) - Choose the sources that route work into the factory.
-* [Slack](/factories/integrations/slack/), [Microsoft Teams](/factories/integrations/teams/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/) integration guides - Per-source setup, events, and filter details.
-* [**Custom webhooks**](/factories/webhooks/) - Start automations from any system that can POST JSON, with the setup flow and authentication modes.
-* [**Definitions as code**](/factories/factory-as-code/) - Manage automations, triggers, and filters as version-controlled files.
-* [**warp-factory-examples**](https://github.com/warpdotdev/warp-factory-examples) - Complete factory definitions with example automations and filters.
-* [**Factory dashboard**](/factories/factory-dashboard/) - Create and edit automations in the factory's **Automations** view.
+* [Connect your factory](/factories/connect-your-factory/) - Set up sources of factory work
+* [Triggering automations with custom webhooks](/factories/webhooks/) - Configure senders and authentication
+* [Factory definition syntax](/factories/factory-as-code/) - Manage automations as version-controlled files
+* [Factory dashboard](/factories/factory-dashboard/) - Manage agents, automations, and runs
diff --git a/src/content/docs/factories/code-forges/other-code-forges.mdx b/src/content/docs/factories/code-forges/other-code-forges.mdx
index 210e8e9aa..314322fe6 100644
--- a/src/content/docs/factories/code-forges/other-code-forges.mdx
+++ b/src/content/docs/factories/code-forges/other-code-forges.mdx
@@ -16,8 +16,8 @@ This setup gives factory agents repository access. It does not add provider-spec
## Prerequisites
-* **Factory access** - Permission to create the factory, add Agent Secrets, and edit its default runner.
-* **Repository access** - An HTTPS clone URL and a token that can read the repository.
+* Permission to create the factory, add Agent Secrets, and edit its default runner.
+* An HTTPS clone URL and a token with repository read access.
For provider-specific token and clone formats, see [Bitbucket repository access](/platform/integrations/bitbucket/) or [self-managed GitLab repository access](/platform/integrations/gitlab/#self-managed-gitlab-instances).
diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx
index 9f4b7f638..added444e 100644
--- a/src/content/docs/factories/connect-your-factory.mdx
+++ b/src/content/docs/factories/connect-your-factory.mdx
@@ -55,7 +55,7 @@ flowchart LR
An event from a connected tool starts the automation based on filter matching, such as a specific repository, channel, or label. Schedules start their automation on a timer, and direct requests go straight to the factory.
-Every request lands with the foreman agent, which turns it into a work item and dispatches the agents each stage needs. A reply in the same thread, issue, or pull request continues that work item instead of starting a new one, and repeated event deliveries don't create duplicates. See [how Warp Factories work](/factories/how-factories-work/) for the full lifecycle, including where people stay in the loop.
+Every request lands with the foreman agent, which turns it into a work item and dispatches the agents each stage needs. A reply in the same thread, issue, or pull request continues that work item instead of starting a new one, and repeated event deliveries don't create duplicates. See [How Warp Factories work](/factories/how-factories-work/) for the full lifecycle, including where people stay in the loop.
## Review the default automations
@@ -88,7 +88,7 @@ The [Factory MCP](/factories/factory-mcp/) connects local coding agents and othe
Not every task starts in an external tool:
* Start a direct run for one-off work. Click **New** on the factory's Runs page and describe the task to the foreman, the same way you would from Slack or an issue tracker.
-* Create a scheduled automation for recurring work, such as maintenance or reports. See the [triggers overview](/platform/triggers/) for how schedules and other triggers work across the platform.
+* Create a scheduled automation for recurring work, such as maintenance or reports. See the [Triggers overview](/platform/triggers/) for how schedules and other triggers work across the platform.
This automation from [`06-common-automations`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/06-common-automations) runs a dependency audit every Monday:
diff --git a/src/content/docs/factories/deployment-patterns.mdx b/src/content/docs/factories/deployment-patterns.mdx
index 1fbd9908b..b902dd872 100644
--- a/src/content/docs/factories/deployment-patterns.mdx
+++ b/src/content/docs/factories/deployment-patterns.mdx
@@ -10,7 +10,12 @@ import { VARS } from '@data/vars';
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.
+The comparison below also shows unmanaged execution for standalone agents, which is not a factory execution host.
+
+
+Deployment models divide responsibilities between Warp and your infrastructure.
+
## Choose an execution model
@@ -24,24 +29,27 @@ Both factory options use the same [factory definition](/factories/factory-as-cod
## Warp-hosted execution
-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.
+Use this when your factory can reach its repositories and services over the public internet. The [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) runs the work on Warp-managed infrastructure while your factory definition selects the agents, runner, workspace, and credentials.
+
+Warp operates the control plane and per-run sandboxes.
+
See the [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-lifecycle) reference for a description of each component in the architecture.
### What it looks like
-* **Work intake** - factory automations, configured integrations, Factory MCP, or factory endpoints
-* **Execution** - {VARS.WARP_AUTOMATION_PLATFORM}-hosted environments (Docker-based)
-* **Visibility** - factory dashboard, session sharing, and APIs
+* **Work intake** - Automations, integrations, Factory MCP, and factory endpoints send work to the factory.
+* **Execution** - Agents run in Docker-based environments hosted by the {VARS.WARP_AUTOMATION_PLATFORM}.
+* **Visibility** - Teams monitor work through the factory dashboard, session sharing, and APIs.
### Send work to a factory
-* [Factory automations](/factories/automations/) route integration events, schedules, and webhooks to agents in the factory.
-* [Factory integrations](/factories/connect-your-factory/) let teammates send work from Slack, Linear, Jira, GitHub, and GitLab.
-* [Factory endpoints](/factories/factory-api/) let your service find a factory and dispatch work by UID.
-* [Factory MCP](/factories/factory-mcp/) lets a coding agent hand work to a factory.
+* Route integration events, schedules, and webhooks to factory agents with [Factory automations](/factories/automations/).
+* Send work from Slack, Linear, Jira, GitHub, and GitLab through [factory integrations](/factories/connect-your-factory/).
+* Find a factory and dispatch work by UID from your service using [Factory endpoints](/factories/factory-api/).
+* Coding agents can hand work to a factory through [Factory MCP](/factories/factory-mcp/).
For standalone cloud-agent triggers, see [cloud agents](/platform/).
diff --git a/src/content/docs/factories/factory-agents.mdx b/src/content/docs/factories/factory-agents.mdx
index 2812b0adb..53c70d462 100644
--- a/src/content/docs/factories/factory-agents.mdx
+++ b/src/content/docs/factories/factory-agents.mdx
@@ -1,17 +1,19 @@
---
-title: Factory agents
+title: About factory agents
description: >-
Every factory has a team of default agents: a foreman that coordinates the
work, plus triage, spec, implement, and review agents.
sidebar:
- label: "Factory agents"
+ label: "About factory agents"
---
-The **foreman** is the agent that coordinates a factory's work and communicates with you. It delegates work to other agents, asks for your decisions when needed, and returns results. Four other default agents each cover one part of the software development lifecycle: triage scopes the request, spec writes the plan, implement writes the code, and review checks it. Together they take a work item from the moment it reaches your factory to a pull request ready for review.
+The **foreman** is the agent that coordinates a factory's work and communicates with you. It delegates work to other agents, asks for your decisions when needed, and returns results. Default agents each cover one part of the software development lifecycle: triage scopes the request, spec writes the plan, implement writes the code, and review checks it. Together, they turn a work item into a pull request ready for your team to review.
## The default agents
-Every factory gets a foreman, and you choose one to four other agents to go with it. These defaults are a starting point — you can [add custom agents and automations](#add-custom-agents-and-automations) for work they don't cover. The default agents' prompts, descriptions, and models are reproduced as files in [`00-warp-default-agents`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/00-warp-default-agents) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository.
+Every factory gets a foreman. You choose which of the four default agents to include. These defaults are a starting point, and you can [add custom agents](/factories/factory-agents/creating-custom-agents/) and [automations](/factories/automations/) for work they don't cover.
+
+The default agents' prompts, descriptions, and models are available in [`00-warp-default-agents`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/00-warp-default-agents) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository.
| Agent | What it does | What it produces |
| --- | --- | --- |
@@ -21,140 +23,71 @@ Every factory gets a foreman, and you choose one to four other agents to go with
| Implement | Makes and validates the code change | Code, tests, validation results, and visual evidence |
| Review | Independently checks the finished change | Findings and a recommendation |
-These are responsibilities, not a fixed pipeline. A small, well-understood change can skip the Planning stage entirely, and review can send work back for another pass. By default, work that goes through Planning needs a human to approve the spec before the Building stage starts.
+These are responsibilities, not a fixed pipeline. A small, well-understood change can skip planning entirely. If the review agent finds problems, the foreman sends work back for another pass. By default, work that needs a spec waits for human approval before implementation starts.
-For the complete lifecycle, see [how Warp Factories work](/factories/how-factories-work/).
+For the complete lifecycle, see [How Warp Factories work](/factories/how-factories-work/).
### Foreman
-The **foreman agent** runs the factory floor. It decides which agent a work item goes to next, hands the work over, and keeps the requester informed. It's the only default agent that talks to the requester directly. When another agent needs a human answer, the foreman asks the question and routes the answer back. For revisions and follow-ups, the foreman goes back to the same agent and continues its existing conversation instead of starting a new one, so no context is lost.
+The **foreman agent** assigns work and is the only default agent that communicates directly with you. It relays questions and answers between you and other agents, and continues their existing conversations for revisions and follow-ups.
-When the work is done, the foreman presents the final pull request and its supporting evidence, then marks the work item complete. Complete means the work was handed to a human, not that the change was merged or deployed. Merging stays with your team.
+After implementation and review, the foreman returns the pull request and supporting evidence, then waits for your team to merge. By default, the foreman marks the work item complete on a later merge notification or your confirmation that the pull request landed.
#### Foreman name
-The foreman answers to a handle your team @-mentions in Slack and Linear, labeled **Foreman name** under **Settings** > **Identity** in the [factory dashboard](/factories/factory-dashboard/) and written as [`alias`](/factories/factory-as-code/#alias) in the definition. Factory setup copies it from the factory's name, so unless you change one of them, `payments` is the factory's name and `@payments` reaches its foreman.
+Use the foreman's handle to @-mention it in Slack and Linear. Factory setup defaults the handle to the factory's name. For example, a factory named `payments` gets the handle `@payments`.
-They are still two things: the handle addresses the foreman, and the foreman speaks for the factory. Give them different names if the overlap causes confusion on your team.
+The factory name and foreman handle can differ. To change the foreman's handle, open your factory's **Settings** in the web app and click **Identity**. You can also edit [`alias`](/factories/factory-as-code/#alias) in the definition.
### Triage
-Triage researches the codebase and related issues first, and reproduces a problem only when research can't establish the cause. It reports context, scope, complexity, and open questions that the foreman uses to decide whether to ask the requester for clarification, request a spec, or go straight to implementation.
+Triage researches the codebase and related issues, reproducing problems when research doesn't establish the cause. It reports scope, complexity, and open questions so the foreman can choose clarification, planning, or implementation.
### Spec
-Spec works through the foreman to define requirements, then writes product and technical specifications in a draft pull request with criteria for validating the change. The implement agent later continues that pull request. By default, the foreman waits for a person to approve the spec before implementation starts. Change that in the foreman's instructions.
+Spec defines requirements through the foreman. It writes product and technical specifications with validation criteria in a draft pull request. By default, the foreman waits for human approval before implementation starts. You can change this policy in the foreman's instructions.
### Implement
-Implement continues the spec's branch and draft pull request rather than starting over. It adds tests, runs the repository's validation, and, when [computer use](/agents/capabilities/computer-use/) is available, captures visual evidence of user-facing changes. If review finds problems, implement revises. It never merges.
+Implement builds on the spec's branch and draft pull request. It adds tests, runs repository checks, and captures visual evidence of user-facing changes when [computer use](/agents/capabilities/computer-use/) is available. It revises changes after review but never merges.
### Review
-Review independently examines the change for unmet requirements, broken conventions, missing or failing tests, security issues, and evidence that doesn't hold up. It reruns or extends validation where the evidence is thin, then recommends accepting, revising, or asking a human to decide. The recommendation is advice — review doesn't approve or merge the pull request.
+Review independently checks requirements, code conventions, tests, security, and supporting evidence. It reruns or extends validation when needed, then recommends acceptance, revisions, or a human decision. It doesn't approve or merge the pull request.
## Built-in skills
-Every default agent comes with GitHub skills, and the foreman also comes with a Slack skill. The issue tracker you choose during setup adds to that baseline: choosing Linear or Jira gives the agents that tracker's skill and instructions. If you don't choose a tracker, the agents get only the baseline skills. Define custom procedures with [factory skills](/factories/factory-skills/) to extend what an agent can do beyond the built-in set.
-
-## Configure agent behavior
-
-1. From the [factory dashboard](/factories/factory-dashboard/) sidebar, select your factory and click **Agents**.
-
-
- 
- The Agents page lists a factory's foreman and default agents.
-
-
-2. Click an agent to open its settings page. From here, you can edit the agent description, harness, model, runner, host, [MCP servers](/platform/mcp/), [secrets](/platform/secrets/), and instructions.
-
-
- 
- An agent's settings page, where you configure its model, harness, runner, and host.
-
-
-You can also manage the factory as version-controlled code with [factory definition files](/factories/factory-as-code/) in a Git repository. A factory's settings live in one of two places:
-* A **Warp-managed factory** lets you edit everything, including harness, auth, and credential strategy, from the dashboard.
-* A **GitHub-backed factory** keeps those settings in its definition files. The dashboard shows them read-only, and you edit the files to make changes.
-
-For more information about the two locations, see [where the definition lives](/factories/factory-as-code/#where-the-definition-lives).
-
-Factory setup doesn't choose models for you. To change the model an agent uses, edit that agent.
-
-## Choose models and harnesses per agent
-
-Each agent can run on its own model and harness. Supported harnesses include the Warp Agent harness, Claude Code, and Codex, and any agent can use any of them. A foreman running on Claude Code or Codex can still dispatch the factory's other agents, and the runs it starts are still tracked as its children.
-
-Third-party harnesses require a paid plan; on the Free plan every agent runs on the Warp Agent harness. See [Warp pricing](https://www.warp.dev/pricing) for what each plan includes.
-
-Default model IDs change over time, so choose based on what each agent has to do well:
-
-| Agent | What to optimize for |
-| --- | --- |
-| Foreman | Orchestration, instruction following, and long-running conversations |
-| Triage | Research, evidence gathering, and working with connected tools |
-| Spec | Synthesizing requirements, technical reasoning, and precise writing |
-| Implement | Coding strength, with a harness that fits your repositories and toolchain |
-| Review | A different model or harness from the implement agent, so the two don't share blind spots |
-
-The model picker also includes custom routers from factories you can access. See [model choice for agents](/agents/inference/model-choice/), [custom model routers](/agents/inference/custom-routers/), and [harnesses for cloud agents](/platform/harnesses/) for available options.
+Every default agent includes GitHub skills; the foreman also includes a Slack skill. Choosing Linear or Jira during setup adds that tracker's skill and instructions. You can add custom procedures with [factory skills](/factories/factory-skills/).
-### Configuring a third-party harness
+## Configuring and extending agents
-Change an agent's harness to Claude Code or Codex to run it with that provider's own coding tool instead of the Warp Agent.
+
+
+
-1. From the [factory dashboard](/factories/factory-dashboard/) sidebar, select your factory and click **Agents**.
-2. Click an agent to open its settings page. In the "Harness" dropdown, select **Claude Code** or **Codex**.
-3. In the **Auth** field, choose a compatible, team-owned secret from the list or click **New auth secret** to create one.
+For settings, prompts, models, and third-party authentication, see [Configuring factory agents](/factories/factory-agents/configuration/).
-
- 
- The Auth field's dropdown, showing a team-owned secret and the option to add a new one.
-
+
+
- :::note
- * Claude Code accepts an Anthropic API key, Anthropic Bedrock API key, or Anthropic Bedrock access key.
- * Codex accepts an OpenAI API key.
-
- See [connecting Claude Code credentials](/platform/harnesses/authentication/#connecting-claude-code-credentials) and [connecting Codex credentials](/platform/harnesses/authentication/#connecting-codex-credentials) for how to obtain each key.
- :::
-
-4. Choose a **Model** from that harness's own catalog.
-5. In the top-right corner, click **Save**.
-
-With a Warp-managed factory, you can edit harness, auth, and model from the dashboard. A GitHub-backed factory sets them through [`agentDefaults.harness` or a per-agent `harness` override](/factories/factory-as-code/#agentdefaultsharness) in the definition files. For an example, see [`03-multi-harness`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/03-multi-harness).
-
-## Add custom agents and automations
-
-Add a custom agent for a role that needs separate instructions, configuration, and runs.
-
-For a Warp-managed factory, open **Agents** in the [factory dashboard](/factories/factory-dashboard/), click **New**, then click **Custom agent**. For a GitHub-backed factory, add `agents//agent.md`. See the [`agent.md` configuration keys](/factories/factory-as-code/#agentsnameagentmd).
-
-Custom agents have no built-in skills. Add [factory skills](/factories/factory-skills/) based on who needs them:
-
-* **One agent** - Put the skill under `agents//skills/`.
-* **Every agent** - Put the skill under `skills/`.
-
-### Choose a configured factory agent
-
-Use `run_agents` when the foreman should give work to one of the agents configured in your factory. The foreman receives a list of those agents, with a unique ID (UID) for each one.
-
-Run the child remotely by setting the call's `remote` field, then copy the chosen agent's UID into `agent_run_configs[].agent_identity_uid`. Only use UIDs from the list, and select an agent for every child in the call. The `name` field only labels the child run; it doesn't choose the factory agent.
-
-Warp uses the UID to load that agent's configured environment, runner, host, harness, and model unless the call overrides them. To start a child without factory configuration, use [multi-agent orchestration](/platform/orchestration/) from any Warp conversation.
-
-Automations start a chosen agent on a [schedule](/factories/factory-as-code/#triggersschedule) or when an event fires. They're one more way for work to enter your factory; the foreman still coordinates whatever they start. For all the ways to route work into a factory, see [connect your factory](/factories/connect-your-factory/).
+For new roles, skills, and foreman dispatch, see [Creating custom agents](/factories/factory-agents/creating-custom-agents/). To start agents from schedules and events, use [factory automations](/factories/automations/).
## Human decision points and permissions
| Decision | Default behavior | What enforces it |
| --- | --- | --- |
| Spec approval | The foreman asks a human to clarify ambiguity and approve every spec | Workflow policy in the foreman's instructions, which your team can change |
-| Merging | Agents never merge; the foreman hands the finished pull request to a human | Your repository's permissions decide who can approve and merge |
+| Merging | The foreman hands you the finished pull request. Agents never merge on your behalf. | Your repository's permissions decide who can approve and merge |
| Runtime access | Each agent reaches only the repositories, secrets, and MCP servers in its configuration | Platform configuration and the permissions of the connected providers |
-The first two rows are conventions: they live in the foreman's instructions and your repository settings, and your team can change them. Access is different. What an agent can reach comes from its configuration and the permissions of the connected providers, never from its instructions — changing what an agent is told to do doesn't change what it's able to do.
+Your team can change the spec-approval policy in the foreman's instructions. Repository permissions and branch protection control who can approve and merge pull requests. Access is different. What an agent can reach comes from its configuration and the permissions of the connected providers, never from its instructions — changing what an agent is told to do doesn't change what it's able to do.
So enforce with the real controls: branch protection and repository permissions decide who merges, and each agent's configuration decides what it can reach.
-Next, capture these choices in [factory definitions as code](/factories/factory-as-code/).
+## Related pages
+
+* [Configuring factory agents](/factories/factory-agents/configuration/)
+* [Creating custom agents](/factories/factory-agents/creating-custom-agents/)
+* [How Warp Factories work](/factories/how-factories-work/)
+* [Factory skills](/factories/factory-skills/)
+* [Definitions as code](/factories/factory-as-code/)
diff --git a/src/content/docs/factories/factory-agents/configuration.mdx b/src/content/docs/factories/factory-agents/configuration.mdx
new file mode 100644
index 000000000..966486576
--- /dev/null
+++ b/src/content/docs/factories/factory-agents/configuration.mdx
@@ -0,0 +1,91 @@
+---
+title: Configuring factory agents
+description: >-
+ Configure a factory agent's instructions, tools, model, and harness,
+ including authentication for Claude Code and Codex.
+---
+import { VARS } from '@data/vars';
+
+Change how an existing factory agent works by editing its instructions, tools, and runtime in the {VARS.FACTORY_WEB_APP} or its definition files.
+
+## Prerequisites
+
+* [Editor access to this factory, or team or workspace admin access](/factories/infrastructure-and-security/#factory-roles-and-permissions).
+* An existing factory agent. See [About factory agents](/factories/factory-agents/) for the default roles, or [Creating custom agents](/factories/factory-agents/creating-custom-agents/) to add a role.
+
+
+
+## Edit agent settings and instructions
+
+For a Warp-managed factory, edit agent settings in the web app. For a GitHub-backed factory, settings are read-only in the web app; edit the [factory definition files](/factories/factory-as-code/) instead. See [Where the definition lives](/factories/factory-as-code/#where-the-definition-lives).
+
+1. In the web app sidebar, click your factory to expand it, then click **Agents**.
+
+
+ 
+ The Agents page lists a factory's foreman and default agents.
+
+
+2. Click an agent to open its **Settings** tab.
+
+
+ 
+ The Settings tab contains the agent's description and resources.
+
+
+3. Edit the agent description, harness, model, runner, host, [MCP servers](/platform/mcp/), or [secrets](/platform/secrets/).
+
+4. To change the agent's instructions, click **Prompt** and edit the prompt.
+
+5. In the top-right corner, click **Save**.
+
+## Choose models and harnesses per agent
+
+Choose each agent's model and harness in its settings. Supported harnesses include the Warp Agent, Claude Code, and Codex. A foreman using Claude Code or Codex can still dispatch other factory agents, whose runs are tracked as its children.
+
+Third-party harnesses require a paid plan. On the Free plan, agents use the Warp Agent. See [Warp pricing](https://www.warp.dev/pricing) for plan details.
+
+Default model IDs change over time, so choose based on what each agent has to do well:
+
+| Agent | What to optimize for |
+| --- | --- |
+| Foreman | Orchestration, instruction following, and long-running conversations |
+| Triage | Research, evidence gathering, and working with connected tools |
+| Spec | Synthesizing requirements, technical reasoning, and precise writing |
+| Implement | Coding strength, with a harness that fits your repositories and toolchain |
+| Review | A different model or harness from the implement agent, so the two don't share blind spots |
+
+The model picker also includes custom routers from factories you can access. See [Agent model choice](/agents/inference/model-choice/), [Custom routers](/agents/inference/custom-routers/), and [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) for available options.
+
+### Configuring a third-party harness
+
+Change an agent's harness to Claude Code or Codex to run it with that provider's own coding tool.
+
+1. In the web app sidebar, click your factory to expand it, then click **Agents**.
+2. Click an agent to open its **Settings** tab.
+3. In the "Harness" dropdown, choose **Claude Code** or **Codex**. The "Auth" field appears for these harnesses.
+4. In the "Auth" field, choose a compatible, team-owned secret from the list or click **New auth secret** to create one.
+
+
+ 
+ The Auth dropdown appears when a third-party harness is selected.
+
+
+ :::note
+ * Claude Code accepts an Anthropic API key, Anthropic Bedrock API key, or Anthropic Bedrock access key.
+ * Codex accepts an OpenAI API key.
+
+ See [connecting Claude Code credentials](/platform/harnesses/authentication/#connecting-claude-code-credentials) and [connecting Codex credentials](/platform/harnesses/authentication/#connecting-codex-credentials) for how to obtain each key.
+ :::
+
+5. In the "Model" dropdown, choose a model from that harness's catalog.
+6. In the top-right corner, click **Save**.
+
+With a Warp-managed factory, you can edit harness, auth, and model from the dashboard. A GitHub-backed factory sets them through [`agentDefaults.harness` or a per-agent `harness` override](/factories/factory-as-code/#agentdefaultsharness) in the definition files. For an example, see [`03-multi-harness`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/03-multi-harness).
+
+## Related pages
+
+* [About factory agents](/factories/factory-agents/) - Understand responsibilities and human decision points
+* [Creating custom agents](/factories/factory-agents/creating-custom-agents/)
+* [Factory skills](/factories/factory-skills/)
+* [Definitions as code](/factories/factory-as-code/)
diff --git a/src/content/docs/factories/factory-agents/creating-custom-agents.mdx b/src/content/docs/factories/factory-agents/creating-custom-agents.mdx
new file mode 100644
index 000000000..01f2a3bc5
--- /dev/null
+++ b/src/content/docs/factories/factory-agents/creating-custom-agents.mdx
@@ -0,0 +1,62 @@
+---
+title: Creating custom agents
+description: >-
+ Create a custom factory agent, add skills, and configure how the foreman
+ dispatches it.
+---
+import { VARS } from '@data/vars';
+
+Add a custom agent for work that needs its own instructions, configuration, and runs. For example, create a documentation agent to update reference pages after code changes.
+
+## Prerequisites
+
+* [Editor access to this factory, or team or workspace admin access](/factories/infrastructure-and-security/#factory-roles-and-permissions).
+* An existing factory. Follow the [Warp Factories quickstart](/factories/quickstart/) to create one.
+
+## Create an agent in the web app
+
+For a Warp-managed factory, create the agent in the {VARS.FACTORY_WEB_APP}. For a GitHub-backed factory, use [definition files](#define-an-agent-in-code) instead.
+
+1. In the web app sidebar, click your factory to expand it, then click **Agents**.
+2. Click **New**, then **Custom agent**.
+3. Enter an agent name and a description of its responsibilities.
+4. Under "Agent resources", choose the agent's [harness, model, host, and runner](/factories/factory-agents/configuration/) as needed. Add [MCP servers](/platform/mcp/) and [secrets](/platform/secrets/) for its tools.
+5. Under "Agent prompt", enter the agent's instructions.
+6. In the top-right corner, click **Save**.
+
+The new agent appears on the factory's **Agents** page. Agent names can't be changed after creation.
+
+
+
+## Define an agent in code
+
+For a GitHub-backed factory, add `agents//agent.md` to the factory's definition repository, replacing `` with the agent's directory name. Define its instructions and configuration using the [`agent.md` configuration keys](/factories/factory-as-code/#agentsnameagentmd). Follow your repository's pull request process to apply the change.
+
+## Add skills
+
+Custom agents have no built-in skills. Add [factory skills](/factories/factory-skills/) where needed:
+
+* **One agent** - `agents//skills/`
+* **All agents** - `skills/`
+
+
+
+## Dispatch a configured agent
+
+The foreman uses `run_agents` to dispatch configured factory agents. It receives a list of available agents and their unique IDs (UIDs), then:
+
+1. The foreman chooses an agent from the available list.
+2. It sets `remote` to run the child in the cloud.
+3. For each child, it supplies the selected agent's UID in `agent_run_configs[].agent_identity_uid`.
+
+The `name` field only labels the child run. Unless overridden, the run uses the selected agent's environment, runner, host, harness, and model.
+
+You can start child agents without factory configuration through [multi-agent orchestration](/platform/orchestration/) from any Warp conversation. For scheduled or event-driven work, use [factory automations](/factories/automations/). The foreman coordinates the work they start.
+
+## Related pages
+
+* [About factory agents](/factories/factory-agents/) - Understand default roles and human decision points
+* [Configuring factory agents](/factories/factory-agents/configuration/) - Edit instructions, models, harnesses, and tools
+* [Factory skills](/factories/factory-skills/)
+* [Factory automations](/factories/automations/)
+* [Definitions as code](/factories/factory-as-code/)
diff --git a/src/content/docs/factories/factory-api.mdx b/src/content/docs/factories/factory-api.mdx
index f4e1d54f4..7b85e12e8 100644
--- a/src/content/docs/factories/factory-api.mdx
+++ b/src/content/docs/factories/factory-api.mdx
@@ -27,7 +27,7 @@ Factory endpoints are one of several ways to get work into a factory, and each f
* **A coding agent session**, local or in another MCP client - use [Factory MCP](/factories/factory-mcp/) to send work in or pull a task down to work on locally.
* **A chat platform or issue tracker your team already uses** - connect it as an [integration](/factories/connect-your-factory/) so matching events start work automatically.
-See [connect your factory](/factories/connect-your-factory/) for the full comparison across every intake path.
+See [Connect your factory](/factories/connect-your-factory/) for the full comparison across every intake path.
## Choosing an endpoint family
@@ -39,7 +39,7 @@ Use factory endpoints to find or start work on a factory. Use Agent & run endpoi
| 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/runs` |
-| Build a multi-agent orchestration | Agent & run endpoints - see [multi-agent orchestration](/platform/orchestration/) |
+| Build a multi-agent orchestration | Agent & run endpoints - see [Multi-agent orchestration](/platform/orchestration/) |
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.
diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx
index c60286060..1f07a2989 100644
--- a/src/content/docs/factories/factory-as-code.mdx
+++ b/src/content/docs/factories/factory-as-code.mdx
@@ -1,14 +1,14 @@
---
title: Factory definition syntax
description: >-
- Look up the files and public keys in a factory definition: factory.yaml,
- agents, automations, runners, routers, benchmarks, scorers, skills, and webhooks.
+ Look up the file structure, configuration fields, and supported values
+ used to define factory agents, automations, and other resources.
sidebar:
label: "Factory definition"
---
import { VARS } from '@data/vars';
-A factory definition is a versioned tree of YAML and Markdown files rooted at `factory.yaml`. It can define agents, automations, runners, model routers, benchmarks, scorers, skills, and webhooks. Keys are case-sensitive, and Warp applies file changes automatically.
+A factory definition is a versioned tree of YAML and Markdown files rooted at `factory.yaml`. It can define agents, automations, runners, model routers, benchmarks, scorers, skills, and webhooks. Keys are case-sensitive.
For working definitions you can copy, see [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples).
@@ -23,35 +23,69 @@ Both modes share the file format. You can link a Warp-managed factory to GitHub
Work items, runs, and metrics live in the web app, not in the definition.
-## Validate a definition
+## Directory structure
-Warp validates syntax, required fields, and resource access before applying a definition: on save for a Warp-managed factory, and in pull requests to a GitHub-backed factory's production branch.
+Paths identify resources: `agents/reviewer/agent.md` defines an agent named `reviewer`. Some resources also declare a name or display label in their fields, as described below.
-### Pull request checks
+```text
+factory.yaml
+agents/
+ foreman/
+ agent.md
+ skills/
+ incident-triage/
+ SKILL.md
+ reviewer/
+ agent.md
+automations/
+ labeled-issue/
+ automation.md
+runners/
+ linux-build.yaml
+routers/
+ by-task.yaml
+benchmarks/
+ pull-request-review/
+ suite.yaml
+ tasks/
+ broken-doc-link.yaml
+scorers/
+ tests-run/
+ scorer.md
+skills/
+ repository-conventions/
+ SKILL.md
+webhooks/
+ internal-ci.yaml
+```
-Every pull request to the production branch gets a **warp/factory-config** check. It reports errors by file and line or summarizes the resources a valid change will create, update, or delete. Pull requests that don't change the definition pass immediately.
+See the [example factory definition](#example-factory-definition), the minimal [`01-single-repo-quickstart`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/01-single-repo-quickstart), or the full [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr).
+
+## Validate a definition
-Require the check in branch protection to block invalid definitions.
+Warp validates syntax, required fields, and resource access before applying a definition. A Warp-managed factory validates on save; a GitHub-backed factory validates in pull requests to its production branch. Warp applies the definition as one unit and keeps the last valid definition if validation fails.
-Warp applies a definition as one unit. If validation fails, the factory keeps its last valid definition.
+### Pull request checks
-For subdirectory check names and troubleshooting, see [factory-definition pull request checks](/factories/integrations/github/#factory-definition-pull-request-checks).
+The `warp/factory-config` check validates definition changes against your team and factory. For check results, branch protection, and troubleshooting, see [factory-definition pull request checks](/factories/integrations/github/#factory-definition-pull-request-checks).
### Validate locally or in CI
-Run [`validate_factory_files.py`](https://github.com/warpdotdev/warp-factory-examples/blob/main/scripts/validate_factory_files.py) before opening a pull request or in CI. It requires Python 3, but no Warp login or existing factory.
+The [`warp-factory-examples`](https://github.com/warpdotdev/warp-factory-examples) repository includes [`validate_factory_files.py`](https://github.com/warpdotdev/warp-factory-examples/blob/main/scripts/validate_factory_files.py). From a checkout of that repository, run the script against your definition's root directory. It requires Python 3 and a network connection to Warp's validation service, but no Warp login or existing factory.
```bash
-python3 scripts/validate_factory_files.py path/to/factory-root
+python3 scripts/validate_factory_files.py FACTORY_ROOT
```
-Pass the factory root to check cross-file references. The script reports errors by file and line. The GitHub check also validates team- and factory-dependent settings.
+Replace `FACTORY_ROOT` with the directory containing `factory.yaml`. The script submits factory, agent, automation, runner, and scorer files to Warp's validation service and reports errors by file and line. It doesn't submit routers, benchmarks, webhooks, or skills.
+
+A pass doesn't confirm runner references or team-dependent resources such as secrets and environments. Use the [factory pull request checks](#pull-request-checks) and validation when the definition is applied for the remaining checks.
For a CI job built on the script, see the example repository's [validation workflow](https://github.com/warpdotdev/warp-factory-examples/blob/main/.github/workflows/validate.yml).
### Validate with a coding agent
-* **Warp Agent** - Ask the agent to change or check the definition. Its `factory-files` skill validates before opening a pull request. For example: "Add a nightly dependency-audit automation and validate the definition."
+* **Warp Agent** - Ask the Warp Agent to change or check the definition. Its `factory-files` skill validates before opening a pull request. For example: "Add a nightly dependency-audit automation and validate the definition."
* **Factory MCP** - Connect another coding agent to [Factory MCP](/factories/factory-mcp/) for schema and validation tools.
* **Other agents** - Have the agent run the [validator script](#validate-locally-or-in-ci).
@@ -63,7 +97,18 @@ Warp publishes unauthenticated JSON Schemas for editor completion and validation
* `https://app.warp.dev/api/v1/factory-files/schemas/v1alpha1` - Returns all `v1alpha1` documents, keyed by document name.
* `https://app.warp.dev/api/v1/factory-files/schemas/v1alpha1/` - Returns one document for use as a schema reference.
-Documents include `factory.schema.json` for `factory.yaml`; `agent.schema.json`, `automation.schema.json`, and `scorer.schema.json` for Markdown frontmatter; `runner.schema.json`, `router.schema.json`, `webhook.schema.json`, `benchmark_suite.schema.json`, and `benchmark_suite_task.schema.json` for YAML resources; and `common.schema.json` for shared definitions.
+| Schema document | Applies to |
+| --- | --- |
+| `factory.schema.json` | `factory.yaml` |
+| `agent.schema.json` | Agent Markdown frontmatter |
+| `automation.schema.json` | Automation Markdown frontmatter |
+| `scorer.schema.json` | Scorer Markdown frontmatter |
+| `runner.schema.json` | Runner YAML files |
+| `router.schema.json` | Model-router YAML files |
+| `webhook.schema.json` | Webhook YAML files |
+| `benchmark_suite.schema.json` | Benchmark suite YAML files |
+| `benchmark_suite_task.schema.json` | Benchmark task YAML files |
+| `common.schema.json` | Shared field definitions |
For completion and inline validation in the VS Code YAML extension, add the document URL on the first line:
@@ -73,45 +118,7 @@ schemaVersion: v1alpha1
name: payments-factory
```
-YAML schemas don't apply to Markdown frontmatter. Use one of the [definition validators](#validate-a-definition) for Markdown files.
-
-## Directory structure
-
-Each resource takes its name from its path: `agents/reviewer/agent.md` defines an agent named `reviewer`.
-
-```text
-factory.yaml
-agents/
- foreman/
- agent.md
- skills/
- incident-triage/
- SKILL.md
- reviewer/
- agent.md
-automations/
- labeled-issue/
- automation.md
-runners/
- linux-build.yaml
-routers/
- by-task.yaml
-benchmarks/
- pull-request-review/
- suite.yaml
- tasks/
- broken-doc-link.yaml
-scorers/
- tests-run/
- scorer.md
-skills/
- repository-conventions/
- SKILL.md
-webhooks/
- internal-ci.yaml
-```
-
-See the [example factory definition](#example-factory-definition), the minimal [`01-single-repo-quickstart`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/01-single-repo-quickstart), or the full [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr).
+This YAML-extension configuration doesn't validate Markdown frontmatter. Use one of the [definition validators](#validate-a-definition) for Markdown files.
## `factory.yaml`
@@ -128,35 +135,26 @@ agentDefaults:
model: auto
```
-### `schemaVersion`
-
-**Required.**
-Every definition sets `schemaVersion: v1alpha1`.
-
-### `name`
-
-**Required.**
-The factory's name.
-
-### `description`
-
-**Optional.**
-What the factory is for.
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `schemaVersion` | Yes | None | Set to `v1alpha1`. |
+| `name` | Yes | None | The factory's name. |
+| `description` | No | Not specified | What the factory is for. |
### `alias`
**Optional.**
-The handle used to @-mention the foreman on platforms such as Slack and Linear. The factory dashboard labels it **Foreman name**. It accepts up to 60 letters, numbers, spaces, `.`, `_`, and `-`, and is case-insensitively unique in the workspace.
+The handle used to @-mention the foreman on platforms such as Slack and Linear. The factory dashboard labels it "Foreman name". It accepts up to 60 letters, numbers, spaces, `.`, `_`, and `-`, and is case-insensitively unique in the workspace.
### `credentialStrategy`
**Optional.**
-Whose credentials runs use: `EXECUTOR` for the executing principal, or `CREATOR` for the user who created the run. `CREATOR` requires a paid plan. Omit the key to preserve the setting; otherwise, it defaults to `EXECUTOR`. Agents can override it by role.
+Whose credentials runs use: `EXECUTOR` for the identity executing the run, or `CREATOR` for the user who created it. `CREATOR` requires a paid plan. Omitting the key preserves the stored setting; the factory default is `EXECUTOR`. Agents can override the strategy by role.
### `automations`
**Optional.**
-Factory-wide automation settings. `automations.githubOnboardingNotices` defaults to `true`. Set it to `false` to suppress future GitHub account-connection and team-membership notices without changing access requirements. Users without a GitHub account connected to Warp or active membership in the factory’s Warp team still cannot trigger its GitHub automations. Disabling notices can leave them without an explanation.
+Factory-wide automation settings. `automations.githubOnboardingNotices` defaults to `true`. Set it to `false` to suppress GitHub account-connection and team-membership notices. Users still need a connected GitHub account and active membership in the factory's Warp team to trigger its GitHub automations.
```yaml title="factory.yaml"
automations:
@@ -220,8 +218,13 @@ mcpServers:
**Optional.**
Cloud-provider identity federation for agent runs:
-* `cloudProviders.gcp` configures Google Cloud. It requires `cloudProviders.gcp.projectNumber`, `cloudProviders.gcp.workloadIdentityFederationPoolId`, and `cloudProviders.gcp.workloadIdentityFederationProviderId`. Quote `projectNumber` so YAML keeps it as a string. Optional `cloudProviders.gcp.serviceAccountEmail` selects a service account.
-* `cloudProviders.aws.roleArn` configures AWS and is required for that provider.
+| Field under `cloudProviders` | Required | Description |
+| --- | --- | --- |
+| `gcp.projectNumber` | For Google Cloud | Project number. Quote it so YAML keeps it as a string. |
+| `gcp.workloadIdentityFederationPoolId` | For Google Cloud | Workload identity federation pool ID. |
+| `gcp.workloadIdentityFederationProviderId` | For Google Cloud | Workload identity federation provider ID. |
+| `gcp.serviceAccountEmail` | No | Service account to use. |
+| `aws.roleArn` | For AWS | Role ARN for agent runs. |
```yaml
cloudProviders:
@@ -251,12 +254,14 @@ integrations:
autoRespondToThreadReplies: false
```
-`integrations[].linear.teamIds` and `integrations[].jira.projectKeys` are accepted for compatibility but don't control issue discovery or routing. Warp omits them when rewriting the definition. Use automation filters such as `team_ids` and `project_keys`.
+For issue discovery and routing, use automation filters such as `team_ids` and `project_keys`.
-### `providers`
+### Compatibility fields
-**Optional.**
-Accepted as a legacy alias for [`cloudProviders`](#cloudproviders) with the same keys. Use `cloudProviders` in new files. Warp writes the canonical key when it updates an older definition.
+| Field | Behavior |
+| --- | --- |
+| `integrations[].linear.teamIds`, `integrations[].jira.projectKeys` | Accepted but ignored for issue discovery and routing; omitted when Warp rewrites the definition. |
+| `providers` | Optional legacy alias for [`cloudProviders`](#cloudproviders), with the same keys. Use `cloudProviders` in new files; Warp writes that key when updating older definitions. |
### `scorerDefaults`
@@ -275,7 +280,7 @@ Configures scheduled self-improvement for a GitHub-backed factory:
### `agentDefaults`
**Required.**
-Execution defaults inherited by every agent. Declare exactly one of `model` or `harness`. Agents can override these defaults.
+Execution defaults inherited by every agent. Declare exactly one of [`model`](#agentdefaultsmodel) or [`harness`](#agentdefaultsharness). Agents can override these defaults.
```yaml
agentDefaults:
@@ -284,7 +289,14 @@ agentDefaults:
environmentId: PAYMENTS_ENVIRONMENT_ID
```
-### `agentDefaults.model`
+| Field under `agentDefaults` | Required | When omitted | Description |
+| --- | --- | --- | --- |
+| `runner` | No | No runner selected here | Name of a runner defined under [`runners/`](#runnersnameyaml). See [runner OS requirements](/factories/runners/#operating-systems) before choosing a factory default. |
+| `environmentId` | No | Warp manages the workspace from the factory's repositories | ID of an existing [environment](/platform/environments/). |
+| `secrets` | No | No defaults declared here | Managed secrets inherited by agents without their own list. An agent-level list replaces this list; factory-wide [`secrets`](#secrets) still apply. |
+| `mcpServers` | No | No defaults declared here | MCP servers inherited by agents without their own map. An agent-level map replaces this map; factory-wide servers still apply. Uses the [`mcpServers`](#mcpservers) syntax. |
+
+#### `agentDefaults.model`
**Conditionally required.** Set exactly one of `model` or `harness`.
The `model_id` used for runs. See [model choice for agents](/agents/inference/model-choice/). `model` is shorthand for the Warp Agent harness:
@@ -303,7 +315,7 @@ harness:
`model` and `harness` are mutually exclusive everywhere they appear.
-### `agentDefaults.harness`
+#### `agentDefaults.harness`
**Conditionally required.** Set exactly one of `model` or `harness`.
The run harness and model. The object requires `type` and `model`. `type` accepts `oz`, `claude`, `codex`, or `claude-code` (an alias for `claude`). Prefer the canonical [harness identifier](/platform/harnesses/#harness-identifiers) used by the CLI and the {VARS.WARP_PLATFORM_API}. See [supported harnesses](/platform/harnesses/) for availability and behavior.
@@ -318,38 +330,23 @@ harness:
secretName: CODEX_API_KEY
```
-Optional `auth` requires `source`. `managedSecret` also requires `agentDefaults.harness.auth.secretName`; `workerEnvironment` rejects it and requires a self-hosted `workerHost`. Set the source with `agentDefaults.harness.auth.source`.
+Optional `auth` requires `source`:
-The `oz` harness supplies its own credentials and rejects `auth` and `reasoningLevel`. Third-party harnesses accept optional `reasoningLevel`.
-
-For per-agent harnesses and managed-secret authentication, see [`03-multi-harness`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/03-multi-harness). To use the dashboard instead, see [configuring a third-party harness](/factories/factory-agents/#configuring-a-third-party-harness).
-
-### `agentDefaults.runner`
-
-**Optional.**
-The name of a runner defined under [`runners/`](#runnersnameyaml) that provides the compute for runs.
-
-### `agentDefaults.environmentId`
-
-**Optional.**
-The ID of an existing [environment](/platform/environments/) for runs. Omit it to let Warp manage the workspace from the factory's repositories.
-
-### `agentDefaults.secrets`
-
-**Optional.**
-Managed secrets inherited by agents without their own `secrets` list. An agent-level list replaces this one; factory-wide [`secrets`](#secrets) still apply.
+| `auth.source` | `auth.secretName` | Requirement |
+| --- | --- | --- |
+| `managedSecret` | Required | Name of the managed authentication secret. |
+| `workerEnvironment` | Not allowed | Requires a self-hosted `workerHost`; uses authentication from that worker's environment. |
-### `agentDefaults.mcpServers`
+The `oz` harness supplies its own credentials and rejects `auth` and `reasoningLevel`. Third-party harnesses accept optional `reasoningLevel`.
-**Optional.**
-MCP servers inherited by agents without their own map, using the [`mcpServers`](#mcpservers) syntax. An agent-level map replaces this one; factory-wide servers still apply.
+For per-agent harnesses and managed-secret authentication, see [`03-multi-harness`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/03-multi-harness). To use the dashboard instead, see [configuring a third-party harness](/factories/factory-agents/configuration/#configuring-a-third-party-harness).
-### `agentDefaults.workerHost`
+#### `agentDefaults.workerHost`
**Optional.**
Where runs execute: `warp` for Warp-hosted compute, or the ID of a connected [self-hosted worker](/factories/self-hosting/). Omit the key for the workspace default. At the agent or automation level, use `null` or an empty string to clear an inherited host. Configure the backend on the worker; the definition selects only the worker and runner.
-### `agentDefaults.computerUseModel`
+#### `agentDefaults.computerUseModel`
**Optional.**
The `model_id` used by [Computer Use](/agents/capabilities/computer-use/). Omit it for automatic selection.
@@ -399,22 +396,25 @@ Review each pull request against the repository's standards. Request
changes when tests are missing; never approve your own edits.
```
-All frontmatter keys are optional:
+All frontmatter keys are optional.
-* `description` - What the agent does.
-* [`agentType`](#agenttype) - The agent's role.
-* `credentialStrategy` - Overrides the factory-level [`credentialStrategy`](#credentialstrategy). Omit it to keep the agent's current setting.
-* `spawnableBy` - Agents allowed to start this agent. Omit it to allow only the foreman, use an empty list to allow none, or list exact agent names.
-* `model` or `harness`, `runner`, `environmentId`, `secrets`, `mcpServers`, `workerHost`, `computerUseModel` - Override the corresponding [`agentDefaults`](#agentdefaults).
-* `idleTimeoutMinutes` - Keeps a completed session available for follow-up for 1 through 60 minutes. Omit it or use `null` to inherit. Without an inherited or run-level value, Warp uses 10 minutes, or 60 minutes for an orchestrated child run.
-* `required_repos` - Repositories prepared for every run by this agent. Each item requires `required_repos[].owner` and `required_repos[].name`. Use `required_repos[].codeForge` to distinguish the same repository across hosts.
+| Field | Description |
+| --- | --- |
+| `description` | What the agent does. |
+| [`agentType`](#agenttype) | The agent's role. |
+| `credentialStrategy` | Overrides the factory-level [`credentialStrategy`](#credentialstrategy). Omit it to keep the agent's current setting. |
+| `spawnableBy` | Agents allowed to start this agent. Omit it to allow only the foreman, use an empty list to allow none, or list exact agent names. |
+| `model`, `harness` | Override the corresponding [`agentDefaults`](#agentdefaults). Set at most one. |
+| `runner`, `environmentId`, `secrets`, `mcpServers`, `workerHost`, `computerUseModel` | Override the corresponding [`agentDefaults`](#agentdefaults), subject to each field's inheritance rules. |
+| `idleTimeoutMinutes` | Keeps a completed session available for follow-up for 1 through 60 minutes. Omit it or use `null` to inherit. Without an inherited or run-level value, Warp uses 10 minutes, or 60 minutes for an orchestrated child run. |
+| `required_repos` | Repositories prepared for every run by this agent. Each entry requires `owner` and `name`; use `codeForge` to distinguish the same repository across hosts. |
An agent's `harness` object is a sparse override of [`agentDefaults.harness`](#agentdefaultsharness). Set `auth` to `null` to clear inherited authentication. Agent-level `mcpServers` entries use the same transport keys as the factory-level [`mcpServers`](#mcpservers) map.
### `agentType`
**Optional.**
-The agent's role: `CUSTOM` (default), `FOREMAN` (alias `MAIN`), `TRIAGE`, `SPEC`, `IMPLEMENT`, `REVIEW`, or `VERIFY`. Every factory has one foreman, which serves as its entry point and the default automation target. See [factory agents](/factories/factory-agents/) for role behavior.
+The agent's role: `CUSTOM` (default), `FOREMAN` (alias `MAIN`), `TRIAGE`, `SPEC`, `IMPLEMENT`, `REVIEW`, or `VERIFY`. Every factory has one foreman, which serves as its entry point and the default automation target. See [About factory agents](/factories/factory-agents/) for role behavior.
## `automations//automation.md`
@@ -436,42 +436,41 @@ Review the labeled issue and decide the next required stage. Return
unresolved product questions to a human.
```
-### `enabled`
-
-**Optional.**
-Turns the automation on or off. Defaults to `true`.
-
-### `agent`
-
-**Optional.**
-The agent that handles the automation's runs. Defaults to the foreman.
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | No | `true` | Turns the automation on or off. |
+| `agent` | No | Foreman | The agent that handles the automation's runs. |
### `triggers`
**Required.**
-One or more events that start runs. Every automation requires `triggers`. Each trigger declares `provider` and `event`, and can include `filter` or, for scheduled runs, `schedule`.
+One or more events that start runs. Each trigger declares `provider` and `event`, and can include `filter` or, for scheduled runs, `schedule`.
The providers and their events:
-* `azure_devops` - `pull_request_closed`, `pull_request_commented`, `pull_request_created`, `pull_request_mentioned`, `pull_request_merged`, `pull_request_updated`, `push`, `work_item_assigned`, `work_item_created`, `work_item_labeled`, `work_item_mentioned`
-* `github` - `check_run_rerequested`, `check_suite_completed`, `check_suite_rerequested`, `issue_assigned`, `issue_commented`, `issue_created`, `issue_labeled`, `issue_mentioned`, `pull_request_assigned`, `pull_request_closed`, `pull_request_commented`, `pull_request_dequeued`, `pull_request_enqueued`, `pull_request_labeled`, `pull_request_mentioned`, `pull_request_merged`, `pull_request_opened`, `pull_request_ready`, `pull_request_reopened`, `pull_request_review_requested`, `pull_request_review_submitted`, `pull_request_synchronized`, `push`, `workflow_run_completed`
-* `gitlab` - `bot_mentioned`, `merge_request`, `push`
-* `linear` - `agent_session_created`, `comment_created`, `issue_assigned`, `issue_created`, `issue_labeled`, `issue_state_changed`
-* `jira` - `agent_session_created`, `issue_created`, `issue_labeled`, `status_changed`
-* `slack` - `app_mention`, `member_joined_channel`, `message_dm`, `message_im`, `message_mpim`, `message_posted`, `reaction_added`
-* `teams` - `app_mention`, `message_posted`
-* `schedule` - `cron_fired`
-* `webhook` - `received`
-* `factory` - `work_item_stage_changed`
+| Provider | Events |
+| --- | --- |
+| `azure_devops` (pull requests and pushes) | `pull_request_closed`, `pull_request_commented`, `pull_request_created`, `pull_request_mentioned`, `pull_request_merged`, `pull_request_updated`, `push` |
+| `azure_devops` (work items) | `work_item_assigned`, `work_item_created`, `work_item_labeled`, `work_item_mentioned` |
+| `factory` | `work_item_stage_changed` |
+| `github` (issues) | `issue_assigned`, `issue_commented`, `issue_created`, `issue_labeled`, `issue_mentioned` |
+| `github` (pull requests) | `pull_request_assigned`, `pull_request_closed`, `pull_request_commented`, `pull_request_dequeued`, `pull_request_enqueued`, `pull_request_labeled`, `pull_request_mentioned`, `pull_request_merged`, `pull_request_opened`, `pull_request_ready`, `pull_request_reopened`, `pull_request_synchronized` |
+| `github` (reviews) | `pull_request_review_requested`, `pull_request_review_submitted` |
+| `github` (code and CI) | `check_run_rerequested`, `check_suite_completed`, `check_suite_rerequested`, `push`, `workflow_run_completed` |
+| `gitlab` | `bot_mentioned`, `merge_request`, `push` |
+| `jira` | `agent_session_created`, `issue_created`, `issue_labeled`, `status_changed` |
+| `linear` | `agent_session_created`, `comment_created`, `issue_assigned`, `issue_created`, `issue_labeled`, `issue_state_changed` |
+| `schedule` | `cron_fired` |
+| `slack` | `app_mention`, `member_joined_channel`, `message_dm`, `message_im`, `message_mpim`, `message_posted`, `reaction_added` |
+| `teams` | `app_mention`, `message_posted` |
+| `webhook` | `received` |
Slack, Microsoft Teams, Linear, and Jira triggers require the matching [integration](/platform/integrations/) to be connected. Code-forge triggers use the factory's repositories and provider connection; see the [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), and [Azure DevOps](/factories/integrations/azure-devops/) integration guides. `webhook` triggers listen to [custom webhooks](/factories/webhooks/) declared under [`webhooks/`](#webhooksnameyaml).
### `triggers[].filter`
**Conditionally required.** Required for `webhook` / `received`; optional for other triggers.
-Narrows which events start runs. Available keys depend on the provider and event, such as `repos`, `labels`, and `authors` for GitHub or `channels`, `users`, and `keywords` for Slack. Keys combine with AND. Within a key's list, any value can match. An omitted key matches everything.
-
-Most canonical keys accept matcher objects with `in` and `not_in`. The name-based aliases `issues`, `projects`, `states`, `teams`, `channels`, `users`, and `itemUsers` take plain lists; Warp resolves their values to IDs.
+Narrows which events start runs. Available keys depend on the provider and event. Keys combine with AND; within an inclusion list, any value can match. Omitting an optional list filter adds no restriction, but provider defaults still apply. For example, GitHub's [`skip_bots` defaults to `all`](/factories/integrations/github/#events-from-bots-dont-start-work).
A `webhook` trigger for `received` requires `webhook_ids`: a one-item list with one webhook UID. It supports `in` only and doesn't accept a file name. To listen to multiple webhooks, add one trigger per UID. The optional `payload` pattern matches against the delivery's JSON body. See [webhook payload filters](/factories/automations/#payload-filters-for-webhook-triggers) for the pattern syntax.
@@ -479,7 +478,7 @@ Filter keys by provider:
* Factory: `stages`.
* Azure DevOps: `assignees`, `authors`, `base_branches`, `branches`, `labels`, `mentioned`, `repos`, `source_repos`, and `work_item_types`.
-* GitHub: `assignees`, `authors`, `baseBranches`, `base_branches`, `branches`, `conclusions`, `keywords`, `labels`, `mentioned`, `paths`, `prNumbers`, `pr_numbers`, `repos`, `review_states`, `reviewer_teams`, `reviewers`, and `workflows`.
+* GitHub: `assignees`, `authors`, `baseBranches`, `base_branches`, `branches`, `conclusions`, `keywords`, `labels`, `mentioned`, `paths`, `prNumbers`, `pr_numbers`, `repos`, `review_states`, `reviewer_teams`, `reviewers`, `skip_bots`, and `workflows`.
* GitLab: `actions`, `base_branches`, `branches`, `mentioned`, and `repos`.
* Jira: `keywords`, `labels`, `project_keys`, and `status_ids`.
* Linear: `assignee_ids`, `creator_ids`, `issue_ids`, `issues`, `keywords`, `labels`, `mentioned_user_ids`, `project_ids`, `projects`, `state_ids`, `states`, `team_ids`, and `teams`.
@@ -488,11 +487,11 @@ Filter keys by provider:
* Microsoft Teams: `channel_ids`, `keywords`, `team_ids`, and `user_ids`.
* Webhook: `payload` and `webhook_ids`.
-Matcher objects use `in` to include values and `not_in` to exclude them. Webhook `payload` also accepts `exists`. Microsoft Teams `team_ids` and `channel_ids` support only `in`.
+Most canonical keys accept matcher objects: `in` includes values and `not_in` excludes them. Webhook `payload` also accepts `exists`. Microsoft Teams `team_ids` and `channel_ids` support only `in`.
For Microsoft Teams, `team_ids` contains exactly one Microsoft Graph team UUID, and `channel_ids` contains at least one channel ID.
-`baseBranches` and `prNumbers` are authoring aliases for `base_branches` and `pr_numbers`. `teams`, `projects`, `states`, `issues`, `channels`, `users`, and `itemUsers` are name-based aliases for their `_ids` counterparts. An alias and its canonical key are mutually exclusive.
+`baseBranches` and `prNumbers` alias `base_branches` and `pr_numbers`. The name-based aliases `teams`, `projects`, `states`, `issues`, `channels`, `users`, and `itemUsers` take plain lists; Warp resolves their values to their `_ids` counterparts. An alias and its canonical key are mutually exclusive.
```yaml
triggers:
@@ -546,35 +545,35 @@ platform:
dockerImage: ubuntu:22.04
```
-### `description`
-
-**Optional.**
-A description of the runner.
-
-### `setupCommands`
-
-**Optional.**
-Shell commands that run in order while the sandbox is prepared.
+| Field | Required | When omitted | Description |
+| --- | --- | --- | --- |
+| `description` | No | Not specified | A description of the runner. |
+| `setupCommands` | No | No commands declared here | Shell commands that run in order while the sandbox is prepared. |
+| `failureSessionRetentionMinutes` | No | Uses the environment setting | Keeps a failed session open for inspection for 1 through 60 minutes. |
### `instanceShape`
**Optional.**
-The compute size. When set, `instanceShape` requires both `vcpus` and `memoryGb`. Omit it for the workspace default. Linux and Windows require powers of two. macOS accepts 4 vCPUs with 7 GB, 6 vCPUs with 14 GB, 8 vCPUs with 14 GB, 12 vCPUs with 28 GB, or 12 vCPUs with 56 GB.
+The compute size. Set both `vcpus` and `memoryGb`, or omit `instanceShape` for the workspace default.
+
+| Operating system | Supported sizes |
+| --- | --- |
+| Linux and Windows | Powers of two for both vCPUs and memory in GB. |
+| macOS | 4 vCPUs and 7 GB; 6 vCPUs and 14 GB; 8 vCPUs and 14 GB; 12 vCPUs and 28 GB; or 12 vCPUs and 56 GB. |
### `platform`
**Required.**
-The operating system and architecture. `os` accepts `linux` (default), `macos`, or `windows`. `arch` accepts `x86_64` (the Linux default and only Windows option) or `aarch64` (supported on Linux and required on macOS).
+The operating system and architecture:
-Linux runners require `platform.linux.dockerImage`. For macOS, `platform.mac.version` accepts `"14"`, `"15"`, `"26"`, or `"27"`. Quote the version; omitting `platform.mac` uses `"26"`.
+| `platform.os` | `platform.arch` | OS-specific settings |
+| --- | --- | --- |
+| `linux` (default) | `x86_64` (default) or `aarch64` | Requires `platform.linux.dockerImage`. |
+| `macos` | `aarch64` | `platform.mac.version` accepts `"14"`, `"15"`, `"26"`, or `"27"`. Quote the version; omitting `platform.mac` uses `"26"`. |
+| `windows` | `x86_64` | No OS-specific image setting. |
For a private Linux image, set `linux.registryCredentialSecretName` to the name of a managed Docker registry (`docker_registry`) or AWS ECR (`aws_ecr_credential`) credential. The credential's registry host must match the host in `linux.dockerImage`.
-### `failureSessionRetentionMinutes`
-
-**Optional.**
-Keeps a failed session open for inspection for 1 through 60 minutes. Omit it to use the environment setting.
-
## `routers/.yaml`
**Optional resource.**
@@ -598,7 +597,12 @@ routing:
model: claude-4-8-opus-high
```
-For `type: complexity`, optional `routing.easy`, `routing.medium`, and `routing.hard` map complexity levels to concrete models. For `type: prompt`, `routing` is an ordered list of `routing.description` and `routing.model` pairs. Each pair requires both fields. `routing` is optional for either type. Targets must be concrete supported models, not Auto models or other routers. See [custom model routers](/agents/inference/custom-routers/) for routing behavior.
+The optional `routing` field takes a different shape for each type:
+
+* **Complexity** - For `type: complexity`, `routing.easy`, `routing.medium`, and `routing.hard` optionally map complexity levels to concrete models.
+* **Prompt** - For `type: prompt`, `routing` is an ordered list of objects, each requiring `description` and `model`.
+
+Targets must be concrete supported models, not Auto models or other routers. See [custom model routers](/agents/inference/custom-routers/) for routing behavior.
Factory members who can access the router can also select it from model catalogs in the factory dashboard, including agent settings and benchmark configurations.
@@ -624,29 +628,29 @@ tasks:
- broken-doc-link
```
-### `name`
-
-**Required.**
-The suite display name, which must be unique in the factory.
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `name` | Yes | None | Suite display name; must be unique in the factory. |
+| `description` | No | Not specified | What the suite measures. |
+| `agent` | Yes | None | The factory agent used for every task in the suite. |
-### `description`
+### `configurations`
**Optional.**
-A short summary of what the suite measures.
+One to six reusable configurations. Warp uses these presets when a benchmark run doesn't supply configurations. Each configuration requires a unique `name`.
-### `agent`
+The optional `agents` list pins factory agents to models and harnesses for the configuration's trials:
-**Required.**
-The factory agent used for every task in the suite.
-
-### `configurations`
+| Field in `configurations[].agents[]` | Required | Description |
+| --- | --- | --- |
+| `agent` | Yes | The factory agent's name. List each agent once per configuration. |
+| `model` or `harness` | Exactly one | Model selection. A `harness` requires `type` and `model`; `type` accepts `oz`, `claude`, `claude-code`, or `codex`. Optional `auth` follows the [harness authentication rules](#agentdefaultsharness). |
-**Optional.**
-One to six reusable configurations. Warp uses these presets when a benchmark run doesn't supply configurations. Each configuration requires a unique `name`.
+Omitted agents use their settings at launch time.
-Optional `role` is deprecated metadata. Warp ignores it and omits it when rewriting the suite.
+#### Deprecated metadata
-The optional `agents` list pins factory agents to models and harnesses for the configuration's trials. Each `configurations[].agents[]` item names an `agent` and includes exactly one of `model` or `harness`. A `harness` requires `type` and `model`; `type` accepts `oz`, `claude`, `claude-code`, and `codex`. Optional `auth` follows the [harness authentication rules](#agentdefaultsharness). List an agent once per configuration. Omitted agents use their settings at launch time.
+Optional configuration `role` is accepted for compatibility. Warp ignores it and omits it when rewriting the suite.
### `tasks`
@@ -666,35 +670,14 @@ startingRepoRefs:
- github.com:acme/payments-docs@0123456789abcdef0123456789abcdef01234567
```
-### `title`
-
-**Required.**
-The task display name. It doesn't need to match the task slug.
-
-### `prompt`
-
-**Required.**
-The instructions sent to the agent.
-
-### `successCriteria`
-
-**Required.**
-The Correctness Scorer's evaluation criteria.
-
-### `sourceRunId`
-
-**Optional.**
-The ID of the prior run that produced the task. This records provenance and can refer to a deleted run.
-
-### `tags`
-
-**Optional.**
-An ordered list of task labels.
-
-### `linearSeed`
-
-**Optional.**
-JSON-compatible starting state for the trial's isolated Linear workspace.
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `title` | Yes | None | Task display name; doesn't need to match the task slug. |
+| `prompt` | Yes | None | Instructions sent to the agent. |
+| `successCriteria` | Yes | None | Correctness Scorer's evaluation criteria. |
+| `sourceRunId` | No | Not specified | ID of the prior run that produced the task; can refer to a deleted run. |
+| `tags` | No | Not specified | Ordered list of task labels. |
+| `linearSeed` | No | Not specified | JSON-compatible starting state for the trial's isolated Linear workspace. |
### `startingRepoRefs`
@@ -704,7 +687,7 @@ The GitHub or GitLab repositories and commits used as the task's starting state.
## `scorers//scorer.md`
**Optional resource.**
-Scorer files define LLM judges that classify sampled runs against a rubric. The directory is a stable slug; `name` identifies the scorer. Frontmatter defines the classification contract, and the Markdown body holds the rubric. See [configuring scorers](/factories/measure-and-improve/scorers/) for how scores are used.
+Scorer files classify sampled runs against a rubric. The directory is a stable slug; `name` identifies the scorer. Frontmatter defines the labels and scoring settings, and the Markdown body holds the rubric. See [Configuring Scorers](/factories/measure-and-improve/scorers/) for how scores are used.
```markdown title="scorers/tests-run/scorer.md"
---
@@ -726,15 +709,15 @@ Evaluate whether the agent ran the relevant tests before finishing. Return
exactly one declared label.
```
-### `name`
-
-**Required.**
-The scorer's identity. Changing it doesn't move the directory.
-
-### `description`
-
-**Optional.**
-A short summary of what the scorer checks.
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `name` | Yes | None | Scorer name. Changing it doesn't move the directory. |
+| `description` | No | Not specified | What the scorer checks. |
+| `output` | No | Not specified | Output form; `classification` is the supported value. |
+| `passingScore` | Yes | None | Passing threshold, from 0 through 1. |
+| `samplingRate` | No | `25` | Percentage of eligible runs to score, from 0 through 100. Rounds to two decimal places; `0` disables automatic scoring. |
+| `model` | Yes | None | Model that judges runs. |
+| `selfImprovement` | No | `false` | When `true`, failing scores can feed self-improvement, which proposes definition changes in pull requests. |
### `agents`
@@ -752,40 +735,15 @@ agents:
**Optional.**
`runner`, `secrets`, and `mcpServers` override the factory's `scorerDefaults` for this scorer. Scorer-level `mcpServers` use the [factory-level transport syntax](#mcpservers). Set shared values under `scorerDefaults` in `factory.yaml`.
-### `output`
-
-**Optional.**
-The scorer output form. `classification` is the supported value.
-
### `labels`
**Required.**
One to 20 classifications. Each label requires a unique `value` and a `score` from 0 through 1; `description` is optional. At least one label must meet `passingScore`, and at least one must fall below it.
-### `passingScore`
-
-**Required.**
-The passing threshold, from 0 through 1.
-
-### `samplingRate`
-
-**Optional.**
-The percentage of eligible runs to score, from 0 through 100. It defaults to 25, rounds to two decimal places, and disables automatic scoring at 0.
-
-### `model`
-
-**Required.**
-The model that judges runs.
-
-### `selfImprovement`
-
-**Optional.**
-When `true`, failing scores can feed the self-improvement flow, which proposes definition changes in pull requests. Defaults to `false`.
-
## `webhooks/.yaml`
**Optional resource.**
-Webhook files define [authenticated URLs](/factories/webhooks/) for JSON POST requests. Automation `webhook` triggers subscribe to them; the file name names the webhook. `secretName` references an existing [managed secret](/platform/secrets/), not secret material.
+Webhook files define [authenticated URLs](/factories/webhooks/) for JSON POST requests. Automation `webhook` triggers subscribe to them; the file name identifies the webhook. `secretName` references an existing [managed secret](/platform/secrets/), not secret material.
```yaml title="webhooks/internal-ci.yaml"
authMode: token
@@ -794,6 +752,12 @@ deliveryIdHeader: X-CI-Run-Id
enabled: true
```
+| Field | Required | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | No | `true` | Whether the webhook accepts deliveries. Set to `false` to stop deliveries without deleting it, or to create it before the provider issues a signing secret. See [Setting up a Vercel webhook](/factories/webhooks/vercel/). |
+
+You can't change `authMode` or `signatureScheme` on an existing webhook. Delete and recreate it, or create the replacement under a different name.
+
### `authMode`
**Optional.**
@@ -814,23 +778,16 @@ The managed secret containing the bearer token, URL token, or provider signing s
**Optional.**
The sender's delivery ID header, used to deduplicate retries. It accepts up to 64 characters and must be a valid HTTP header name. Credential-bearing headers such as `Authorization`, `Cookie`, and provider signature headers are rejected.
-### `enabled`
-
-**Optional.**
-Whether the webhook accepts deliveries. Defaults to `true`. Use `false` to stop deliveries immediately without deleting the webhook, or to create it before the provider issues a signing secret. See [setting up a Vercel webhook](/factories/webhooks/vercel/).
-
On a Warp-managed factory, creating a webhook in the dashboard writes this file for you and stores the secret under the name you enter in the "Secret name" field.
-You can't change `authMode` or `signatureScheme` on an existing webhook. Delete and recreate the webhook, or create the replacement under a different name.
-
## Skills
**Optional resource.**
-A skill is a directory containing `SKILL.md`, not a YAML key. Put shared skills under `skills/` and agent-specific skills under `agents//skills/`. See [factory skills](/factories/factory-skills/) for placement and [Skills](/agents/capabilities/skills/) for the file format.
+A skill is a directory containing `SKILL.md`, not a YAML key. Put shared skills under `skills/` and agent-specific skills under `agents//skills/`. See [Factory skills](/factories/factory-skills/) for placement and [Skills for agents](/agents/capabilities/skills/) for the file format.
## Example factory definition
-This definition includes one repository, a foreman, an automation triggered by a GitHub label, and a Linux runner. Replace `PAYMENTS_ENVIRONMENT_ID` and `SENTRY_MCP_SERVER_ID` with existing resource IDs.
+This definition includes one repository, a foreman, an automation triggered by a GitHub label, and a Linux runner. Replace `PAYMENTS_ENVIRONMENT_ID` and `SENTRY_MCP_SERVER_ID` with existing environment and MCP server IDs. Create a managed secret named `SENTRY_AUTH_TOKEN`, or replace that name with an existing secret.
For more complete definitions, see [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples).
@@ -897,7 +854,7 @@ platform:
### Routing to a self-hosted worker
-To use a [managed self-hosted worker](/factories/infrastructure-and-security/#choose-an-execution-host), set `agentDefaults.workerHost` to the worker ID. Agents and automations can override it.
+Set [`agentDefaults.workerHost`](#agentdefaultsworkerhost) to a connected worker's ID:
```yaml title="factory.yaml"
agentDefaults:
@@ -906,11 +863,11 @@ agentDefaults:
workerHost: SELF_HOSTED_WORKER_ID
```
-Pair `workerHost` with a runner whose `platform` matches the worker. Follow the [self-hosting quickstart](/factories/self-hosting/quickstart/) to connect a worker, or copy [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker).
+Replace `SELF_HOSTED_WORKER_ID` with the worker's ID and pair it with a runner whose `platform` matches the worker. See the [Self-hosting quickstart](/factories/self-hosting/quickstart/) or copy [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker).
## Related pages
-* [Factory MCP for coding agents](/factories/factory-mcp/) - Read the schema and validate a tree from any coding agent, and send work to a factory
-* [GitHub integration](/factories/integrations/github/#factory-definition-pull-request-checks) - How the **warp/factory-config** check appears on pull requests, and what to check when it doesn't
-* [Factory dashboard](/factories/factory-dashboard/#edit-definitions-in-the-factory-definition-tab) - Where a Warp-managed definition is edited and validated on save
-* [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) - Complete definitions to copy, plus the validator script and a CI workflow that runs it
+* [Factory MCP for coding agents](/factories/factory-mcp/) - Read schemas and validate definitions through an agent
+* [Factory-definition pull request checks](/factories/integrations/github/#factory-definition-pull-request-checks) - Review validation results and protect merges
+* [Factory dashboard](/factories/factory-dashboard/#edit-definitions-in-the-factory-definition-tab) - Edit a Warp-managed definition
+* [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) - Copy complete definitions and validation workflows
diff --git a/src/content/docs/factories/factory-dashboard.mdx b/src/content/docs/factories/factory-dashboard.mdx
index 090c30a41..2a556282d 100644
--- a/src/content/docs/factories/factory-dashboard.mdx
+++ b/src/content/docs/factories/factory-dashboard.mdx
@@ -16,7 +16,9 @@ The factory dashboard is the web app for operating a single factory. Open the /SKILL.md`** - Available to every agent in the factory. Use this for procedures that apply regardless of role, such as your repository's coding conventions or a shared escalation policy.
-* **`agents//skills//SKILL.md`** - Available only to that agent. Use this for procedures specific to one role, such as how the review agent should apply your security checklist.
-
-Both forms use the same `SKILL.md` format as skills anywhere else in Warp. See [Skills](/agents/capabilities/skills/) for the file format, front matter, and argument syntax.
-
-## Factory role and integration skills
+
+
-Every default agent starts with a baseline of role and integration skills so the factory works immediately after setup, before you write anything custom:
-
-* **GitHub** - Every default agent gets a GitHub skill, covering how to read issues, open pull requests, and follow your repository's conventions.
-* **Slack** - The foreman also gets a Slack skill, since it's the agent that replies in threads and DMs.
-* **Issue tracker** - The tracker you choose during setup, Linear or Jira, adds that tracker's skill and instructions to the agents that use it. If you don't connect a tracker, agents keep only the GitHub and Slack skills.
-
-These baseline skills aren't files in your definition; they come from the agent roles and integrations you choose. Anything you add under `skills/` or `agents//skills/` extends this baseline rather than replacing it.
+A factory run can use skills from three sources:
-## Warp-provided platform-bundled skills
+* **Role and integration skills** - Default agents have GitHub skills for repository work. The foreman also has a Slack skill. Choosing Linear or Jira during setup gives relevant agents the tracker's skill and instructions. These skills come from roles and integrations, not files in your definition.
+* **Warp-provided skills** - Bundled capabilities include `oz-platform` for cloud agents, `factory-files` for factory definitions, and `factory-mcp` for sending work to factories.
+* **Custom skills** - Team-owned `SKILL.md` files live in the factory definition and are shared across the factory or scoped to one agent. They extend the built-in skills rather than replacing them.
-Platform-bundled skills are separate from factory role and integration skills. They provide Warp capabilities such as operating cloud agents with `oz-platform`, editing factory definitions with `factory-files`, and sending work through Factory MCP with `factory-mcp`.
+
-Warp provides these stable bundled-skill IDs:
+For bundled skill IDs and how to attribute team-owned skill usage, see [Skill actions in conversation data](/factories/api-and-sdk/#skill-actions-in-conversation-data).
-| Bundled skill ID | Purpose |
-| --- | --- |
-| `add-mcp-server` | Add an MCP server to Warp configuration. |
-| `change-keybinding` | Change or remove Warp keyboard shortcuts. |
-| `claude-api` | Build and maintain applications that use the Anthropic SDK. |
-| `create-skill` | Create, improve, and evaluate skills. |
-| `create-tab-config` | Create a Warp tab configuration. |
-| `factory-files` | Create and validate file-based Warp factory definitions. |
-| `factory-mcp` | Send work to a factory and collaborate through Factory MCP. |
-| `modify-settings` | View or change Warp settings using the bundled settings schema. |
-| `oz-platform` | Run, configure, and inspect cloud agents through the API and CLI. |
-| `pr-comments` | Fetch GitHub pull request review comments for the current branch. |
-| `tab-configs` | Look up the tab configuration schema and validation rules. |
-| `tui-migrate-setup` | Migrate supported settings into the Warp Agent CLI. |
-| `update-tab-config` | Update an existing Warp tab configuration. |
-| `warpctrl` | Control and inspect a running Warp app with Warp Control. |
+## When to add a custom skill
-See [skill actions in conversation data](/factories/api-and-sdk/#skill-actions-in-conversation-data) for the API reference.
+Add a custom skill for procedures the built-in skills don't cover. For example:
-## Attribute team-owned skill usage
+* Run required tests or lint checks.
+* Follow incident-response or triage runbooks.
+* Apply a security or compliance review checklist.
+* Teach a custom agent its job. Custom agents have no built-in skills.
-The [Conversation API](/api) returns skill loads as `read_skill` actions. Use the action's `input` to classify the skill:
+Skills provide instructions, not access to tools or repositories. If a procedure requires credentials or an MCP connection, configure the agent's [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/) through its [settings](/factories/factory-agents/configuration/#edit-agent-settings-and-instructions). For how that access is limited, see [credential boundaries](/factories/infrastructure-and-security/#credential-boundaries).
-* **`input.bundled_skill_id` is present** - The action loaded a Warp-provided bundled reference. Exclude it when measuring usage of skills your team owns.
-* **Only `input.skill_path` is present** - A path alone doesn't identify the skill's owner. Count it as team-owned only when the path is under a skill root your team manages, such as `skills/` or `agents//skills/` in the factory definition.
+
-## When to add a custom skill
+## Add or edit a skill
-Add a custom skill when a default agent needs to do something the built-in baseline doesn't cover, such as:
+Custom skills live in the factory's [definition](/factories/factory-as-code/#directory-structure), not its agent settings. You need permission to edit that definition.
-* Enforcing a specific test, lint, or validation command before a change is considered complete.
-* Following a runbook for a category of incident or request your triage agent sees repeatedly.
-* Applying a security or compliance checklist during review that goes beyond general code quality.
-* Teaching a custom agent its job. Custom agents have no built-in skills.
+To add or update a custom skill:
-A skill changes what an agent knows how to do, not what it can reach. To scope access, configure the agent's [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/) — see [factory agents](/factories/factory-agents/#configure-agent-behavior) and [infrastructure and security](/factories/infrastructure-and-security/#credential-boundaries).
+1. Open the definition where it's managed:
+ * **Warp-managed** - In the web app sidebar, expand your factory and click **Factory definition**.
+ * **GitHub-backed** - Open the connected definition repository. See [Where the definition lives](/factories/factory-as-code/#where-the-definition-lives).
+2. Create or open the skill file for the scope you need:
+ * **Every agent** - `skills//SKILL.md`, for shared procedures such as repository conventions.
+ * **One agent** - `agents//skills//SKILL.md`, for a role-specific procedure such as a security review.
-## Add or edit a skill
+ Replace `` with the skill's directory name and `` with the agent's directory name.
-Where you edit a skill depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives):
+ For example, this layout shares repository conventions with every agent and gives only the foreman an incident-triage skill:
-* **Warp-managed** - Add or edit `SKILL.md` files directly in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step.
-* **GitHub** - Add or edit the files in the connected definition repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks) that validate the rest of the definition apply to skill files.
+ ```text
+ skills/
+ repository-conventions/
+ SKILL.md
+ agents/
+ foreman/
+ skills/
+ incident-triage/
+ SKILL.md
+ ```
+3. Write or update the skill's instructions, name, and description. See [Skill file format](/agents/capabilities/skills/#skill-file-format) for frontmatter and [Skill arguments](/agents/capabilities/skills/#skill-arguments) for parameters.
+4. Apply the change:
+ * **Warp-managed** - Save the definition. Warp validates and commits it.
+ * **GitHub-backed** - Open a pull request. The factory's [pull request checks](/factories/factory-as-code/#pull-request-checks) validate the change, and merging to the production branch applies it.
-For worked examples, including a factory-wide skill and a per-agent skill together, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository.
+For an example of a shared skill and an agent-specific skill in one definition, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr) in [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples).
## Skills and self-improvement
-A factory can propose changes to a skill. When [Self-improvement](/factories/measure-and-improve/self-improvement/) is on for a Scorer and it flags a recurring failure, it can edit the responsible skill in a follow-up run, the same way it can edit application code. The change still arrives as a pull request for your team to review, whether that's through the factory dashboard or your Git host.
+When a Scorer with [Self-improvement](/factories/measure-and-improve/self-improvement/) enabled flags a recurring failure, the factory can update the responsible skill in a follow-up run. Changes arrive as pull requests for your team to review in the web app or your Git host.
## Related pages
-* [Factory agents](/factories/factory-agents/) - The agents that use a factory's skills, and how to configure each one.
-* [Definitions as code](/factories/factory-as-code/) - The full schema for `factory.yaml`, agents, automations, and runners alongside skills.
-* [Skills](/agents/capabilities/skills/) - The general skill file format, shared across Warp, cloud agents, and factories.
-* [Measure and improve a factory](/factories/measure-and-improve/) - How Self-improvement turns repeated failures into skill and code changes.
+* [About factory agents](/factories/factory-agents/) - Understand the agents that use factory skills
+* [Creating custom agents](/factories/factory-agents/creating-custom-agents/) - Add specialized roles and skills
+* [Factory definition syntax](/factories/factory-as-code/) - Look up definition files and fields
+* [Skills for agents](/agents/capabilities/skills/) - Write skills with arguments and supporting files
+* [Measure and improve a factory](/factories/measure-and-improve/) - Evaluate runs and propose improvements
diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx
index 372438085..3f10bf70f 100644
--- a/src/content/docs/factories/how-factories-work.mdx
+++ b/src/content/docs/factories/how-factories-work.mdx
@@ -2,31 +2,21 @@
title: How Warp Factories work
description: >-
A factory's foreman routes each work item through triage, planning,
- building, and reviewing, with humans making the key decisions.
+ implementation, and review, with humans making the key decisions.
sidebar:
label: "How factories work"
---
-A factory is a team of cloud agents attached to a set of repositories. You talk to one of them, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, each of which owns one part of the software development lifecycle, and people make the key decisions along the way.
+A factory is a team of cloud agents connected to your repositories. The **foreman agent** coordinates a factory's work and communicates with you through the tool where the request started, such as Slack or Linear. It dispatches the factory's other agents, each of which handles a stage of the software development lifecycle, and people make the key decisions along the way.
A **work item** is a single request the factory acts on, such as an issue, support request, pull request, or Factory MCP task. It keeps its identity from intake to handoff, however many agents contribute to it along the way.
-The diagram, from intake to improvement:
-
-* **Work sources** - [Slack](/factories/integrations/slack/), [Microsoft Teams](/factories/integrations/teams/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), [Jira](/factories/integrations/jira/), [custom webhooks](/factories/webhooks/), [factory endpoints](/factories/factory-api/), the [Factory MCP](/factories/factory-mcp/), direct runs, and schedules.
-* **Automations** - [Automations](/factories/automations/) filter provider events and schedules and decide which agent handles them. 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/).
-* **Human handoff** - The factory opens a pull request with evidence and updates the original work item. You review and merge.
-* **Factory definition** - Version-controlled agents, automations, runners, scorers, skills, and webhooks, either Warp-managed or in a GitHub repository your team owns. See [definitions as code](/factories/factory-as-code/).
-* **Execution** - Every stage is a cloud agent run on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, using the factory's repositories and each stage's configured model and [harness](/platform/harnesses/).
-* **Factory dashboard** - Metrics, work items by stage, 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 repeated failures into pull requests for your review.
## How a work item moves through the factory
-The foreman coordinates every work item. It routes work between the factory's agents, passes each one the context it needs, and continues existing agent conversations instead of starting new ones. See [factory agents](/factories/factory-agents/) for what each agent does.
+The foreman passes each agent the context it needs and continues existing conversations when work returns for revisions.
Not every work item needs every stage. The foreman picks the shortest path that still meets your quality policy: it skips stages when the work is already well defined, starts partway through when enough context exists, and sends work back to an earlier agent when revisions are needed.
@@ -47,24 +37,26 @@ flowchart LR
Reviewing --> Revision{Revision needed?}
Revision -->|Yes| Building
Revision -->|No| Handoff["Human handoff (default policy)"]
- Handoff --> Complete[Complete]
+ Handoff -->|"Merge notification or human confirmation"| Complete[Complete]
```
-* **Intake** - A work item enters from a [connected integration](/factories/connect-your-factory/), an automation, a direct run, or the [Factory MCP](/factories/factory-mcp/). It keeps its source context as it moves through later stages.
+* **Intake** - A work item enters from a [connected integration](/factories/connect-your-factory/), an automation, a direct run, or the [Factory MCP](/factories/factory-mcp/). [Automations](/factories/automations/) filter events and schedules and select an agent to handle the work. Direct requests go straight to the foreman. The work item keeps its source context as it moves through later stages.
* **Triage** - The triage agent researches the request, reproduces the problem when needed, and defines the scope and complexity of the change. The foreman skips this stage when the request already explains the problem and what needs to change.
* **Planning** - The spec agent defines product behavior, technical constraints, and validation criteria. The foreman skips this stage for small, well-understood changes.
* **Building** - The implement agent makes the code change on a branch and opens a pull request with test and visual evidence.
* **Reviewing** - The review agent checks the change against the requirements, tests, and security expectations, then sends findings back for another pass. Its verdict is advisory.
-* **Human handoff** - The factory presents the result, its evidence, and any findings. A person decides what happens next.
-* **Complete or Cancelled** - The work item ends when the factory finishes its work, or stops early if someone cancels it.
+* **Human handoff** - The factory presents the result, its evidence, and any findings, and updates the original work item. A person decides what happens next.
+* **Complete or Cancelled** - By default, the foreman completes the work item after a merge notification or confirmation that the pull request landed. Handoff alone doesn't complete it. A cancellation stops the work early.
+
+Stages and agents are named separately, so the spec agent works the planning stage, the implement agent works the building stage, and the review agent works the reviewing stage. See [About factory agents](/factories/factory-agents/) for each agent's responsibilities.
-Stages and agents are named separately, so the spec agent works the Planning stage, the implement agent works the Building stage, and the review agent works the Reviewing stage. Each agent's run within a work item is an ordinary [cloud agent run](/platform/) you can watch and steer from the factory's [Runs page](/factories/factory-dashboard/#inspect-runs), and any stage that needs your input surfaces in your [inbox](/factories/factory-inbox/).
+Each agent's run is a [cloud agent run](/platform/) on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, using the factory's repositories and the agent's configured model and [harness](/platform/harnesses/). Watch and steer runs from the factory's [Runs page](/factories/factory-dashboard/#inspect-runs). Work that needs your input appears in your [inbox](/factories/factory-inbox/).
## Where your team stays in charge
A factory pauses when a person needs to decide. By default, that's three places:
-* **Approving the spec** - When work goes through the Planning stage, the Building stage waits until a person signs off on the plan.
+* **Approving the spec** - When work needs a spec, implementation waits until a person signs off on the plan.
* **Answering questions** - When requirements are unclear or a review finding is ambiguous, the foreman asks instead of guessing.
* **Merging** - The factory opens the pull request and hands it off. Whether and when it merges is your team's call.
@@ -74,12 +66,14 @@ The first two are workflow policy, written into the foreman's instructions; edit
[Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, and [Self-improvement](/factories/measure-and-improve/self-improvement/) groups the failures they flag into follow-up runs that propose fixes to the application code or to the factory's own definition. Every proposal arrives as a pull request for your review; nothing is adopted on its own.
-The factory's definition is open to the same loop. Anyone on the team, or an agent, can propose changes to its instructions, skills, models, or other [definition files](/factories/factory-as-code/), and definitions stored in GitHub go through pull request review and [configuration checks](/factories/factory-as-code/#pull-request-checks) before a change reaches the production branch.
+Use [benchmarks](/factories/benchmarks/) to compare configurations on the same tasks.
+
+A factory's agents, automations, runners, scorers, skills, and webhooks are configured in [definition files](/factories/factory-as-code/), either managed by Warp or stored in a GitHub repository your team owns. Anyone on the team, or an agent, can propose changes to the definition, including its instructions, skills, and models. Definitions stored in GitHub go through pull request review and [configuration checks](/factories/factory-as-code/#pull-request-checks) before a change reaches the production branch.
## Related pages
* [Sizing a factory](/factories/#sizing-a-factory) - Which repositories belong in one factory.
-* [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure it.
+* [About factory agents](/factories/factory-agents/) - What each default agent does and how to configure it.
* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory.
* [Measure and improve](/factories/measure-and-improve/) - Scorers, benchmarks, and Self-improvement.
* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent/) - Apply the same loop to a standalone agent.
diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx
index 712925069..cd966c16b 100644
--- a/src/content/docs/factories/index.mdx
+++ b/src/content/docs/factories/index.mdx
@@ -10,7 +10,7 @@ import { VARS } from '@data/vars';
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
import VideoEmbed from '@components/VideoEmbed.astro';
-A factory is a team of cloud agents attached to a set of repositories. It takes work from Slack, GitHub, Linear, or Jira through triage, spec, implementation, and review, and returns the result, usually a pull request, where the work started.
+A factory is a team of cloud agents connected to your repositories. It routes work from Slack, GitHub, Linear, or Jira through triage, planning, implementation, and review. The output, usually a pull request, is returned to the thread or issue where the work started.
## What a factory does
-A factory can work through a backlog of issues, fix defects reported in a support channel, or review incoming pull requests across several repositories.
-
+A factory can work through a backlog of tasks, fix defects reported in a support channel, or review incoming pull requests across several repositories.
+
-
-
-
-The software factory loop. The default agents cover triage through review.
+An introduction to Warp Factories.
## The parts of a factory
### Work items
-A work item is one request the factory acts on: an issue, a support thread, a pull request, or a scheduled job. It keeps its source context from intake to handoff, however many agents contribute along the way.
+A work item is one request the factory acts on. This can be an issue, a support thread, a pull request, or a scheduled job. It keeps its source context from intake to handoff, however many agents contribute along the way.
### Foreman and factory agents
-The foreman is the agent that coordinates a factory's work and communicates with you. See [factory agents](/factories/factory-agents/) for agent roles, models, harnesses, and configuration.
+The foreman is the agent that coordinates a factory's work and communicates with you. See [About factory agents](/factories/factory-agents/) for their roles, and [Configuring factory agents](/factories/factory-agents/configuration/) to change their models, harnesses, and instructions.
Setup gives the foreman the same handle as the factory, so `payments` is the factory and `@payments` reaches its foreman from Slack or Linear. See [Foreman name](/factories/factory-agents/#foreman-name).
### Stages and checkpoints
-Work moves through Triage, Planning, Building, and Reviewing. The foreman can skip unnecessary stages or send work back for revisions. Spec approval is part of the foreman's editable instructions, not a repository permission. The factory never merges on your behalf. Repository permissions and branch protection control approval and merge access. See [how Warp Factories work](/factories/how-factories-work/).
+Factory agents handle different stages of the software development lifecycle. The default agents cover triage, planning, implementation, and review.
+
+
+
+The software factory loop.
+
+
+The foreman can skip unnecessary stages or send work back for revisions. Spec approval is part of the foreman's editable instructions, not a repository permission. The factory never merges on your behalf. Repository permissions and branch protection control approval and merge access. See [How Warp Factories work](/factories/how-factories-work/).
### Factory definition
@@ -84,13 +88,14 @@ Group the repositories that ship together into one factory, and keep separate pr
* One factory for your marketing site
* One factory for your data pipelines
-Don't split the same repositories across factories by team or task, such as frontend and platform. Add [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/) to specialize instead.
+Don't split the same repositories across factories by team or task, such as frontend and platform. Add [custom agents](/factories/factory-agents/creating-custom-agents/) and [skills](/factories/factory-skills/) to specialize instead.
## Related pages
* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item.
* [How Warp Factories work](/factories/how-factories-work/) - The work-item lifecycle, stage by stage.
-* [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure its model and harness.
+* [About factory agents](/factories/factory-agents/) - Understand default agent roles
+* [Configuring factory agents](/factories/factory-agents/configuration/) - Choose models, harnesses, and instructions
* [Definitions as code](/factories/factory-as-code/) - The definition file format, with working examples in [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples).
* [Transitioning from Oz](/platform/transitioning-from-oz/) - Assess an existing web app, CLI, SDK, or API workflow.
* Get started with the Warp team - Get help choosing and setting up a workflow.
diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx
index 9595cc182..3fee0ec83 100644
--- a/src/content/docs/factories/infrastructure-and-security.mdx
+++ b/src/content/docs/factories/infrastructure-and-security.mdx
@@ -1,17 +1,17 @@
---
-title: Warp Factories infrastructure and security
+title: About factory infrastructure and security
description: >-
Warp Factories gives you control over inference and execution hosting while
Warp stores run records, transcripts, and outputs.
sidebar:
- label: "Infrastructure & security"
+ label: "About infrastructure and security"
---
Warp Factories separates execution, inference, and credential boundaries. You choose where code runs, which providers serve inference, and which credentials each agent receives. Warp coordinates the work and stores transcripts and artifacts.
## Control plane and execution plane
-Each factory uses two planes:
+Warp manages coordination, while a Warp-hosted sandbox or a worker on your infrastructure executes the work. These responsibilities form the control plane and execution plane:
* **Control plane** - Warp coordinates runs, identity and configuration, observability, integrations, storage, and inference routing.
* **Execution plane** - A Warp-hosted sandbox or a managed self-hosted worker checks out code, runs setup, invokes tools, builds the project, and executes commands.
@@ -27,42 +27,31 @@ flowchart LR
C --> D["Warp-managed storage"]
```
-With managed self-hosting, repository checkouts, commands, and sandbox files stay on machines you control. Prompts, results, transcripts, attachments, artifacts, and telemetry still flow through Warp and configured providers. See [deployment patterns](/factories/deployment-patterns/), [execution security](/platform/execution-security/), and the [data security and boundaries](/platform/architecture/#data-security-and-boundaries) reference for details.
+With managed self-hosting, repository checkouts, commands, and sandbox files stay on machines you control. Prompts, results, transcripts, attachments, artifacts, and telemetry still flow through Warp and can contain code context. The Warp Agent sends model requests through Warp to the configured inference provider. Claude Code and Codex call their providers directly from the execution environment. See [deployment patterns](/factories/deployment-patterns/), [execution security](/platform/execution-security/), and [data security and boundaries](/platform/architecture/#data-security-and-boundaries) for details.
## Runners
-A runner selects the operating system, architecture, sandbox image, and vCPU and memory shape. The factory's [definition](/factories/factory-as-code/) supplies repositories, setup commands, and secrets. Define runners in `runners/*.yaml`; `agentDefaults.runner` sets the default, and agents and automations can override it. The execution host determines how each setting is used:
+A runner selects the operating system, architecture, sandbox image, and vCPU and memory shape. The factory's [definition](/factories/factory-as-code/) supplies repositories, setup commands, and secrets. The factory definition sets the default runner with `agentDefaults.runner`. Individual agents and automations can override that default.
-| Setting | Warp-hosted | Direct | Kubernetes | Docker |
-| --- | --- | --- | --- | --- |
-| `platform.os`, `platform.arch`, `platform.mac.version` | Selects the sandbox OS, architecture, and macOS VM version | Does not configure the host; the worker host determines the platform | Use Linux; the cluster and `pod_template` schedule nodes | Use Linux; the Docker daemon determines the architecture |
-| `platform.linux.dockerImage` | Linux sandbox image | Ignored | Task and setup container image | Task container image |
-| `platform.linux.registryCredentialSecretName` | Warp-managed private-registry credential | Ignored | Ignored; use `imagePullSecrets` | Ignored; configure registry credentials on the worker, such as in its Docker config |
-| `instanceShape` | Sandbox size, subject to plan limits; omitted uses the workspace default | Ignored; the task uses host resources | Task-container requests and limits; overrides matching `pod_template` resources; omitted keeps template or cluster defaults | Task-container limits; omitted adds no limits |
-
-Self-hosted runner settings don't provision capacity. Worker configuration controls resources, registry authentication, volumes, placement, and backend policy. See [runner compute options](/factories/runners/) for available configurations.
+The execution host determines how runner settings apply. Self-hosted runner settings don't provision capacity. See [Runner settings by execution host](/factories/runners/#runner-settings-by-execution-host) for a settings comparison.
## 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](/factories/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 |
| --- | --- | --- |
| **Compute** | Warp provisions the sandbox | Your team provisions the worker |
-| **Checkout and commands** | Run on Warp-managed compute | Run on your infrastructure |
+| **Checkout and commands** | On Warp-managed compute | On your infrastructure |
| **Network** | Warp manages sandbox connectivity | The worker connects outbound to Warp; no inbound firewall port |
| **Private services** | Must be reachable from the hosted sandbox | Reachable through the worker's network access |
| **Operations** | Warp manages capacity and lifecycle | Your team manages capacity, isolation, updates, and availability |
-To route factory work to a managed self-hosted worker (an Enterprise feature):
-
-1. **Deploy a worker** - Review the [self-hosting requirements](/factories/self-hosting/), then connect a worker that authenticates to Warp with a self-hosted worker 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.
+Managed self-hosting requires an Enterprise plan. Task platforms depend on the backend: Docker uses a `linux/amd64` or `linux/arm64` daemon, Kubernetes uses Linux task nodes, and Direct uses the worker host's OS and architecture. A native worker on macOS or Windows can connect to a Linux Docker daemon; the task still runs on Linux. See [Runner settings by execution host](/factories/runners/#runner-settings-by-execution-host).
-For a working definition with `workerHost` set and a platform-matched runner, see [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker).
+See the [managed prerequisites](/factories/self-hosting/#managed-prerequisites) for credentials and network access, and the [Self-hosting quickstart](/factories/self-hosting/quickstart/) to connect a worker. The factory definition selects the connected worker with [`workerHost`](/factories/factory-as-code/#agentdefaultsworkerhost). For a complete configuration with a compatible runner, see [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker).
Unmanaged self-hosted agents and other CLI agents can't serve as a factory's execution host, but they can exchange work with a factory through [Factory MCP](/factories/factory-mcp/).
@@ -70,11 +59,13 @@ Unmanaged self-hosted agents and other CLI agents can't serve as a factory's exe
The worker backend sets isolation and scheduling on your infrastructure:
-| Structure | How factory runs execute | What your team operates | Use it when |
-| --- | --- | --- | --- |
-| **[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 |
+| Backend | How factory runs execute |
+| --- | --- |
+| [Docker](/factories/self-hosting/managed-docker/) (default) | In a separate Docker container on the worker host |
+| [Kubernetes](/factories/self-hosting/managed-kubernetes/) | As a Kubernetes Job in the worker's namespace |
+| [Direct](/factories/self-hosting/managed-direct/) | In a separate workspace on the worker host, sharing its OS and kernel |
+
+For backend selection guidance, including Command and one-shot Direct options, see [Choosing a managed backend](/factories/self-hosting/#choosing-a-managed-backend).
## Choose inference independently
@@ -83,16 +74,16 @@ Execution hosting doesn't select inference. Configure that boundary separately.
### Inference options for factory runs
-Factory agents execute as cloud agents, so only inference options that support cloud agent runs apply:
+Factory agents execute as cloud agents. For runs using the Warp Agent, support varies by inference option:
| Option | Support for factory runs | Team controls | Key boundary |
| --- | --- | --- | --- |
| **Warp-managed inference** | Supported | The model selected for each agent | Warp provides the provider account and charges your available usage |
-| **[Team-managed keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/)** | Supported on Business and Enterprise | Shared OpenAI, Anthropic, or Google keys, or an OpenAI-compatible endpoint | Warp stores the encrypted credential and uses it only at the inference boundary; it never enters the worker or run environment |
+| **[Team-managed keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/)** | Supported on Business and Enterprise | Shared OpenAI, Anthropic, or Google keys, or an OpenAI-compatible endpoint | Warp encrypts stored credentials and uses them only at the inference boundary. They never enter the worker or run environment. |
| **[BYOLLM: AWS Bedrock](/enterprise/enterprise-features/byollm-aws-bedrock/)** | Supported on Enterprise | The AWS account, IAM role, available Claude models, and provider billing | Warp assumes your IAM role through OIDC; inference runs in your AWS account |
| **[BYOLLM: Gemini Enterprise](/enterprise/enterprise-features/byollm-gemini-enterprise/)** | Not supported for factory runs | Interactive inference in your Google Cloud project | Gemini Enterprise BYOLLM currently supports interactive agent requests only |
-Self-serve BYOK and custom inference endpoints are stored on an individual member's device and don't apply to factory runs. With team-managed keys and endpoints, select a specific provider model or endpoint; Auto continues to use Warp-managed inference. When you supply the provider, its retention follows your account and contract, and Warp can't enforce ZDR for that provider.
+Personal BYOK and personal custom inference endpoints are stored on a member's device and don't apply to factory runs. With team-managed keys and endpoints, select a specific provider model or endpoint. Auto continues to use Warp-managed inference. Your provider's retention follows your account and contract. Warp can't enforce ZDR for that provider.
## Credential boundaries
@@ -100,12 +91,12 @@ A factory handles four kinds of credentials, each with its own boundary:
| Credential | Used for | Boundary |
| --- | --- | --- |
-| **Inference credentials** | Model provider requests | Used only at the inference boundary; never injected into the sandbox |
-| **Execution secrets** | APIs, package registries, and tools an agent uses | Delivered from an explicit per-agent allowlist; factory agents that don't act as a specific user receive no managed secrets by default |
-| **Harness authentication** | Third-party harnesses such as Claude Code or Codex | Configured separately from the agent's secret allowlist |
-| **Repository identity** | Checking out code and pushing changes | Runs act with the creating user's authorization (changes are attributed to them) or as the agent itself for unattended work; set by the definition's [`credentialStrategy`](/factories/factory-as-code/#credentialstrategy) |
+| **Inference credentials** | Model provider requests from the Warp Agent | Credentials are used only at the Warp–provider boundary and never injected into the sandbox. |
+| **Execution secrets** | APIs, package registries, and tools an agent uses | Secrets are delivered from an explicit per-agent allowlist. Factory agents that don't act as a specific user receive no managed secrets by default. |
+| **Harness authentication** | Third-party harnesses such as Claude Code or Codex | Credentials are used inside the execution environment for direct provider calls. This authentication is configured separately from the agent's secret allowlist. |
+| **Repository identity** | Checking out code and pushing changes | Runs act with the creating user's authorization (changes are attributed to them) or as the agent itself for unattended work. The definition's [`credentialStrategy`](/factories/factory-as-code/#credentialstrategy) sets this behavior. |
-Scope each credential to the resources and actions its agent needs. Warp redacts known secret values at output boundaries, but redaction is a backstop, not a substitute for narrow external permissions and rotation. See [cloud agent secrets](/platform/secrets/), [harness authentication](/platform/harnesses/authentication/), [secret redaction](/support-and-community/privacy-and-security/secret-redaction/), and [team identity](/platform/team-access-billing-and-identity/) for the underlying controls.
+Scope each credential to the resources and actions its agent needs. Warp redacts known secret values at output boundaries, but redaction is a backstop, not a substitute for narrow external permissions and rotation. See [Cloud agent secrets](/platform/secrets/), [harness authentication](/platform/harnesses/authentication/), [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/), and [team identity](/platform/team-access-billing-and-identity/) for the underlying controls.
## Factory roles and permissions
@@ -113,17 +104,21 @@ Factory creation uses the team-level Warp Factories role. Team and workspace adm
Three roles govern an existing factory:
-* **User** - View and run the factory, and propose definition changes.
-* **Editor** - Edit the factory definition, configure its agents, repositories, and automations, attach existing integrations, secrets, and MCP servers, and select existing runners.
-* **Admin** - Manage members, delete the factory, and force-merge a blocked definition change.
+| Role | Permissions |
+| --- | --- |
+| User | View and run the factory. Propose definition changes. |
+| Editor | Edit the definition and configure agents, repositories, and automations. Attach existing integrations, secrets, and MCP servers. Select existing runners. |
+| Admin | Manage members. Delete the factory. Force-merge blocked definition changes. |
+
+Team and workspace admins and owners always have the Admin role. Factory admins manage roles within their factory. Team and workspace admins manage the team-level Warp Factories role.
-Team and workspace admins and owners always have the Admin role. Admins for a factory manage its roles; team and workspace admins manage the team-level role.
+Managing shared runners and connecting team-wide integrations and providers require separate team or workspace permissions.
-Managing shared runners and connecting team-wide integrations and providers require team or workspace permission. Factory roles don't control specification or pull request review. Treat factory definition changes as operational code, and protect merges through repository settings.
+Factory roles don't control specification or pull request review. For factory definition changes, treat the files as operational code and protect merges through repository settings.
## Metering
-Warp meters hosted compute, Warp-provided inference, and [platform usage](/support-and-community/plans-and-billing/platform-credits/). Self-hosting removes Warp-hosted compute charges. Your provider bills customer-supplied inference. Neither removes applicable platform charges. External inference bills are not fully represented in Warp's totals.
+Warp meters hosted compute, Warp-provided inference, and [platform usage](/support-and-community/plans-and-billing/platform-credits/). Self-hosting removes Warp-hosted compute charges, and customer-supplied inference is billed directly by your provider. Platform charges still apply in both cases, and Warp's totals don't fully reflect external inference costs.
## Deployment checklist
@@ -135,10 +130,10 @@ Warp meters hosted compute, Warp-provided inference, and [platform usage](/suppo
## Related pages
-* [**Deployment patterns**](/factories/deployment-patterns/) - Compare execution and inference boundaries.
-* [**Runners**](/factories/runners/) - Configure compute and worker compatibility.
-* [**Managed self-hosting**](/factories/self-hosting/) - Deploy and operate a worker backend.
-* [**Execution security**](/platform/execution-security/) - Review data boundaries, egress, and backend controls.
-* [**Team-managed model keys and endpoints**](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) - Configure inference credentials.
-* [**Roles and permissions**](/enterprise/team-management/roles-and-permissions/) - Govern team and workspace resources.
-* [Platform usage](/support-and-community/plans-and-billing/platform-credits/) - Understand agent-hour charges.
+* [Deployment patterns for Warp Factories](/factories/deployment-patterns/) - Compare execution models
+* [Runners for Warp Factories](/factories/runners/) - Configure compute and worker compatibility
+* [Self-hosting overview](/factories/self-hosting/) - Review managed backends and setup requirements
+* [Security and networking](/platform/execution-security/) - Review data boundaries, egress, and backend controls
+* [Team-managed LLM API keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) - Configure inference credentials
+* [Roles and permissions](/enterprise/team-management/roles-and-permissions/) - Govern team and workspace resources
+* [Platform usage](/support-and-community/plans-and-billing/platform-credits/) - Understand agent-hour charges
diff --git a/src/content/docs/factories/integrations/azure-devops.mdx b/src/content/docs/factories/integrations/azure-devops.mdx
index 650839284..ef3517e9c 100644
--- a/src/content/docs/factories/integrations/azure-devops.mdx
+++ b/src/content/docs/factories/integrations/azure-devops.mdx
@@ -26,13 +26,10 @@ Each factory identity consists of a separate Microsoft Entra application and ser
## Requirements
-* **A Warp team** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/).
-* **An Azure DevOps Services organization** - Use an organization hosted at `dev.azure.com`, with the project and repositories the factory needs.
-* **A connected Azure DevOps user** - Connect a user who can read the organization, project, and repositories you want to select.
-* **An active connection for each automation creator** - The user who creates an Azure DevOps automation must keep their own Azure DevOps OAuth connection active with the required scopes.
-* **Microsoft Entra and Azure DevOps administrators** - Administrators with the roles listed below approve and add the Manager.
-
-The Microsoft Entra and Azure DevOps approvals can be completed by different people. A setup link lets each administrator complete their step without a Warp account.
+* Membership in a [Warp team](/knowledge-and-collaboration/teams/).
+* An Azure DevOps Services organization at `dev.azure.com` with the project and repositories the factory needs.
+* An Azure DevOps account with read access to the organization, project, and selected repositories.
+* Access to Microsoft Entra and Azure DevOps administrators with the [required permissions](#required-administrator-permissions).
### Required administrator permissions
@@ -55,6 +52,8 @@ Start from factory setup to connect your account, select repositories, and provi
2. In the code host step, find the Azure DevOps row and click **Connect**. Complete the Microsoft sign-in to connect your Azure DevOps user.
3. Choose an Azure DevOps organization and project, then select the repositories the factory will use. Only resources your connected user can read appear.
4. If the organization already has an active Azure DevOps Manager, continue setup. Otherwise, connect the Manager yourself or send the setup link to the required administrators.
+
+ Different people can complete the Microsoft Entra and Azure DevOps approvals. Each administrator can use the setup link without a Warp account.
5. Complete the Manager approval in this order:
1. A Global Administrator or Privileged Role Administrator completes the Microsoft Entra approval.
2. A Project Collection Administrator completes the Azure DevOps approval.
@@ -64,7 +63,7 @@ When setup confirms that the identity is ready, the factory uses that identity f
## Configure Azure DevOps automations
-An Azure DevOps automation starts a factory run when a supported event matches its filters. Before starting a run, Warp checks the automation creator's Azure DevOps connection. New Azure DevOps factories include a default automation for pull request mentions, work item mentions, and work item assignments.
+An Azure DevOps automation starts a factory run when a supported event matches its filters. Before starting a run, Warp checks the automation creator's Azure DevOps connection. Each creator must keep their own OAuth connection active with the required scopes. New Azure DevOps factories include a default automation for pull request mentions, work item mentions, and work item assignments.
To configure an automation as code, ask the Warp Agent to update the factory definition or edit its `automations/` files directly. See [definitions as code](/factories/factory-as-code/).
@@ -74,7 +73,7 @@ To add or change a trigger in the factory dashboard:
2. Add an Azure DevOps trigger, then choose an event and its filters.
3. Click **Save**. Perform a matching action in Azure DevOps and confirm that a run starts in the factory dashboard.
-For general filter behavior, see [factory automations](/factories/automations/).
+For general filter behavior, see [Factory automations](/factories/automations/).
### Supported events and filters
diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx
index 80b420ff6..d78b66eb1 100644
--- a/src/content/docs/factories/integrations/github.mdx
+++ b/src/content/docs/factories/integrations/github.mdx
@@ -12,11 +12,13 @@ When you connect a factory to GitHub, repository activity starts work in your fa
## Prerequisites
-* **The Warp GitHub App** - Follow the [GitHub integration setup](/platform/integrations/github/) if you haven't already. One installation serves both the platform integration and factories.
-* **A factory with GitHub repositories** - The app must have access to at least one of the factory's repositories.
+* The Warp GitHub App installed. See [GitHub integration setup](/platform/integrations/github/).
+* At least one GitHub repository for the factory that the app can access.
## Connect GitHub to a factory
+One GitHub App installation serves both the platform integration and factories.
+
1. In the {VARS.FACTORY_WEB_APP}, click **+** next to **Factories** to open the setup wizard, then choose **I want to use repos from GitHub** under **Connect your code host**.
2. Under **Select your repos**, choose the repositories to provide code and context for the factory.
diff --git a/src/content/docs/factories/integrations/gitlab.mdx b/src/content/docs/factories/integrations/gitlab.mdx
index de285ec09..cba70e83c 100644
--- a/src/content/docs/factories/integrations/gitlab.mdx
+++ b/src/content/docs/factories/integrations/gitlab.mdx
@@ -12,9 +12,9 @@ When you connect a factory to GitLab, project activity starts work in your facto
## Prerequisites
-* **GitLab.com** - The integration supports GitLab.com only, not self-managed GitLab instances. To use a self-managed instance with a factory, see [connecting other code forges](/factories/code-forges/other-code-forges/). For standalone cloud agents, see the [GitLab access token setup](/platform/integrations/gitlab/).
-* **A top-level GitLab group you own** - Connecting GitLab links one top-level group to your Warp workspace, one-to-one. Creating the link requires the Owner role on the group and workspace admin permissions in Warp.
-* **A GitLab plan with service accounts and group webhooks** - Warp provisions service accounts in your group and installs a group webhook; both are GitLab Premium and Ultimate features. On a plan without group webhooks, factory credentials still work, but GitLab cannot trigger runs.
+* A GitLab.com account. Self-managed GitLab instances require [another code-forge setup](/factories/code-forges/other-code-forges/).
+* Owner access to a top-level GitLab group and workspace admin permissions in Warp.
+* A GitLab Premium or Ultimate plan with service accounts and group webhooks.
## Service accounts and access
@@ -25,8 +25,12 @@ Warp manages GitLab access through service accounts it creates in your connected
The connected group's webhook delivers merge request and comment events to Warp, and matching automations turn them into factory work.
+On a plan without group webhooks, factory credentials still work, but GitLab cannot trigger runs. For standalone cloud agents, see [GitLab access token setup](/platform/integrations/gitlab/).
+
## Connect GitLab to a factory
+Connecting GitLab links one top-level group to your Warp workspace, one-to-one.
+
1. In the {VARS.FACTORY_WEB_APP}, click **+** next to **Factories** to open the setup wizard.
2. Choose **I want to use repos from GitLab** under **Connect your code host**, then authorize with GitLab when prompted.
3. Under **Connect a GitLab group**, pick a top-level group you own and click **Next**. Warp creates the manager service account and installs the group webhook. A group that is already connected shows a **Connected** badge, and the selection is locked to it.
diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx
index 66771715a..e069a2d90 100644
--- a/src/content/docs/factories/integrations/jira.mdx
+++ b/src/content/docs/factories/integrations/jira.mdx
@@ -12,10 +12,9 @@ Connect Jira Cloud to your factory so your team can start factory work without l
## Prerequisites
-* **Jira Cloud** - The integration supports Jira Cloud only, not Jira Server or Data Center.
-* **A Jira site admin** - A site admin must install the Warp app and connect the Jira site to your Warp workspace.
-* **A factory** - You need a factory in the connected workspace and permission to edit its [definition](/factories/factory-as-code/).
-* **The Warp agent in Jira** - The **Warp** agent must be available on your Jira site so people can assign or mention it on work items. Jira lists it among Atlassian's Rovo agents.
+* A Jira Cloud site. Jira Server and Data Center are not supported.
+* A Jira site admin to install the Warp app and connect the site to your Warp workspace.
+* A factory in the connected workspace and permission to edit its [definition](/factories/factory-as-code/).
## Connect Jira and add an automation
@@ -30,6 +29,8 @@ If you aren't a Jira site admin, choose **Someone else** during setup and email
5. **Test the connection.** Assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory.
+ The **Warp** agent must be available on your Jira site to assign or mention it. Jira lists it among Atlassian's Rovo agents.
+
{/* VISUAL: A Jira work item assigned to Warp, showing the resulting agent session. */}
The standalone Jira integration uses the `warp-agent` label to start cloud agent runs. Factories use an automation instead.
diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx
index ce7367791..341ab9235 100644
--- a/src/content/docs/factories/integrations/linear.mdx
+++ b/src/content/docs/factories/integrations/linear.mdx
@@ -13,10 +13,10 @@ When the factory needs an answer, reply in Linear, or open the live run to steer
## Prerequisites
-* **A factory** - Create a factory with the agents and repositories needed to handle Linear work.
-* **A Linear workspace** - Use a Linear account that can authorize the Warp app for the workspace.
-* **A linked Warp account (agent sessions only)** - Anyone who starts a Linear agent session must link their Linear user to their Warp account. If Warp can't identify the session creator, Linear shows an authentication prompt instead of starting work.
-* **Code host access** - Configure repository access separately through the factory's [GitHub connection](/platform/integrations/github/). The factory needs it to change code or create a pull request.
+* A factory with the agents and repositories needed for Linear work. See the [Warp Factories quickstart](/factories/quickstart/).
+* A Linear account that can authorize the Warp app for the workspace.
+* A Warp account linked to your Linear user to start agent sessions.
+* Repository access through the factory's [GitHub connection](/platform/integrations/github/) for code changes and pull requests.
For workspace-level installation, reconnection, and removal steps, see the [Linear integration setup guide](/platform/integrations/linear/).
@@ -31,6 +31,8 @@ Warp then adds a default automation that routes new [agent sessions](#route-agen
## Route agent sessions
+If Warp can't identify the session creator, Linear shows an authentication prompt instead of starting work.
+
When someone mentions, assigns, or delegates the Warp app on an issue, Linear starts an agent session. The default automation created when you connected Linear routes new sessions from your selected teams to the factory, so assigning an issue or tagging the factory in a comment is enough to start work. If a session doesn't match any automation, the [Linear integration](/platform/integrations/linear/) handles it with its default behavior.
diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx
index d1cea5105..9f9c23384 100644
--- a/src/content/docs/factories/integrations/slack.mdx
+++ b/src/content/docs/factories/integrations/slack.mdx
@@ -13,8 +13,8 @@ Each factory appears in Slack as its own app with the factory's name and avatar.
## Prerequisites
-* **Permission to install Slack apps in the target workspace** - Workspace policy may require administrator approval before the app installs.
-* **Permission to update the factory** - Connecting Slack changes the factory's configuration.
+* Permission to install Slack apps in the target workspace.
+* Permission to update the factory's configuration.
## Connect the factory
@@ -86,7 +86,7 @@ using the connected Slack tools. Include links to each work item or pull
request, and report the Slack posting error if delivery fails.
```
-Replace `C0123456789` with the destination's channel ID. See [factory definition syntax](/factories/factory-as-code/#automationsnameautomationmd) for the other automation fields and schedule options.
+Replace `C0123456789` with the destination's channel ID. See [Factory definition syntax](/factories/factory-as-code/#automationsnameautomationmd) for the other automation fields and schedule options.
## Start and continue work from Slack
@@ -107,7 +107,7 @@ The Slack thread where work started is also where you follow it: the factory pos
For an overview of the factory's work items, open the app's **Home** tab in Slack. It groups them by stage (Triage, Planning, Building, Reviewing, Complete, and Cancelled), offers stage and date filters, and links each work item back to its Slack thread, factory run, issue, or pull request when available.
-Work that starts in Slack still ends at a pull request for a person to review — see [how Warp Factories work](/factories/how-factories-work/).
+Work that starts in Slack still ends at a pull request for a person to review — see [How Warp Factories work](/factories/how-factories-work/).
## Who can start work
diff --git a/src/content/docs/factories/integrations/teams.mdx b/src/content/docs/factories/integrations/teams.mdx
index 139205348..3e0caaff9 100644
--- a/src/content/docs/factories/integrations/teams.mdx
+++ b/src/content/docs/factories/integrations/teams.mdx
@@ -117,7 +117,7 @@ For UI-selected teams and standard channels, copy these values from the seeded a
Optional `keywords` and `user_ids` filters narrow matching by message content and author.
-See the [factory definition syntax](/factories/factory-as-code/#integrations) for integration settings, triggers, and filter shapes.
+See the [Factory definition syntax](/factories/factory-as-code/#integrations) for integration settings, triggers, and filter shapes.
## Troubleshooting
diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx
index f5fec5ad7..2c4c6aeac 100644
--- a/src/content/docs/factories/quickstart.mdx
+++ b/src/content/docs/factories/quickstart.mdx
@@ -12,66 +12,71 @@ Create your first factory and take one small work item from prompt to pull reque
## Prerequisites
-If you don't have a Warp account, [sign up for Warp](https://app.warp.dev/signup). If you're not on a team, [join or create a team](/knowledge-and-collaboration/teams/) before starting.
-
-* **Factory creation access** - On an existing Warp team, you need team or workspace admin access, or the team-level Warp Factories Editor role. See [factory roles and permissions](/factories/infrastructure-and-security/#factory-roles-and-permissions).
-* **Usage requirements** - Your factory's agents consume eligible team usage. Check your team's [access and billing requirements](/platform/team-access-billing-and-identity/) before starting.
-* **Repository access** - Access to the repositories you want the factory to work on. If your organization restricts connections to Warp, involve a code-host administrator.
+* A [Warp account](https://app.warp.dev/signup) and membership in a [Warp team](/knowledge-and-collaboration/teams/).
+* Team or workspace admin access, or the team-level [Warp Factories Editor role](/factories/infrastructure-and-security/#factory-roles-and-permissions).
+* Available usage in your team's balance for factory runs. See [access and billing requirements](/platform/team-access-billing-and-identity/).
+* Access to the repositories you want the factory to work on.
## Set up your factory
:::note
-For GitHub and GitLab repositories, an agent connected to [Factory MCP](/factories/factory-mcp/#set-up-with-your-coding-agent) can run this whole setup. Use the web setup wizard for Azure DevOps. If the wizard is still open when the agent finishes, refresh the page to see the new factory.
+For GitHub and GitLab repositories, an agent connected to [Factory MCP](/factories/factory-mcp/#set-up-with-your-coding-agent) can run this setup. For Azure DevOps, follow the steps below in the {VARS.FACTORY_WEB_APP}. If the setup page is still open when the agent finishes, refresh it to see the new factory.
:::
-1. Open the {VARS.FACTORY_WEB_APP} and sign in. Choose the Warp team that will own the factory, then click **+** next to **Factories**.
+1. Open the {VARS.FACTORY_WEB_APP} and sign in if prompted. To switch teams, click your avatar, hover over the team name, and select another team.
+
+2. Click **+** next to **Factories**.
The factory setup control in the sidebar.
-2. Under **Connect your code hosts**, connect GitHub, GitLab, or Azure DevOps. Choose the GitHub organization, GitLab group, or Azure DevOps organization and project to connect.
-
- Azure DevOps organizations require [one-time administrator approval](/factories/integrations/azure-devops/#requirements). The setup flow lets you send the approval link to the required administrators.
-
- To use another code forge, select **No repo**, finish creating the factory, then [configure repository access from the default runner](/factories/code-forges/other-code-forges/).
+3. On the "Connect your code hosts" screen, select GitHub, GitLab, or Azure DevOps, then choose the organization or group to connect. For Azure DevOps, also choose a project. Click **Next**.
- 
- Connected GitHub organizations available during setup.
+ 
+ The GitHub organization dropdown in factory setup.
-3. On **Select your repos**, select one or two repositories that ship together, then click **Add repos**. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository already covered by another factory.
+ If your organization restricts connections to Warp, involve a code-host administrator. Azure DevOps requires [one-time administrator approval](/factories/integrations/azure-devops/#requirements); you can send the approval link during setup.
+
+ For other code forges, see [Connecting other code forges to your factory](/factories/code-forges/other-code-forges/).
+
+4. On the "Set up your factory" screen, select the repositories your factory will work on. See [sizing a factory](/factories/#sizing-a-factory).
- 
- The repository selector for factory setup.
+ 
+ A repository search during factory setup.
-4. Name the factory. This also sets its [**Foreman name**](/factories/factory-agents/#foreman-name), the handle your team @-mentions in Slack and Linear.
+5. Enter a "Factory name". This also sets the default [foreman name](/factories/factory-agents/#foreman-name), the handle your team @-mentions in Slack and Linear. Click **Next**.
- 
- Identity settings for the factory and foreman.
+ 
+ The factory name and optional details during setup.
-5. Choose which agents the foreman can dispatch. Leave **Implement** enabled so this quickstart ends in a pull request. See [factory agents](/factories/factory-agents/) for details.
+6. Choose which agents the foreman can dispatch. Leave **Code** enabled so this quickstart ends in a pull request. See [About factory agents](/factories/factory-agents/) for details.
- 
+ 
Default factory agents enabled during setup.
-6. Optionally, connect Slack and an issue tracker. You can add either later from [connect your factory](/factories/connect-your-factory/).
+7. Optionally, connect Slack and an issue tracker. You can add either later from [Connect your factory](/factories/connect-your-factory/).
Warp creates the factory and opens its [dashboard](/factories/factory-dashboard/).
## Send your first work item
-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/).
+Send a request to your factory's foreman from the {VARS.FACTORY_WEB_APP}. You can also send work from [Slack or an issue tracker](/factories/connect-your-factory/).
+
+1. In the web app sidebar, click **New Chat**.
+
+2. In the dropdown below the prompt input, choose your factory.
-1. Describe one small, verifiable change and send it:
+3. Enter one small, verifiable change, then click the send arrow:
```text title="Example first request"
Add a "Local development" section to README.md that summarizes the setup
@@ -79,16 +84,16 @@ Send work from Slack or an issue tracker. If you skipped integrations, start a r
repo's lint check, and open a pull request.
```
-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/).
+4. The foreman dispatches the agents needed for the request and posts progress where it started. In the sidebar, click **Runs** to follow the [foreman and child runs](/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:
+ If you sent the request from Slack, you can follow along in its thread:
A factory Slack thread with live progress.
-3. When the foreman hands back the pull request, review the changes and validation results, then merge it according to your normal process.
+5. When the foreman hands back the pull request, review the changes and validation results, then merge it according to your normal process.
## Next steps
diff --git a/src/content/docs/factories/runners.mdx b/src/content/docs/factories/runners.mdx
index b034e8a20..1ee6d9744 100644
--- a/src/content/docs/factories/runners.mdx
+++ b/src/content/docs/factories/runners.mdx
@@ -9,44 +9,56 @@ description: >-
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. Factory agents select runners through the [factory definition](/factories/factory-as-code/) or the [factory dashboard](/factories/factory-dashboard/).
+Runners are reusable compute configurations for [cloud agent runs](/platform/). Each runner selects an operating system, CPU architecture, instance size, and sandbox image.
-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.
+An [environment](/platform/environments/) supplies the repositories, toolchain, and workspace setup. The execution host determines whether the work runs on [Warp-hosted](/factories/warp-hosting/) infrastructure or a [self-hosted worker](/factories/self-hosting/).
-## 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.
+Reuse a runner across workflows, or choose different instance sizes for lightweight checks and resource-intensive 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.
-:::
+## Defaults and overrides
+
+Factory agents inherit the factory's default runner unless an agent or automation selects another. The factory default (`agentDefaults.runner`) must be Linux because it supplies the factory-managed environment. Individual agents and automations can select other supported operating systems.
-## Key features
+Factories manage their repositories and workspace by default, so you don't need to create a separate environment. To use an existing one, set [`agentDefaults.environmentId`](/factories/factory-as-code/#agentdefaultsenvironmentid).
+
+For standalone cloud runs, a run-level runner overrides the environment's default runner for that run only. Omitting `instanceShape` uses the workspace's default size.
+
+## Configure runners for a factory
-What runners give you:
+In the [factory definition](/factories/factory-as-code/), `runners/*.yaml` files define runners. Set `agentDefaults.runner` to the default runner's name, or set `runner` on an agent or automation to override it.
-* **Reusable compute configs** – Define an OS, architecture, instance size, and sandbox image once, then reuse the runner across cloud agent runs and orchestration without repeating the configuration.
-* **Right-sized hardware** – Choose the number of vCPUs and amount of memory a run needs, so lightweight tasks stay cheap and heavy builds get enough resources.
-* **Operating systems** – Run agents on Linux, macOS, or Windows.
-* **Independent of environments** – Override an environment's default runner per run without changing the environment itself.
+For Warp-managed factories, edit runner files in the [factory dashboard](/factories/factory-dashboard/#edit-definitions-in-the-factory-definition-tab). For GitHub-backed factories, edit them through pull requests in the definition repository. See [runner file syntax](/factories/factory-as-code/#runnersnameyaml) for fields and a complete example.
## How runners fit into cloud agent runs
-A runner is the compute layer for a cloud agent run. When a run starts, Warp provisions a sandbox, clones the repositories, runs the runner's `setupCommands` in order, and then runs the environment's setup commands before the agent begins. A setup command that exits with a nonzero status or runs longer than 30 minutes fails the run during environment setup.
+For Warp-hosted runs, Warp provisions a sandbox and clones the repositories before setup. The runner's `setupCommands` run in order, followed by the environment's setup commands, before the agent begins. A setup command that exits with a nonzero status or runs longer than 30 minutes fails the run during environment setup.
-* **Environment** – Defines the workspace: Docker image, repositories, and setup commands. See [Environments](/platform/environments/).
-* **Runner** – Defines the OS, architecture, instance shape (vCPUs and memory), and sandbox image.
-* **Host** – Determines where execution happens (Warp-hosted or [self-hosted](/factories/self-hosting/) infrastructure).
+Self-hosted backends apply runner settings differently, as described below.
-Each environment has a default runner. Specifying a runner for a run overrides that default for that run only.
+## Runner settings by execution host
+
+The execution host determines how each runner setting is used:
+
+| Setting | Warp-hosted | Direct | Kubernetes | Docker |
+| --- | --- | --- | --- | --- |
+| `platform.os`, `platform.arch`, `platform.mac.version` | Selects the sandbox OS, architecture, and macOS VM version | Does not configure the host. The worker host determines the platform. | Use Linux. The cluster and `pod_template` schedule nodes. | Use Linux. The Docker daemon determines the architecture. |
+| `platform.linux.dockerImage` | Linux sandbox image | Ignored | Task and setup container image | Task container image |
+| `platform.linux.registryCredentialSecretName` | Warp-managed private-registry credential | Ignored | Ignored. Use `imagePullSecrets`. | Ignored. Configure registry credentials on the worker, such as in its Docker config. |
+| `instanceShape` | Sandbox size, subject to plan limits. Omitted uses the workspace default. | Ignored. The task uses host resources. | Task-container requests and limits. Overrides matching `pod_template` resources. Omitted keeps template or cluster defaults. | Task-container limits. Omitted adds no limits. |
+
+Self-hosted runner settings don't provision capacity. Worker configuration controls resources, registry authentication, volumes, placement, and backend policy. See [choosing a managed backend](/factories/self-hosting/#choosing-a-managed-backend) for execution options and [runner file syntax](/factories/factory-as-code/#runnersnameyaml) for configuration fields.
## Operating systems
- Linux runners execute the agent in a fresh Docker container. Warp uses the Docker image you select to provide the agent's base filesystem and toolchains.
+ Warp-hosted Linux runners execute the agent in a fresh Docker container. The selected image provides the agent's base filesystem and toolchain.
- Warp-hosted Linux runners support any public x86-64 or aarch64 image, and private images with a team credential. By default, runners use [`warpdotdev/dev-base:latest`](https://hub.docker.com/r/warpdotdev/dev-base).
+ Warp-hosted Linux runners support x86-64 and aarch64 images. Use a public image, or a private image with a team credential. The default image is [`warpdotdev/dev-base:latest`](https://hub.docker.com/r/warpdotdev/dev-base).
+
+ The image must match the runner's architecture and include `bash` and core utilities such as `ls` and `mkdir`. See [image and container-user requirements](/platform/environments/configuring-environments/) for runtime compatibility.
To pull a private image, choose a team-owned credential for the image's registry in the "Private image credential" dropdown when you create or edit the runner. See [AWS ECR credentials](/platform/secrets/#aws-ecr-credentials) for Amazon ECR.
@@ -55,17 +67,20 @@ Each environment has a default runner. Specifying a runner for a run overrides t
Warp-hosted Linux runners can also run Docker containers and KVM-based virtual machines, such as the Android emulator.
- macOS runners execute the agent in a fresh VM on Apple Silicon. You can choose from macOS 14, 15, 26, or 27. If not specified, Warp uses the current macOS release.
+ Warp-hosted macOS runners execute the agent in a fresh VM on Apple Silicon. Choose macOS 14, 15, 26, or 27. If no version is specified, Warp uses macOS 26.
The VM has Xcode and standard system tools installed, along with simulators for iOS, watchOS, and tvOS. Use setup commands to install additional dependencies.
Downloads from Homebrew and popular language package managers are cached automatically.
- The following resource configurations are supported:
- * 4 vCPUs, 7 GB memory
- * 6 vCPUs, 14 GB memory
- * 8 vCPUs, 14 GB memory
- * 12 vCPUs, 28 GB memory
- * 12 vCPUs, 56 GB memory
+ Supported resource configurations:
+
+ | vCPUs | Memory |
+ | --- | --- |
+ | 4 | 7 GB |
+ | 6 | 14 GB |
+ | 8 | 14 GB |
+ | 12 | 28 GB |
+ | 12 | 56 GB |
Windows runners are available for Warp-hosted execution and run each agent in a fresh Windows VM. They support x86-64 architecture only and don't use Docker images or expose a custom Windows image setting.
@@ -86,9 +101,9 @@ Each environment has a default runner. Specifying a runner for a run overrides t
Both `vcpus` and `memoryGb` must be positive powers of two within your plan's resource limit. Omit `instanceShape` to use the workspace default shape.
- A factory's default runner (`agentDefaults.runner`) must be Linux because it supplies the factory-managed environment. Select a Windows runner on an individual agent or automation with `runner`.
+ Select a Windows runner on an individual agent or automation with `runner`. The factory's default runner remains Linux.
- Managed self-hosted workers currently run on Linux. Use [Warp-hosted execution](/factories/warp-hosting/) for Windows runners.
+ Self-hosted Docker and Kubernetes backends run Linux tasks, even when the worker process runs on another OS. Use [Warp-hosted execution](/factories/warp-hosting/) for Windows runners.
@@ -98,31 +113,32 @@ The legacy [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) also supports creating,
### Create a runner
-Create a runner with a name and the compute configuration you need.
+Name the runner and choose its compute configuration:
-```sh
+```bash
oz runner create \
- --name \
+ --name RUNNER_NAME \
--os linux \
- --docker-image \
+ --docker-image IMAGE_REFERENCE \
--vcpus 4 \
--memory-gb 8 \
- --setup-command "" \
+ --setup-command "SETUP_COMMAND" \
--description "Optional description"
```
-Key flags:
+Replace `RUNNER_NAME` with a human-readable label, `IMAGE_REFERENCE` with a Linux container image, and `SETUP_COMMAND` with a sandbox setup command.
-* `--name` (`-n`) — human-readable label for the runner (required).
-* `--description` (`-d`) — optional description (max 240 characters).
-* `--os` — target operating system: `linux` (default), `macos`, or `windows`.
-* `--arch` — CPU architecture: `auto` (default), `x86-64`, or `aarch64`. `auto` uses the OS default (x86-64 on Linux and Windows, aarch64 on macOS).
-* `--docker-image` — Docker image reference for the sandbox. Linux only.
-* `--macos-version` — macOS version for the sandbox: `14`, `15`, `26`, or `27`. macOS only.
-* `--vcpus` — number of vCPUs for the instance shape. Must be set together with `--memory-gb`.
-* `--memory-gb` — memory in GB for the instance shape. Must be set together with `--vcpus`.
-* `--setup-command` (`-c`) — command to run when initializing the sandbox. Repeatable.
-* `--team` / `--personal` — create the runner at the team level or private to your account.
+| Flag | Description |
+| --- | --- |
+| `--name` (`-n`) | Required human-readable label. |
+| `--description` (`-d`) | Optional description, up to 240 characters. |
+| `--os` | `linux` (default), `macos`, or `windows`. |
+| `--arch` | `auto` (default), `x86-64`, or `aarch64`. Auto uses x86-64 on Linux and Windows, or aarch64 on macOS. |
+| `--docker-image` | Sandbox image reference. Linux only. |
+| `--macos-version` | `14`, `15`, `26`, or `27`. macOS only. |
+| `--vcpus`, `--memory-gb` | Instance size in vCPUs and GB of memory. Set both together when creating a runner. |
+| `--setup-command` (`-c`) | Command to run during sandbox setup. Repeat for additional commands. |
+| `--team`, `--personal` | Create a team runner or one private to your account. |
:::caution
OS-specific options must match `--os`. Use `--docker-image` only with `--os linux`, and `--macos-version` only with `--os macos`. Windows doesn't have an OS-specific option.
@@ -130,7 +146,7 @@ OS-specific options must match `--os`. Use `--docker-image` only with `--os linu
### List runners
-```sh
+```bash
oz runner list
```
@@ -138,43 +154,45 @@ Add `--sort-by name` or `--sort-by last-updated` to order the results.
### Update a runner
-Change a runner's name, description, compute shape, or sandbox image without recreating it. Identify the runner by its UID, or by `--name` when you don't have the UID.
+Identify the runner by UID or name. Replace `RUNNER_UID` with its UID, `RUNNER_NAME` with its current name, and `NEW_RUNNER_NAME` with the new name:
-```sh
+```bash
# Update by UID
-oz runner update --vcpus 8 --memory-gb 16
+oz runner update RUNNER_UID --vcpus 8 --memory-gb 16
# Rename a runner (UID identifies it, --name sets the new name)
-oz runner update --name "new name"
+oz runner update RUNNER_UID --name "NEW_RUNNER_NAME"
# Update by name when you don't have the UID
-oz runner update --name --docker-image node:22
+oz runner update --name RUNNER_NAME --docker-image node:22
```
-When updating by UID, `--vcpus` and `--memory-gb` can be set independently—the value you don't pass is preserved.
+When updating by UID, `--vcpus` and `--memory-gb` can be set independently. The value you don't pass is preserved. Updates can change the name, description, compute size, or sandbox image without recreating the runner.
### Delete a runner
-```sh
-oz runner delete
+Replace `RUNNER_UID` with the runner's UID:
+
+```bash
+oz runner delete RUNNER_UID
```
Add `--force` to skip the confirmation prompt.
## Using a runner for a run
-Pass a runner's ID to `oz agent run-cloud` to run a cloud agent on that runner. This overrides the environment's default runner for that run.
+For a standalone cloud task, pass a runner UID with `--runner`. Replace `RUNNER_UID` with the UID and `TASK_PROMPT` with the agent's instructions:
-```sh
-oz agent run-cloud --runner --prompt ""
+```bash
+oz agent run-cloud --runner RUNNER_UID --prompt "TASK_PROMPT"
```
You can also select a runner when [running orchestrated agents](/platform/orchestration/multi-agent-runs/), so child agents run on the compute shape their work requires.
## Related pages
-* [Environments](/platform/environments/) – Define the repos, image, and setup commands an agent works with.
-* [Warp-hosted execution](/factories/warp-hosting/) – Run factory work on Warp-managed infrastructure.
-* [Managed self-hosting](/factories/self-hosting/) – Run factory work on Linux infrastructure you manage.
-* [Managing cloud agents](/platform/managing-cloud-agents/) – Start, monitor, and manage cloud agent runs.
-* [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/) – Full command-line reference for runners and every other cloud agent command.
+* [Cloud agent environments](/platform/environments/) - Define repositories, images, and workspace setup
+* [Warp-hosted execution for Warp Factories](/factories/warp-hosting/) - Review hosted capacity and networking
+* [Self-hosting overview](/factories/self-hosting/) - Choose a managed backend
+* [Managing cloud agents](/platform/managing-cloud-agents/) - Start and monitor standalone runs
+* [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/) - Install and authenticate the supported legacy CLI
diff --git a/src/content/docs/factories/self-hosting/direct-monorepo-worktrees.mdx b/src/content/docs/factories/self-hosting/direct-monorepo-worktrees.mdx
index 8c5988e21..10dfdc0c1 100644
--- a/src/content/docs/factories/self-hosting/direct-monorepo-worktrees.mdx
+++ b/src/content/docs/factories/self-hosting/direct-monorepo-worktrees.mdx
@@ -28,9 +28,11 @@ Direct backend tasks share the worker host's filesystem, network, processes, and
### Prerequisites
-* **A Direct backend worker host** - Install the worker and the {VARS.WARP_AGENT_CLI} as described in [Managed: Direct backend](/factories/self-hosting/managed-direct/).
-* **Git credentials for the monorepo** - Use an SSH key in the worker service account's home directory, a system-level Git credential helper, or a credential helper in the base clone's repository config. The Direct backend sets `GIT_CONFIG_GLOBAL` to a task-local file, so helpers configured only in the service account's normal global Git config are unavailable to tasks.
-* **A base clone path** - Choose a dedicated path outside `workspace_root`, such as `/srv/warp/repos/product-base`. The worker account needs write access because Git stores worktree metadata in the base clone.
+* A Direct backend host with the worker and the {VARS.WARP_AGENT_CLI} installed. See [Managed: Direct backend](/factories/self-hosting/managed-direct/).
+* Git credentials for the monorepo through an SSH key in the worker service account's home directory, a system-level credential helper, or a helper in the base clone's repository config.
+* A dedicated base clone path outside `workspace_root`, writable by the worker account.
+
+The Direct backend sets `GIT_CONFIG_GLOBAL` to a task-local file, so helpers configured only in the service account's normal global Git config are unavailable to tasks. Git stores worktree metadata in the base clone, which is why the worker needs write access.
Create a clone without a checked-out working tree:
diff --git a/src/content/docs/factories/self-hosting/external-orchestrators.mdx b/src/content/docs/factories/self-hosting/external-orchestrators.mdx
index 57fea82a8..18cfd3c20 100644
--- a/src/content/docs/factories/self-hosting/external-orchestrators.mdx
+++ b/src/content/docs/factories/self-hosting/external-orchestrators.mdx
@@ -19,9 +19,10 @@ Both patterns use the managed architecture: Warp accepts triggers and routes run
## Prerequisites
-Complete the shared [managed prerequisites](/factories/self-hosting/#managed-prerequisites). The one-shot example below uses one Default Service Account agent key for both the worker and `run-cloud`. When those actions run in different processes, use a self-hosted worker key for the worker and an agent key for the run creator.
-
-Install `oz-agent-worker` from a [published release](https://github.com/warpdotdev/oz-agent-worker/releases). One-shot Direct also requires the {VARS.WARP_AGENT_CLI} on the allocated host. The Command backend worker requires the tools used by your dispatch and cancellation commands.
+* Managed self-hosting access, network connectivity, and credentials. See the [shared managed prerequisites](/factories/self-hosting/#managed-prerequisites).
+* `oz-agent-worker` installed from a [published release](https://github.com/warpdotdev/oz-agent-worker/releases).
+* For one-shot Direct, the {VARS.WARP_AGENT_CLI} on the allocated host.
+* For the Command backend, the tools used by the dispatch and cancellation commands.
## Using one-shot Direct
@@ -43,6 +44,8 @@ For a job created directly through the Agent API that must exit immediately, set
Add this script to the job your orchestrator starts. `CI_JOB_ID` must be unique for each job.
+This example uses one Default Service Account agent key for both the worker and `run-cloud`. When those actions run in different processes, use a self-hosted worker key for the worker and an agent key for the run creator.
+
```bash title="run-agent.sh"
#!/usr/bin/env bash
set -euo pipefail
diff --git a/src/content/docs/factories/self-hosting/index.mdx b/src/content/docs/factories/self-hosting/index.mdx
index c4bec7e4b..e5c33b034 100644
--- a/src/content/docs/factories/self-hosting/index.mdx
+++ b/src/content/docs/factories/self-hosting/index.mdx
@@ -21,7 +21,7 @@ With [unmanaged execution](/platform/unmanaged-execution/), your CI system, sche
| Aspect | Managed | Unmanaged |
| --- | --- | --- |
| Run lifecycle | The {VARS.WARP_AUTOMATION_PLATFORM} routes each run to a worker | Your system starts and stops each CLI process |
-| Host support | Linux | Linux, macOS, and Windows |
+| Task platform | Depends on the backend; Docker and Kubernetes tasks use Linux | Linux, macOS, and Windows |
| Execution | Docker container, Kubernetes Job, direct host process, or external runtime | The host environment you provide |
| Triggers | Integrations, schedules, API, web app, and CLI | CI, cron, scripts, and internal schedulers |
@@ -31,7 +31,7 @@ Use managed and unmanaged runs together when different workflows need different
Use [unmanaged execution](/platform/unmanaged-execution/) when any of these conditions apply:
-* Agents must run on macOS or Windows.
+* Your existing macOS or Windows workflow invokes the agent CLI directly.
* Your system should own both the trigger and process lifecycle.
* You want to add `oz agent run` to an existing CI job or script.
@@ -47,13 +47,11 @@ Use the managed architecture when the {VARS.WARP_AUTOMATION_PLATFORM} should acc
## Managed prerequisites
-All managed deployments require:
+* Outbound network access from the worker and agent runtime to Warp. No inbound ports are required. See [Security and networking](/platform/execution-security/).
+* A worker ID for routing runs with `--host`.
+* Worker credentials. Docker, Kubernetes, Direct, and Command workers accept a [self-hosted worker API key](/agents/cli/oz-cli/api-keys/#creating-a-self-hosted-worker-api-key).
-* **Outbound network access** - The worker and agent runtime must reach Warp. You do not need to open inbound ports. See [Security and networking](/platform/execution-security/) for endpoints and data boundaries.
-* **A worker ID** - Choose the value used to route runs with `--host`. Multiple long-lived workers can share an ID for load balancing. Use a unique ID for each one-shot Direct job.
-* **Worker credentials** - Docker, Kubernetes, Direct, and Command workers can use a [self-hosted worker API key](/agents/cli/oz-cli/api-keys/#creating-a-self-hosted-worker-api-key). Store it in your secret manager and provide it as `WARP_API_KEY` or `--api-key`.
-
-For unattended run creation through `oz agent run-cloud` or the API, use an **agent API key associated with the Default Service Account**. In the {VARS.WEB_APP} settings, create an Agent key and choose **Default Service Account**. The same agent key can authenticate the worker when one job both starts the worker and creates the run. Otherwise, give the worker a self-hosted worker key and the run creator an agent key. See [API keys for the {VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/api-keys/) for the key types and creation flow.
+Store the worker key in your secret manager and provide it as `WARP_API_KEY` or `--api-key`.
Backend pages list the remaining runtime-specific requirements, such as Docker, Kubernetes, or the {VARS.WARP_AGENT_CLI} binary.
@@ -61,11 +59,17 @@ Backend pages list the remaining runtime-specific requirements, such as Docker,
`oz-agent-worker` connects to the {VARS.WARP_AUTOMATION_PLATFORM}, waits for tasks addressed to its worker ID, and handles each task with the configured backend. Docker, Kubernetes, and Direct run the agent on worker infrastructure. Command hands the task to an external runtime.
-Start with the [self-hosting quickstart](/factories/self-hosting/quickstart/) for a Docker worker. For exact flags and YAML fields, use the [self-hosted worker reference](/factories/self-hosting/reference/).
+Multiple long-lived workers can share an ID for load balancing. Use a unique ID for each one-shot Direct job.
+
+Start with the [Self-hosting quickstart](/factories/self-hosting/quickstart/) for a Docker worker. For exact flags and YAML fields, use the [Self-hosted worker reference](/factories/self-hosting/reference/).
### Routing runs to self-hosted workers
-Set the run's host to the connected worker's ID. From the {VARS.WARP_AGENT_CLI}:
+Set the run's host to the connected worker's ID.
+
+For unattended run creation through `oz agent run-cloud` or the API, use an **agent API key associated with the Default Service Account**. In the {VARS.WEB_APP} settings, create an Agent key and choose **Default Service Account**. The same agent key can authenticate the worker when one job both starts the worker and creates the run. Otherwise, give the worker a self-hosted worker key and the run creator an agent key. See [API keys for the {VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/api-keys/) for the key types and creation flow.
+
+From the {VARS.WARP_AGENT_CLI}:
```bash
oz agent run-cloud \
diff --git a/src/content/docs/factories/self-hosting/managed-direct.mdx b/src/content/docs/factories/self-hosting/managed-direct.mdx
index 91b9e42cd..4cf629237 100644
--- a/src/content/docs/factories/self-hosting/managed-direct.mdx
+++ b/src/content/docs/factories/self-hosting/managed-direct.mdx
@@ -33,11 +33,10 @@ The Direct backend does not provide per-task container isolation. Each task runs
## Prerequisites
-Complete the shared [managed prerequisites](/factories/self-hosting/#managed-prerequisites), then prepare:
-
-* **A worker host** - Grant write access to `workspace_root`, which defaults to `/var/lib/oz/workspaces`.
-* **The `oz-agent-worker` binary** - Install it on the worker host through [Homebrew or a prebuilt binary](/factories/self-hosting/managed-docker/#install-and-run-the-worker).
-* **The {VARS.WARP_AGENT_CLI}** - Install it in `PATH` on the worker host, or set `oz_path` in the config file. See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli).
+* Managed self-hosting access, network connectivity, and credentials. See the [shared managed prerequisites](/factories/self-hosting/#managed-prerequisites).
+* A worker host with write access to `workspace_root`, which defaults to `/var/lib/oz/workspaces`.
+* The `oz-agent-worker` binary on the worker host. See [Homebrew or prebuilt binary installation](/factories/self-hosting/managed-docker/#install-and-run-the-worker).
+* The {VARS.WARP_AGENT_CLI} in `PATH` on the worker host, or selected with `oz_path` in the config file. See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli).
---
diff --git a/src/content/docs/factories/self-hosting/managed-docker.mdx b/src/content/docs/factories/self-hosting/managed-docker.mdx
index 44128cd83..3e56784f7 100644
--- a/src/content/docs/factories/self-hosting/managed-docker.mdx
+++ b/src/content/docs/factories/self-hosting/managed-docker.mdx
@@ -20,11 +20,10 @@ Run the `oz-agent-worker` daemon with the **Docker backend** — the default man
## Prerequisites
-Complete the shared [managed prerequisites](/factories/self-hosting/#managed-prerequisites), then prepare:
-
-* **A machine to run the worker** - Use a Linux VM, server, or workstation. On macOS, use [Homebrew](#option-2-homebrew) or a [release binary](#option-3-github-releases-binary). On Windows, use a [release binary](#option-3-github-releases-binary).
-* **Docker** - Install a **linux/amd64** or **linux/arm64** Docker daemon that runs Linux containers. Windows containers are not supported. Verify the daemon with `docker info`.
-* **Task images** - Use a glibc-based image, such as Debian, Ubuntu, or a non-Alpine variant of an official image. Musl-based images such as Alpine Linux are not supported. Add required tools, binaries, scripts, and system packages to the [environment's custom image](/platform/environments/).
+* Managed self-hosting access, network connectivity, and credentials. See the [shared managed prerequisites](/factories/self-hosting/#managed-prerequisites).
+* A Linux VM, server, or workstation, or a macOS or Windows host using a native worker binary.
+* A `linux/amd64` or `linux/arm64` Docker daemon running Linux containers. Windows containers are not supported.
+* A glibc-based task image with the required tools and dependencies. See [custom environment images](/platform/environments/). Musl-based images such as Alpine Linux are not supported.
### Install Docker
@@ -52,6 +51,8 @@ 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.
+On macOS, use [Homebrew](#option-2-homebrew) or a [release binary](#option-3-github-releases-binary). On Windows, use a [release binary](#option-3-github-releases-binary).
+
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)
@@ -152,7 +153,7 @@ backend:
- name: GITHUB_TOKEN # inherits from host environment
```
-Pass it with `--config-file config.yaml`. See the [self-hosted worker reference](/factories/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.
---
diff --git a/src/content/docs/factories/self-hosting/managed-kubernetes.mdx b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx
index efcacefd8..a74a4f104 100644
--- a/src/content/docs/factories/self-hosting/managed-kubernetes.mdx
+++ b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx
@@ -30,13 +30,21 @@ Deploy the `oz-agent-worker` daemon into a Kubernetes cluster with the included
## Prerequisites
-Complete the shared [managed prerequisites](/factories/self-hosting/#managed-prerequisites), then prepare:
+* Managed self-hosting access, network connectivity, and credentials. See the [shared managed prerequisites](/factories/self-hosting/#managed-prerequisites).
+* A Kubernetes cluster whose API server is reachable from the worker, with the [required permissions](#cluster-permissions).
+* [Helm](https://helm.sh/docs/intro/install/) installed locally and `kubectl` authenticated to the target cluster.
+* A glibc-based task image with the required tools and dependencies. See [custom environment images](/platform/environments/). Musl-based images such as Alpine Linux are not supported.
-* **A Kubernetes cluster** - The worker process must reach the API server. The cluster must:
- * Allow the task namespace to create Jobs with a **root init container**, unless you enable native image volumes with `kubernetesBackend.useImageVolumes=true`.
- * 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/)** - Install Helm locally and authenticate `kubectl` against the target cluster.
-* **Task images** - Use a glibc-based image, such as Debian, Ubuntu, or a non-Alpine variant of an official image. Musl-based images such as Alpine Linux are not supported. Add required tools, binaries, scripts, and system packages to the [environment's custom image](/platform/environments/).
+### Cluster permissions
+
+The task namespace must allow Jobs with a root init container unless native image volumes are enabled with `kubernetesBackend.useImageVolumes=true`.
+
+The worker needs these namespace-scoped permissions:
+
+* `create`, `get`, `list`, `watch`, and `delete` on `jobs`.
+* `get`, `list`, and `watch` on `pods`.
+* `get` on `pods/log`.
+* `list` on `events`.
---
@@ -146,7 +154,7 @@ Each release runs a single worker replica. To scale out, install more releases w
* `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](/factories/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.
---
diff --git a/src/content/docs/factories/self-hosting/quickstart.mdx b/src/content/docs/factories/self-hosting/quickstart.mdx
index 1052df1ac..760cb2d42 100644
--- a/src/content/docs/factories/self-hosting/quickstart.mdx
+++ b/src/content/docs/factories/self-hosting/quickstart.mdx
@@ -18,9 +18,12 @@ This quickstart sets up the [managed architecture](/factories/self-hosting/#mana
## Prerequisites
-* **Managed self-hosting access and credentials** - Complete the shared [managed prerequisites](/factories/self-hosting/#managed-prerequisites), then create an [Agent API key associated with the Default Service Account](/agents/cli/oz-cli/api-keys/#from-the-web-app-recommended). This key authenticates both the worker and the `oz agent run-cloud` command in this quickstart. A self-hosted worker key authenticates the worker only.
-* **A Linux machine with a rootful Docker daemon and GNU `stat`** - This quickstart does not cover macOS or Windows. On those hosts, follow the [Homebrew](/factories/self-hosting/managed-docker/#option-2-homebrew) or [release binary](/factories/self-hosting/managed-docker/#option-3-github-releases-binary) setup instead.
-* **The {VARS.WARP_AGENT_CLI}** - Install it on the machine that will route the test run. See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli).
+* Managed self-hosting access and network connectivity. See the [shared managed prerequisites](/factories/self-hosting/#managed-prerequisites).
+* An [Agent API key associated with the Default Service Account](/agents/cli/oz-cli/api-keys/#from-the-web-app-recommended).
+* A Linux machine with a rootful Docker daemon and GNU `stat`.
+* The {VARS.WARP_AGENT_CLI} on the machine that will route the test run. See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli).
+
+For macOS or Windows, use the [Homebrew](/factories/self-hosting/managed-docker/#option-2-homebrew) or [release binary](/factories/self-hosting/managed-docker/#option-3-github-releases-binary) setup instead.
---
@@ -30,7 +33,7 @@ _~10 minutes_
### 1. Export your API key
-Export the Agent API key so the worker container and the {VARS.WARP_AGENT_CLI} can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}:
+Use the Agent API key for both the worker container and `oz agent run-cloud`. A self-hosted worker key authenticates the worker only. Export the key so both tools can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}:
```bash
export WARP_API_KEY="YOUR_AGENT_API_KEY"
diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx
index e7e9356ab..592f84d4a 100644
--- a/src/content/docs/factories/troubleshooting.mdx
+++ b/src/content/docs/factories/troubleshooting.mdx
@@ -90,13 +90,13 @@ If a new matching event still doesn't reach the factory, [contact support](https
1. Check your [inbox](/factories/factory-inbox/) for a question, spec review, or PR review tied to the work item.
2. Open the item to see which agent is waiting and use **View agent** to open its session, where a question waiting on a human is visible and answerable.
-3. If the run is still active, you can steer it directly. See [cloud agent session sharing](/platform/viewing-cloud-agent-runs/).
+3. If the run is still active, you can steer it directly. See [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/).
### No pull request appears
**Cause:** The factory can't push, or the work never reached the implement agent.
-**Fix:** Confirm that the **Implement** agent is enabled on the factory, that the code host connection still grants write access to the target repository, and that the work item actually reached the Building stage. Branch protection rules apply to everything the factory pushes.
+**Fix:** Confirm that the **Implement** agent is enabled on the factory, that the code host connection still grants write access to the target repository, and that the work item actually reached the building stage. Branch protection rules apply to everything the factory pushes.
## Related pages
diff --git a/src/content/docs/factories/warp-hosting.mdx b/src/content/docs/factories/warp-hosting.mdx
index 8f79f0262..ae99f95c3 100644
--- a/src/content/docs/factories/warp-hosting.mdx
+++ b/src/content/docs/factories/warp-hosting.mdx
@@ -10,28 +10,29 @@ import { VARS } from '@data/vars';
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 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/).
+Use it when your factory's repositories and services are reachable from the public internet. Warp manages capacity and host maintenance. For private services or a network boundary that must contain checkout and execution, use [managed self-hosting](/factories/self-hosting/).
## Sandbox environment
-All Warp-hosted agents run in fully-isolated sandboxes. Warp uses a mix of infrastructure providers to ensure reliable sandbox startup.
+Warp-hosted agents run in isolated sandboxes. See [About factory infrastructure and security](/factories/infrastructure-and-security/) for execution, data, and credential boundaries.
-### OS and architecture
+## OS and architecture
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.
-Linux runners are compatible with any x86-64 image that includes a `bash` shell and core utilities like `ls` and `mkdir`. For Linux, macOS, and Windows platform options, see [factory runners](/factories/runners/#operating-systems).
-### Resources
+For supported operating systems, architectures, and Linux image requirements, see [runner platform options](/factories/runners/#operating-systems).
-The resources available to Warp-hosted agents depend on your [plan](https://www.warp.dev/pricing) - see the latest details there.
+## Resources
-On [Enterprise](/enterprise/) plans, resources are configurable up to 32 vCPUs and 64 GiB of memory. If additional resources are required, reach out to Warp support about custom provisioning.
+Available CPU and memory depend on your plan. See [Warp pricing](https://www.warp.dev/pricing) for plan information.
-### Concurrency
+On [Enterprise](/enterprise/) plans, resources are configurable up to 32 vCPUs and 64 GiB of memory. Contact Warp support about custom provisioning if you need more.
-To fairly allocate resources across all Warp users, concurrency of Warp-hosted agents is limited on a per-team basis. If an agent is started while at your concurrency limit, it is automatically queued and will start as soon as another agent completes.
+## Concurrency
-### Networking
+Warp limits concurrent hosted runs per team. Runs started at the limit are queued until another run completes.
+
+## Networking
Warp-hosted agents have network egress enabled by default. If you need to allowlist traffic from Warp agents, such as in a firewall policy, get Warp's IP address ranges from the "Warp-hosted agent networking" settings for your team. Find it on your team's **Platform** page in the [Admin Panel](https://app.warp.dev/admin/) or on User settings in the {VARS.FACTORY_WEB_APP}.
@@ -39,6 +40,6 @@ Warp-hosted agents have network egress enabled by default. If you need to allowl
## Related pages
-* [{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.
+* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) - Review shared cloud-agent capabilities
+* [Runners for Warp Factories](/factories/runners/) - Choose the operating system, architecture, and instance size
+* [Self-hosting overview](/factories/self-hosting/) - Run work on infrastructure you manage
diff --git a/src/content/docs/factories/webhooks.mdx b/src/content/docs/factories/webhooks.mdx
index 151c5d31a..8ec0a05c3 100644
--- a/src/content/docs/factories/webhooks.mdx
+++ b/src/content/docs/factories/webhooks.mdx
@@ -41,7 +41,7 @@ A URL token webhook's URL is itself the credential: treat it like a secret, and
### Prerequisites
-* **Permission to manage the factory** - Creating and editing webhooks changes the factory's configuration.
+* Permission to manage the factory's configuration.
### Create the webhook
diff --git a/src/content/docs/factories/webhooks/vercel.mdx b/src/content/docs/factories/webhooks/vercel.mdx
index 752dd447c..d40b19f59 100644
--- a/src/content/docs/factories/webhooks/vercel.mdx
+++ b/src/content/docs/factories/webhooks/vercel.mdx
@@ -10,12 +10,12 @@ import { VARS } from '@data/vars';
Vercel shows a webhook's signing secret only after you save its URL, and Warp has a URL only once the webhook exists. To break the loop, create the webhook without a secret: Warp creates it disabled, gives you the URL, and takes the secret in a second step. Stripe and PagerDuty issue their secrets the same way, so the same steps work for them with **Stripe** or **PagerDuty** as the provider scheme.
-Vercel team webhooks require a Vercel Pro or Enterprise plan.
-
## Prerequisites
-* **Permission to manage the factory** - Creating and editing webhooks changes the factory's configuration.
-* **The basics of custom webhooks** - Authentication modes, delivery rules, and how an automation subscribes to a webhook are covered in [Triggering automations with custom webhooks](/factories/webhooks/).
+* A Vercel Pro or Enterprise plan for team webhooks.
+* Permission to manage the factory's configuration.
+
+For authentication modes, delivery rules, and automation subscriptions, see [Triggering automations with custom webhooks](/factories/webhooks/).
## Creating the webhook in the factory dashboard
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 50dab8478..9d891744b 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
@@ -122,7 +122,7 @@ Add repo-specific context without forking the core skill by creating a `triage-i
## Next steps
* [Warp Factories overview](/factories/) — Warp's product for running this same loop without the manual wiring.
-* [Factory agents](/factories/factory-agents/#triage) — The Triage agent role, doing the same job as the agent you just built.
+* [About factory agents](/factories/factory-agents/#triage) — The Triage agent role, doing the same job as the agent you just built.
* [Factory skills](/factories/factory-skills/) — How Warp Factories scopes and shares a skill file like the one you just wrote.
* [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Add the spec role once your backlog is well-triaged.
* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Automate skill improvement based on your corrections.
diff --git a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx
index 509738e38..385108b10 100644
--- a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx
+++ b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx
@@ -164,7 +164,7 @@ The reviewer agent surfaces issues and inconsistencies; the human makes the fina
* [Warp Factories overview](/factories/) — Warp's product for running this same intake-to-review loop without the workflow wiring.
* [Automations](/factories/automations/) — Replaces the label-based state machine you just wired by hand.
-* [Factory agents](/factories/factory-agents/) — The same four roles — Triage, Spec, Implement, Review — as managed agents.
+* [About factory agents](/factories/factory-agents/) — The same four roles — Triage, Spec, Implement, Review — as managed agents.
* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop into a managed {VARS.WARP_AUTOMATION_PLATFORM} deployment.
* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop.
* [Review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code) — The human review workflow for agent-generated PRs.
diff --git a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx
index 8575b2edd..0bbe976f8 100644
--- a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx
+++ b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx
@@ -73,7 +73,7 @@ A tech spec defines how the feature will be implemented, including architecture
## Next steps
* [Warp Factories overview](/factories/) — Warp's product for running this same loop without the manual wiring.
-* [Factory agents](/factories/factory-agents/#spec) — The Spec agent role, gating implementation the same way.
+* [About factory agents](/factories/factory-agents/#spec) — The Spec agent role, gating implementation the same way.
* [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) — Connect the spec role to implementation and review.
* [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) — The full set of shared skills including `write-product-spec`, `write-tech-spec`, and `validate-changes-match-specs`.
* [Planning](/agents/capabilities/planning) — Warp's built-in planning feature for smaller tasks.
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index 7b1666c57..c811b2e1c 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -1,5 +1,5 @@
---
-title: Warp products and getting started
+title: Warp products overview
description: >-
Warp combines a modern terminal, coding agents, cloud automation, and
software factories for teams that build and ship software.
@@ -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 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 is an [open-source](https://github.com/warpdotdev/warp) **Agentic Development Environment**. With Warp, you can run commands in a desktop terminal, use the Warp Agent in a local checkout, and automate background work in the cloud. Teams can use Warp Factories to move work through triage, implementation, and review.
## Warp
@@ -31,14 +31,14 @@ The {VARS.WARP_AUTOMATION_PLATFORM} runs cloud agents from triggers, schedules,
## Warp Factories
-A factory is a team of cloud agents attached to a set of repositories. It takes work from Slack, GitHub, Linear, or Jira through triage, spec, implementation, and review, and returns the result, usually a pull request, where the work started.
+A factory is a team of cloud agents connected to your repositories. It routes work from Slack, GitHub, Linear, or Jira through triage, planning, implementation, and review. The output, usually a pull request, is returned to the thread or issue where the work started.
* [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.
## How the products work together
-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.
+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} so teams can route incoming work through repeatable workflows with specialized agents and review stages.
## Related pages
diff --git a/src/content/docs/platform/architecture.mdx b/src/content/docs/platform/architecture.mdx
index a34f3d4b4..867826036 100644
--- a/src/content/docs/platform/architecture.mdx
+++ b/src/content/docs/platform/architecture.mdx
@@ -115,4 +115,4 @@ Every run moves a few distinct classes of data, and each class has its own bound
* [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.
+* [About factory infrastructure and security](/factories/infrastructure-and-security/) - The same boundaries applied to factories.
diff --git a/src/content/docs/platform/handoff/local-to-cloud.mdx b/src/content/docs/platform/handoff/local-to-cloud.mdx
index a751c720e..02dc91ed6 100644
--- a/src/content/docs/platform/handoff/local-to-cloud.mdx
+++ b/src/content/docs/platform/handoff/local-to-cloud.mdx
@@ -37,7 +37,7 @@ If any changes fail to apply in the cloud run, the cloud agent reports which cha
* **An active local conversation** - Have a [Warp Agent](/agents/) conversation open in Warp with the work you want to hand off.
* **A configured environment** - The cloud agent needs an [environment](/platform/environments/) that includes the same repositories you're working in locally. The environment's repos must match your local checkout so the workspace snapshot applies cleanly.
* **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked. See [Cloud-synced conversations](/agents/local-agents/cloud-conversations/).
-* **Sufficient usage** - Cloud runs need an eligible balance for inference, hosted compute, and platform charges. See [cloud agent access and billing](/platform/team-access-billing-and-identity/).
+* **Usage balance** - Available usage for cloud runs. Add usage if needed. See [cloud agent access and billing](/platform/team-access-billing-and-identity/).
## Handing off a conversation to the cloud
diff --git a/src/content/docs/platform/harnesses/authentication.mdx b/src/content/docs/platform/harnesses/authentication.mdx
index d1475ae59..9a6f5e02e 100644
--- a/src/content/docs/platform/harnesses/authentication.mdx
+++ b/src/content/docs/platform/harnesses/authentication.mdx
@@ -10,7 +10,7 @@ import { VARS } from '@data/vars';
Third-party cloud agent authentication in the {VARS.WARP_AUTOMATION_PLATFORM} stores provider credentials for cloud runs as Warp-managed secrets. Third-party cloud agents, like [Claude Code](#connecting-claude-code-credentials) and [Codex](#connecting-codex-credentials), call their providers directly, so set up an Anthropic or OpenAI credential once before launching a third-party harness.
-Auth secrets can be scoped to a **team** (available to all teammates' runs) or **personal** (only your own runs), like any other Warp-managed secret. A [factory agent](/factories/factory-agents/#configuring-a-third-party-harness) can only select team-scoped secrets, since a factory's runs aren't tied to one person. Personal secrets remain available when you start an ad hoc cloud run.
+Auth secrets can be scoped to a **team** (available to all teammates' runs) or **personal** (only your own runs), like any other Warp-managed secret. A [factory agent](/factories/factory-agents/configuration/#configuring-a-third-party-harness) can only select team-scoped secrets, since a factory's runs aren't tied to one person. Personal secrets remain available when you start an ad hoc cloud run.
:::note
[Bring Your Own Key (BYOK)](/agents/inference/bring-your-own-api-key/) configured in the Warp desktop app applies to local agent runs only. Cloud runs of Claude Code and Codex always use Warp-managed secrets.
diff --git a/src/content/docs/platform/harnesses/claude-code.mdx b/src/content/docs/platform/harnesses/claude-code.mdx
index 5318745a6..60124c51b 100644
--- a/src/content/docs/platform/harnesses/claude-code.mdx
+++ b/src/content/docs/platform/harnesses/claude-code.mdx
@@ -56,4 +56,4 @@ For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/au
* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect Claude Code cloud runs in the Agent Management Panel and the Runs page
* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) - Codex as a cloud harness
* [Claude Code in Warp](/agents/cli-agents/claude-code/) - Claude Code in your local Warp terminal
-* [Factory agents](/factories/factory-agents/#configuring-a-third-party-harness) - Configure Claude Code as a factory agent's harness
+* [Factory agents](/factories/factory-agents/configuration/#configuring-a-third-party-harness) - Configure Claude Code as a factory agent's harness
diff --git a/src/content/docs/platform/harnesses/codex.mdx b/src/content/docs/platform/harnesses/codex.mdx
index eea2e3052..a13cc4230 100644
--- a/src/content/docs/platform/harnesses/codex.mdx
+++ b/src/content/docs/platform/harnesses/codex.mdx
@@ -56,4 +56,4 @@ For setup steps, see [Connecting Codex credentials](/platform/harnesses/authenti
* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect Codex cloud runs in the Agent Management Panel and the Runs page
* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) - Claude Code as a cloud harness
* [Codex CLI in Warp](/agents/cli-agents/codex/) - Codex in your local Warp terminal
-* [Factory agents](/factories/factory-agents/#configuring-a-third-party-harness) - Configure Codex as a factory agent's harness
+* [Factory agents](/factories/factory-agents/configuration/#configuring-a-third-party-harness) - Configure Codex as a factory agent's harness
diff --git a/src/content/docs/platform/integrations/github.mdx b/src/content/docs/platform/integrations/github.mdx
index 6ff576b45..47333184e 100644
--- a/src/content/docs/platform/integrations/github.mdx
+++ b/src/content/docs/platform/integrations/github.mdx
@@ -65,7 +65,8 @@ When a run for that thread is already in flight, a new mention is delivered to t
## Requirements
* **Team membership** - The GitHub integration requires a [Warp team](/knowledge-and-collaboration/teams/). Configuration is team-scoped, and runs are owned by the team associated with the GitHub App installation.
-* **Plan and usage** - Your team must have cloud agents enabled and sufficient eligible usage. Enterprise billing follows your contract. See [cloud agent access and billing](/platform/team-access-billing-and-identity/).
+* **Plan access** - A Warp team with cloud agents enabled and a plan that supports [integrations](/platform/team-access-billing-and-identity/#requirements-for-integrations).
+* **Usage balance** - Available usage for integration-triggered runs. Add usage if needed. Enterprise billing follows your contract. See [cloud agent billing](/platform/team-access-billing-and-identity/#billing-for-cloud-agent-runs).
* **Warp Factories GitHub App** - A GitHub organization owner installs the [Warp Factories](https://github.com/apps/warp-factories) GitHub App on the organization or account that owns the repositories, granting it access to all repositories or a selected set. The installation's repository access is what agents act with, so scope it deliberately.
* **An enabled GitHub organization** - A Warp team admin adds the organization under **Enabled GitHub Orgs** in the Admin Panel so the installation maps to your Warp team.
* **A connected GitHub account** - Each teammate connects their GitHub account to Warp once, so Warp can identify who triggered the run and which team to bill. The connection identifies the requester; it doesn't determine what the agent can reach on GitHub.
diff --git a/src/content/docs/platform/integrations/jira.mdx b/src/content/docs/platform/integrations/jira.mdx
index 05d75ac62..ce7ae3e35 100644
--- a/src/content/docs/platform/integrations/jira.mdx
+++ b/src/content/docs/platform/integrations/jira.mdx
@@ -15,7 +15,8 @@ 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 usage** - Review [integration access](/platform/team-access-billing-and-identity/#requirements-for-integrations) and [eligible usage balances](/platform/team-access-billing-and-identity/#usage-requirements) before starting a run.
+* **Plan access** - A team plan that supports [integrations](/platform/team-access-billing-and-identity/#requirements-for-integrations).
+* **Usage balance** - Available usage for integration-triggered runs. Add usage if needed. See [cloud agent billing](/platform/team-access-billing-and-identity/#billing-for-cloud-agent-runs).
* **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 1740eeb7c..897482be6 100644
--- a/src/content/docs/platform/integrations/linear.mdx
+++ b/src/content/docs/platform/integrations/linear.mdx
@@ -69,7 +69,8 @@ Because PRs are created as _you_, this makes code review, auditing, and team col
### Requirements
* **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 usage** - Review [integration access](/platform/team-access-billing-and-identity/#requirements-for-integrations) and [eligible usage balances](/platform/team-access-billing-and-identity/#usage-requirements) before starting a run.
+* **Plan access** - A team plan that supports [integrations](/platform/team-access-billing-and-identity/#requirements-for-integrations).
+* **Usage balance** - Available usage for integration-triggered runs. Add usage if needed. See [cloud agent billing](/platform/team-access-billing-and-identity/#billing-for-cloud-agent-runs).
* **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.
diff --git a/src/content/docs/platform/integrations/quickstart.mdx b/src/content/docs/platform/integrations/quickstart.mdx
index 274471120..830a01caf 100644
--- a/src/content/docs/platform/integrations/quickstart.mdx
+++ b/src/content/docs/platform/integrations/quickstart.mdx
@@ -18,8 +18,9 @@ import { VARS } from '@data/vars';
## Prerequisites
-* **Eligible team** - Slack requires a Warp team with cloud agents enabled and sufficient eligible usage. See [cloud agent access and billing](/platform/team-access-billing-and-identity/).
-* **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one yet, follow the [Cloud Agents Quickstart](/platform/quickstart/) or run `/create-environment` in Warp.
+* **A Warp team** - Membership in a [Warp team](/knowledge-and-collaboration/teams/) with cloud agents enabled and a plan that supports [integrations](/platform/team-access-billing-and-identity/#requirements-for-integrations).
+* **Usage balance** - Available usage for integration-triggered runs. Add usage if needed. See [cloud agent billing](/platform/team-access-billing-and-identity/#billing-for-cloud-agent-runs).
+* **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one yet, follow the [Cloud agents quickstart](/platform/quickstart/) or run `/create-environment` in Warp.
* **GitHub authorization** - Warp needs access to your repos to clone code and open PRs. You'll be prompted to authorize the Warp GitHub app when you first create the integration.
---
diff --git a/src/content/docs/platform/integrations/slack.mdx b/src/content/docs/platform/integrations/slack.mdx
index a08e15b3d..eab12256d 100644
--- a/src/content/docs/platform/integrations/slack.mdx
+++ b/src/content/docs/platform/integrations/slack.mdx
@@ -30,7 +30,8 @@ The CLI opens a browser window to install the Warp app into your Slack workspace
#### Requirements
* **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 usage** - Review [integration access](/platform/team-access-billing-and-identity/#requirements-for-integrations) and [eligible usage balances](/platform/team-access-billing-and-identity/#usage-requirements) before starting a run.
+* **Plan access** - A team plan that supports [integrations](/platform/team-access-billing-and-identity/#requirements-for-integrations).
+* **Usage balance** - Available usage for integration-triggered runs. Add usage if needed. See [cloud agent billing](/platform/team-access-billing-and-identity/#billing-for-cloud-agent-runs).
* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/factories/self-hosting/) on their own infrastructure.
---
diff --git a/src/content/docs/platform/orchestration/index.mdx b/src/content/docs/platform/orchestration/index.mdx
index 2169e4983..068c2b2f5 100644
--- a/src/content/docs/platform/orchestration/index.mdx
+++ b/src/content/docs/platform/orchestration/index.mdx
@@ -43,7 +43,7 @@ An ad hoc child's prompt comes from the parent at spawn time. The model, harness
Use a [skill](/agents/capabilities/skills/) for reusable instructions. A local child discovers the project and home-directory skills in scope from its working directory. For cloud children, the parent attaches skills from a repository in the [environment](/platform/environments/).
-For named agents with standing configuration, use [Warp Factories](/factories/). A factory's foreman can dispatch its [factory agents](/factories/factory-agents/#choose-a-configured-factory-agent).
+For named agents with standing configuration, use [Warp Factories](/factories/). A factory's foreman can dispatch its [factory agents](/factories/factory-agents/creating-custom-agents/#dispatch-a-configured-agent).
## Run state transitions
diff --git a/src/content/docs/platform/quickstart.mdx b/src/content/docs/platform/quickstart.mdx
index bd9cf34f2..413f99f8e 100644
--- a/src/content/docs/platform/quickstart.mdx
+++ b/src/content/docs/platform/quickstart.mdx
@@ -12,10 +12,9 @@ To run a cloud-agent task from Warp, you'll set up an environment if needed, sen
## Prerequisites
-* **Warp app** - Download from the [Warp download page](https://www.warp.dev/download).
-* **Warp account** - Create an account through the [Warp sign-up page](https://app.warp.dev/signup).
-
-Before starting, check your account's or team's [access and billing requirements](/platform/team-access-billing-and-identity/).
+* The [Warp app](https://www.warp.dev/download) installed on your computer.
+* A [Warp account](https://app.warp.dev/signup) with [cloud agent access](/platform/team-access-billing-and-identity/).
+* Available usage for cloud runs. Add usage if needed. See [access and billing requirements](/platform/team-access-billing-and-identity/#usage-requirements).
---
diff --git a/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx b/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx
index 08d0b8aec..71834ef73 100644
--- a/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx
+++ b/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx
@@ -18,8 +18,9 @@ Watch this short demo of creating and testing a scheduled agent:
## Prerequisites
-* **A Warp account** - Your account needs cloud agent access on an eligible plan. Check [usage requirements](/platform/team-access-billing-and-identity/#usage-requirements) before starting a run.
-* **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one, follow the [Cloud Agents Quickstart](/platform/quickstart/) to create one first.
+* **A Warp account** - An account with [cloud agent access](/platform/team-access-billing-and-identity/).
+* **Usage balance** - Available usage for the [user or team billed for the schedule](/platform/team-access-billing-and-identity/#billing-for-cloud-agent-runs). Add usage if needed. See [run identity](#run-identity-and-pull-request-authorship) before choosing which agent runs it.
+* **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one, follow the [Cloud agents quickstart](/platform/quickstart/) to create one first.
---
@@ -70,6 +71,6 @@ Runs are also accessible from the conversation panel view in the Warp app and on
## Next steps
* **Choose the right unattended trigger** - Compare schedules, Slack, Linear, GitHub Actions, CLI, and API workflows in [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/).
-* **Trigger agents from your tools** - Connect the {VARS.WARP_AUTOMATION_PLATFORM} to Slack or Linear to trigger agents from mentions or issue updates. See [Integrations Quickstart](/platform/integrations/quickstart/).
+* **Trigger agents from your tools** - Connect the {VARS.WARP_AUTOMATION_PLATFORM} to Slack or Linear to trigger agents from mentions or issue updates. See [Integrations quickstart](/platform/integrations/quickstart/).
* **Manage and refine your schedule** - Change the frequency, swap skills, or pause and resume the schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/) for the full reference.
* **Share with your team** - Schedules and environments are shared across your Warp team, so everyone benefits automatically.
diff --git a/src/content/docs/quickstart.mdx b/src/content/docs/quickstart.mdx
index 980e0bc65..1a30833b8 100644
--- a/src/content/docs/quickstart.mdx
+++ b/src/content/docs/quickstart.mdx
@@ -12,7 +12,7 @@ Get up and running with Warp in about 10 minutes. Install the app, run your firs
## Prerequisites
-* **macOS, Windows, or Linux** - See [Installation and setup](/getting-started/quickstart/installation-and-setup/) for minimum requirements per platform.
+* A macOS, Windows, or Linux computer that meets the [minimum system requirements](/getting-started/quickstart/installation-and-setup/).
---
diff --git a/src/sidebar.ts b/src/sidebar.ts
index d6ff5b157..faf3694c1 100644
--- a/src/sidebar.ts
+++ b/src/sidebar.ts
@@ -410,7 +410,14 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
// and where it runs.
label: 'Factory configuration',
items: [
- { slug: 'factories/factory-agents', label: 'Factory agents' },
+ {
+ label: 'Factory agents',
+ items: [
+ { slug: 'factories/factory-agents', label: 'About factory agents' },
+ { slug: 'factories/factory-agents/configuration', label: 'Configuring factory agents' },
+ { slug: 'factories/factory-agents/creating-custom-agents', label: 'Creating custom agents' },
+ ],
+ },
{ slug: 'factories/factory-skills', label: 'Factory skills' },
// Moved from 'Integrations' (was 'Automation filters'): this page is
// now the Automations primitive's conceptual home, parallel to Factory
@@ -420,7 +427,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
{
label: 'Infrastructure',
items: [
- { slug: 'factories/infrastructure-and-security', label: 'Overview' },
+ { slug: 'factories/infrastructure-and-security', label: 'About infrastructure and security' },
{ slug: 'factories/deployment-patterns', label: 'Deployment patterns' },
{ slug: 'factories/warp-hosting', label: 'Warp-hosted execution' },
{ slug: 'factories/runners', label: 'Runners' },