From b1b3e88afdd5180d5c8cbfe26eb840203ec932ba Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 6 Oct 2026 23:46:07 +0000 Subject: [PATCH] docs: audit and polish the Warp Factories docs Correct product claims that drifted from warp-server (built-in factory skills, default agent models, default Scorers, the Factory MCP tool list, work-source lists, hosted image support), give duplicated content one canonical home, and make the section read consistently: every page ends with Related pages, list links share one style, integration page titles use the gerund form, and definition-location terms, agent names, and link text match across pages. Co-Authored-By: Warp --- .../demo-sentry-monitoring-with-sdk.mdx | 28 ++-- .../docs/factories/api-and-sdk/index.mdx | 113 ++++++-------- .../docs/factories/api-and-sdk/quickstart.mdx | 47 +++--- src/content/docs/factories/automations.mdx | 18 +-- src/content/docs/factories/benchmarks.mdx | 15 +- .../code-forges/other-code-forges.mdx | 4 +- .../docs/factories/connect-your-factory.mdx | 13 +- .../docs/factories/deployment-patterns.mdx | 8 +- .../docs/factories/developer-tools.mdx | 16 +- src/content/docs/factories/factory-agents.mdx | 42 +++--- src/content/docs/factories/factory-api.mdx | 32 ++-- .../docs/factories/factory-as-code.mdx | 10 +- .../docs/factories/factory-dashboard.mdx | 36 ++--- src/content/docs/factories/factory-inbox.mdx | 14 +- src/content/docs/factories/factory-mcp.mdx | 24 +-- src/content/docs/factories/factory-skills.mdx | 99 +++++-------- .../factories/infrastructure-and-security.mdx | 29 ++-- .../docs/factories/integrations/github.mdx | 10 +- .../docs/factories/integrations/gitlab.mdx | 11 +- .../docs/factories/integrations/jira.mdx | 11 +- .../docs/factories/integrations/linear.mdx | 11 +- .../docs/factories/integrations/slack.mdx | 31 ++-- .../docs/factories/integrations/teams.mdx | 16 +- .../docs/factories/measure-and-improve.mdx | 18 +-- .../factories/measure-and-improve/scorers.mdx | 11 +- .../measure-and-improve/self-improvement.mdx | 2 +- src/content/docs/factories/quickstart.mdx | 13 +- src/content/docs/factories/runners.mdx | 44 +++--- .../docs/factories/self-hosting/index.mdx | 10 +- .../factories/self-hosting/managed-direct.mdx | 38 ++--- .../factories/self-hosting/managed-docker.mdx | 34 ++--- .../self-hosting/managed-kubernetes.mdx | 118 ++++++--------- .../factories/self-hosting/monitoring.mdx | 82 +++++----- .../private-container-registry.mdx | 8 +- .../factories/self-hosting/quickstart.mdx | 18 +-- .../docs/factories/self-hosting/reference.mdx | 140 ++++++++---------- .../self-hosting/troubleshooting.mdx | 22 +-- .../docs/factories/troubleshooting.mdx | 12 +- src/content/docs/factories/warp-hosting.mdx | 13 +- src/content/docs/factories/webhooks.mdx | 14 +- .../docs/factories/webhooks/vercel.mdx | 8 +- .../docs/platform/orchestration/index.mdx | 2 +- src/sidebar.ts | 2 +- 43 files changed, 561 insertions(+), 686 deletions(-) diff --git a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index b45b694f7..00e390e11 100644 --- a/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -8,24 +8,26 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -### Turn production errors into draft PRs with Cloud Agents + TypeScript SDK +Turn production errors into draft pull requests with cloud agents and the TypeScript SDK. In this demo, Ben builds a small TypeScript "Sentry monitor" service that listens for specific Sentry alerts (like a Go nil pointer dereference) and starts a Warp cloud agent to investigate. The server validates the webhook, extracts the stack trace, and passes it to an agent run inside a Warp environment so the agent can inspect the repo and propose a fix. -:::note -Example repository: [**Sentry monitor example repository**](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor) -::: +The code is in the [Sentry monitor example repository](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor). -In this demo, Ben builds a small TypeScript “Sentry monitor” service that listens for specific Sentry alerts (like a Go nil pointer dereference) and triggers a Warp cloud agent to investigate. The server validates the webhook, extracts the stack trace, and injects it into an agent run inside a Warp Environment so the agent can inspect the repo and propose a fix. +To route the alert through a factory's named agents and workflow instead, dispatch the request with [factory endpoints](/factories/factory-api/). This example is still the pattern for custom standalone cloud-agent intake. -To route the alert through a factory's named agents and workflow instead, use [factory endpoints](/factories/factory-api/) to dispatch the request. This example remains useful for custom standalone cloud-agent intake. +The demo also covers the run lifecycle basics in the TypeScript SDK (running an agent, then polling run state to fetch a session link for debugging) and shows the end result: a draft GitHub pull request created from the Sentry event for a maintainer to review. -He also covers the task lifecycle basics in the TypeScript SDK (running an agent, polling task state to fetch a session link for debugging), and shows the end result: a draft GitHub pull request created from the Sentry event for a maintainer to review. +## What the demo covers -**What Ben covers** - -* Using Warp's TypeScript SDK to trigger agent runs and retrieve run details. -* Handling run lifecycle states (queued → running) to reliably fetch a session link. -* Running agents inside a Warp Environment so they can investigate real code, run tests, and validate fixes. +* Using Warp's TypeScript SDK to start agent runs and retrieve run details. +* Handling run lifecycle states, from queued to running, to reliably fetch a session link. +* Running agents inside a Warp environment so they can investigate real code, run tests, and validate fixes. * Building a lightweight Sentry webhook server that filters, validates, and routes only the right errors to an agent. -* Creating a workflow that results in draft PRs for human review, instead of silent autonomous changes. +* Creating a workflow that results in draft PRs for human review instead of silent autonomous changes. + +## Related pages + +* [Agent and run endpoints](/factories/api-and-sdk/) - The endpoints and SDKs the demo builds on. +* [{VARS.WARP_PLATFORM_API} quickstart](/factories/api-and-sdk/quickstart/) - Create and inspect your first run. +* [Triggering automations with custom webhooks](/factories/webhooks/) - Route Sentry and other webhook deliveries into a factory without writing a server. diff --git a/src/content/docs/factories/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx index 49e560679..007c60c0d 100644 --- a/src/content/docs/factories/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -10,47 +10,33 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Agent & run endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to start standalone cloud agent runs and to monitor, continue, or cancel any run after it starts. To find a factory and send it new work, use [factory endpoints](/factories/factory-api/). +The agent and run endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to start standalone cloud agent runs and to monitor, continue, or cancel any run after it starts. To find a factory and send it new work, use [factory endpoints](/factories/factory-api/). -:::note -Some examples use `oz` commands, such as `oz environment list`, from the {VARS.WARP_AGENT_CLI}. Existing commands remain supported during the transition. -::: +## Use the agent and run endpoints -## Use Agent & run endpoints +The agent and run endpoints let you create and inspect [cloud agent](/platform/) runs over HTTP from CI, cron, backend services, and internal tools, without the Warp desktop app. With the API you can: -Agent & run endpoints let you create and inspect [cloud agent](/platform/) runs over HTTP from CI, cron, backend services, and internal tools, without requiring the Warp desktop app. +* Run an agent by submitting a prompt plus optional configuration, such as the model, environment, MCP servers, and base prompt. +* Monitor execution by listing runs and tracking state transitions over time, from queued through in progress to succeeded or failed. +* Inspect results and provenance by fetching a run's full details, including the original prompt, source and creator metadata, session link, and resolved agent configuration. -**With the API you can:** +For endpoint details, use the [{VARS.WARP_PLATFORM_API} reference](/api). For SDK schemas, use the [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) repositories. -* Run an agent by submitting a prompt plus optional config (model, environment, MCP servers, base prompt, etc.) -* Monitor execution by listing runs and tracking state transitions over time (queued → in progress → succeeded/failed) -* Inspect results and provenance by fetching a run's full details, including the original prompt, source/creator metadata, session link, and resolved agent configuration - -For endpoint details, use the [**{VARS.WARP_PLATFORM_API} reference**](/api). For SDK schemas, use the [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) repositories. - -To send work to a [Warp factory](/factories/), use [factory endpoints](/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/runs` with a foreman's `agent_identity_uid`. The follow-up, cancellation, and status endpoints still apply after a factory run is dispatched. +To send work to a [factory](/factories/), use [factory endpoints](/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/runs` with a foreman's `agent_identity_uid`. The follow-up, cancellation, and status endpoints still apply after a factory run is dispatched. ## Choose the SDK or raw REST Warp provides the official [`warp-platform-sdk` Python package](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` TypeScript package](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk). Both SDKs wrap the {VARS.WARP_PLATFORM_API} with: -* **Typed requests and responses** (editor autocomplete, fewer schema mistakes) -* **Built-in retries and timeouts** (with per-request overrides) -* [**Consistent error types**](/factories/api-and-sdk/troubleshooting/errors/) that map to API status codes -* **Helpers for raw responses** when you need headers/status or custom parsing +* **Typed requests and responses** - Editor autocomplete and fewer schema mistakes. +* **Built-in retries and timeouts** - With per-request overrides. +* **Consistent error types** - [Errors](/factories/api-and-sdk/troubleshooting/errors/) that map to API status codes. +* **Helpers for raw responses** - For when you need headers, the status code, or custom parsing. -If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. +Use the SDK for strong typing, standardized error handling, and concurrency patterns. Use raw REST for minimal dependencies or full control over your HTTP client; the SDKs can also call undocumented endpoints when needed. -**SDK vs raw REST** - -* Use the SDK when you want strong typing, standardized error handling, and easy concurrency patterns. -* Use raw REST when you want minimal dependencies or full control over your HTTP client (the SDKs also support calling undocumented endpoints when needed). - - ---- - ## API base URL All endpoints are served over HTTPS: @@ -71,21 +57,21 @@ An agent run represents a single execution of a cloud agent, created with a prom * Optional session information (`session_id`, `session_link`) * Optional resolved configuration (`agent_config`) -See the [**{VARS.WARP_PLATFORM_API} reference**](/api) for details on how runs are created and listed. +See the [{VARS.WARP_PLATFORM_API} reference](/api) for details on how runs are created and listed. ### Agent configuration -You can influence how an agent runs using AmbientAgentConfig, including: +The request's `AmbientAgentConfig` object shapes how an agent runs: -* `name` — a human-readable label for grouping, filtering, and traceability. When you run an agent from a [skill](/agents/capabilities/skills/), `name` is automatically set to the skill name. You can also set `name` explicitly via the API, SDK, or CLI (`--name`) to categorize runs by intent — for example, grouping all runs of a particular workflow regardless of how they were triggered. Use the `name` query parameter on `GET /agent/runs` to filter runs by config name. -* `model_id` for LLM selection -* `base_prompt` to shape behavior -* `environment_id` to choose a `CloudEnvironment` -* `worker_host` to run a standalone cloud agent on a [self-hosted worker](/factories/self-hosting/) -* `skill_spec` to use a [skill](/agents/capabilities/skills/) as the base prompt (format: `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md`) -* `mcp_servers` to enable specific tools via MCP +* `name` - A human-readable label for grouping, filtering, and traceability. When you run an agent from a [skill](/agents/capabilities/skills/), `name` is set to the skill name. You can also set `name` explicitly via the API, SDK, or CLI (`--name`) to categorize runs by intent, such as grouping all runs of a particular workflow regardless of how they were triggered. Use the `name` query parameter on `GET /agent/runs` to filter runs by config name. +* `model_id` - The model to run. +* `base_prompt` - Instructions that shape the agent's behavior. +* `environment_id` - The `CloudEnvironment` to run in. +* `worker_host` - A [self-hosted worker](/factories/self-hosting/) to run a standalone cloud agent on. +* `skill_spec` - A [skill](/agents/capabilities/skills/) to use as the base prompt, in `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md` form. +* `mcp_servers` - MCP servers whose tools the agent can use. -See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript) for the full configuration schema. +See the [Python SDK](https://github.com/warpdotdev/oz-sdk-python) or [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) for the full configuration schema. #### Skill actions in conversation data @@ -114,8 +100,6 @@ The catalog helps group usage across conversations; it isn't an availability man For example, `oz-platform`, `factory-files`, and `factory-mcp` are Warp-provided. `factory-mcp` appears only where Factory MCP is available, `tui-migrate-setup` is specific to the Warp Agent CLI, and connected integrations can add bundled IDs that aren't listed here. ---- - ## Route a run to a self-hosted worker Set `worker_host` in the request configuration to select a connected self-hosted worker. Omit it, or set it to `warp`, to use Warp-hosted workers. @@ -133,28 +117,14 @@ Replace `WORKER_HOST` with the ID of a connected worker. For factory work, set ` ## Key endpoints -Agent & run endpoints include: - -* `POST /agent/runs` - - Create a new agent run with a prompt and optional config and title. Returns run\_id and initial state. -* `GET /agent/runs` - - List runs with pagination and filters for state, config\_name, model\_id, creator, source, and creation time. -* `GET /agent/runs/{runId}` - - Fetch full details for a single run, including session link and resolved configuration. -* `POST /agent/runs/{runId}/followups` - - Send a follow-up message to an existing run to steer or continue it, the same capability the Slack and Linear integrations use. -* `POST /agent/runs/{runId}/cancel` - - Cancel a run that is currently queued or in progress. Returns the ID of the cancelled run. +* `POST /agent/runs` - Create a new agent run with a prompt and optional config and title. Returns the `run_id` and initial state. +* `GET /agent/runs` - List runs with pagination and filters for state, `config_name`, `model_id`, creator, source, and creation time. +* `GET /agent/runs/{runId}` - Fetch full details for a single run, including the session link and resolved configuration. +* `POST /agent/runs/{runId}/followups` - Send a follow-up message to an existing run to steer or continue it, the same capability the Slack and Linear integrations use. +* `POST /agent/runs/{runId}/cancel` - Cancel a run that is queued or in progress. Returns the ID of the cancelled run. All endpoint semantics, query parameters, and [error codes](/factories/api-and-sdk/troubleshooting/errors/) are documented in the [{VARS.WARP_PLATFORM_API} reference](/api). ---- - ## Models The API shares a set of reusable models across endpoints. Detailed JSON schemas, types, and enums are available in the SDK repos ([Python](https://github.com/warpdotdev/oz-sdk-python), [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript)). Key models include: @@ -173,17 +143,15 @@ The API shares a set of reusable models across endpoints. Detailed JSON schemas, * `MCPServerConfig` * `Error` ---- - ## SDKs ### Python SDK The Python SDK is the recommended way to call the API from Python services and scripts. It provides: -* Sync + async clients -* Typed request/response models -* Configurable retries/timeouts and structured errors +* Sync and async clients +* Typed request and response models +* Configurable retries and timeouts, and structured errors Install the package from PyPI: @@ -191,15 +159,15 @@ Install the package from PyPI: pip install warp-platform-sdk ``` -Import `WarpClient` from `warp_platform_sdk`. See the [**Python SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-python) for the full API reference and up-to-date examples. +Import `WarpClient` from `warp_platform_sdk`. See the [Python SDK GitHub repo](https://github.com/warpdotdev/oz-sdk-python) for the full API reference and up-to-date examples. ### TypeScript SDK -The TypeScript SDK is the recommended way to call the API from Node.js services and modern TS/JS runtimes. It provides: +The TypeScript SDK is the recommended way to call the API from Node.js services and modern TypeScript and JavaScript runtimes. It provides: -* Fully typed params/responses -* First-class error handling, retries/timeouts -* Support across common runtimes where fetch is available or polyfilled +* Fully typed params and responses +* First-class error handling, retries, and timeouts +* Support across common runtimes where `fetch` is available or polyfilled Install the package from npm: @@ -207,4 +175,11 @@ Install the package from npm: npm install @warp-dot-dev/warp-platform-sdk ``` -Import `WarpClient` from `@warp-dot-dev/warp-platform-sdk`. See the [**TypeScript SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-typescript) for the full API reference and up-to-date examples. +Import `WarpClient` from `@warp-dot-dev/warp-platform-sdk`. See the [TypeScript SDK GitHub repo](https://github.com/warpdotdev/oz-sdk-typescript) for the full API reference and up-to-date examples. + +## Related pages + +* [Factory endpoints](/factories/factory-api/) - Find a factory and send it work by UID. +* [{VARS.WARP_PLATFORM_API} quickstart](/factories/api-and-sdk/quickstart/) - Create and inspect your first run. +* [API errors](/factories/api-and-sdk/troubleshooting/errors/) - Every error code, its HTTP status, and how to resolve it. +* [Multi-agent orchestration](/platform/orchestration/) - Coordinate parent and child runs through the same API. diff --git a/src/content/docs/factories/api-and-sdk/quickstart.mdx b/src/content/docs/factories/api-and-sdk/quickstart.mdx index cf8d579b2..4d39e0e65 100644 --- a/src/content/docs/factories/api-and-sdk/quickstart.mdx +++ b/src/content/docs/factories/api-and-sdk/quickstart.mdx @@ -2,39 +2,36 @@ topic: factories title: "{{WARP_PLATFORM_API}} quickstart" description: >- - Create and monitor your first cloud agent run via the {{WARP_PLATFORM_API}} in ~5 - minutes. + Create and monitor your first cloud agent run with the {{WARP_PLATFORM_API}} in + about five minutes. sidebar: label: "Quickstart" --- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -The {VARS.WARP_PLATFORM_API} lets you run and manage cloud agents from CI/CD pipelines, backend services, scripts, or custom tooling without the Warp desktop app. This quickstart walks you through creating your first run and checking its status. +Create your first cloud agent run with the {VARS.WARP_PLATFORM_API} and check its status, in about five minutes. The API runs and manages cloud agents from CI pipelines, backend services, scripts, or custom tooling without the Warp desktop app. To dispatch work through a factory's named agents and workflow, use [factory endpoints](/factories/factory-api/) after this quickstart. The run-management steps below also apply to the factory run those endpoints create. -Watch this short demo of how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team: - +This short demo shows how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team. ---- + ## 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. ---- - ## 1. Set your API key -Export your API key so the API can authenticate your requests automatically — all commands in this guide reference the `WARP_API_KEY` environment variable. +Export your API key so every command in this quickstart can authenticate through the `WARP_API_KEY` environment variable. ```bash -export WARP_API_KEY="wk-..." +export WARP_API_KEY="YOUR_API_KEY" ``` -Replace `wk-...` with the key you created earlier. +Replace `YOUR_API_KEY` with the key you created earlier. Keys start with `wk-`. ## 2. Create your first run @@ -47,25 +44,25 @@ curl -X POST https://app.warp.dev/api/v1/agent/runs \ -d '{ "prompt": "Scan the repo for outdated dependencies and summarize the findings.", "config": { - "environment_id": "" + "environment_id": "ENV_ID" } }' ``` -Replace `` with your environment ID. Find it with `oz environment list` on the {VARS.WARP_AGENT_CLI} or in the {VARS.WEB_APP}. +Replace `ENV_ID` with your environment ID. Find it with `oz environment list` on the {VARS.WARP_AGENT_CLI} or in the {VARS.WEB_APP}. :::note -Prefer typed requests? The official [`warp-platform-sdk` Python package](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` TypeScript package](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) wrap the same API with typed models, retries, and error handling. +The official [`warp-platform-sdk` Python package](https://pypi.org/project/warp-platform-sdk/) and [`@warp-dot-dev/warp-platform-sdk` TypeScript package](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) wrap the same API with typed models, retries, and error handling. ::: -The API returns a `run_id` immediately. The agent starts asynchronously — you can check its status at any time using the run ID. +The API returns a `run_id` immediately. The agent starts asynchronously, and you can check its status at any time with the run ID. ## 3. Check run status -Fetch the current state of the run with the following command. Replace `` with the `run_id` from step 2. +Fetch the current state of the run. Replace `RUN_ID` with the `run_id` from step 2. ```bash -curl "https://app.warp.dev/api/v1/agent/runs/" \ +curl "https://app.warp.dev/api/v1/agent/runs/RUN_ID" \ -H "Authorization: Bearer $WARP_API_KEY" ``` @@ -76,7 +73,7 @@ The `state` has the following possible values: * `SUCCEEDED` - The run completed successfully. * `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/factories/api-and-sdk/troubleshooting/errors/) to interpret the error code. -These are the most common states. See the [Agent & run endpoints](/factories/api-and-sdk/) and [{VARS.WARP_PLATFORM_API} reference](/api) for all possible values. +These are the most common states. See the [agent and run endpoints](/factories/api-and-sdk/) and the [{VARS.WARP_PLATFORM_API} reference](/api) for all possible values. To list all recent runs: @@ -87,15 +84,15 @@ curl "https://app.warp.dev/api/v1/agent/runs" \ ## 4. View the results -Once the run reaches `SUCCEEDED`, the response includes a `session_link` — a direct URL to the full run transcript, including commands executed, files changed, and agent output. +Once the run reaches `SUCCEEDED`, the response includes a `session_link`, a direct URL to the full run transcript, including commands executed, files changed, and agent output. You can also view and manage all runs in the {VARS.DASHBOARD}. ---- - ## Next steps -* **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 [Scheduled Agents Quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or [Integrations Quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear. +You created a run from the command line and read its state and transcript back. + +* [Agent and run endpoints](/factories/api-and-sdk/) - The configuration options and run lifecycle, with the [{VARS.WARP_PLATFORM_API} reference](/api) for every parameter, query filter, and response schema. +* [`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) - Typed request and response models, retries, and error handling. +* [Sentry monitoring demo](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) - A webhook handler that starts agents from production errors. +* [Scheduled agents quickstart](/platform/triggers/scheduled-agents-quickstart/) and [integrations quickstart](/platform/integrations/quickstart/) - Run agents on a schedule, or start them from Slack or Linear. diff --git a/src/content/docs/factories/automations.mdx b/src/content/docs/factories/automations.mdx index 15ac6b495..341b6ef3a 100644 --- a/src/content/docs/factories/automations.mdx +++ b/src/content/docs/factories/automations.mdx @@ -7,9 +7,7 @@ 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. A trigger is a schedule or an event from a connected tool or [custom webhook](/factories/webhooks/), and each trigger carries filters, such as a repository, channel, team, project, label, author, or webhook payload field. An event starts a run only when it matches every filter, so a factory can watch busy channels and repositories without acting on everything in them. The default automations Warp creates when you connect a tool and the custom ones you add are the same resource. See [`automations//automation.md`](/factories/factory-as-code/#automationsnameautomationmd) for the full schema. ## How matching works @@ -23,7 +21,7 @@ One event can match more than one automation, and each match starts its own run. ## 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 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 Azure DevOps factory identity's repository permissions, 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 are still your main control over who starts runs. On GitHub and GitLab, the event author doesn't need to be a Warp team member, so use author, member, and branch filters to decide whose activity starts work. 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. @@ -124,8 +122,6 @@ triggers: 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). - ## 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. @@ -143,9 +139,9 @@ 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. +* [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. +* [Custom webhooks](/factories/webhooks/) - Start automations from any system that can POST JSON, with the setup flow and authentication modes. +* [Factory definition syntax](/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. diff --git a/src/content/docs/factories/benchmarks.mdx b/src/content/docs/factories/benchmarks.mdx index a4a38980b..1b40b1343 100644 --- a/src/content/docs/factories/benchmarks.mdx +++ b/src/content/docs/factories/benchmarks.mdx @@ -1,8 +1,8 @@ --- title: Factory benchmarks description: >- - Warp Factories benchmarks compare agent model and runner configurations on - fixed tasks so you can choose a production configuration. + Warp Factories benchmarks compare agent model, harness, and runner + configurations on fixed tasks so you can choose a production configuration. sidebar: label: "Benchmarks" --- @@ -10,7 +10,9 @@ import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; Warp Factories benchmarks compare model, harness, and runner configurations for one factory agent on the same fixed tasks. Use a benchmark to test a change on representative work before you apply it to your factory. + This video shows how to compare benchmark results for quality and cost before changing a coding agent's configuration. + ## How benchmarks work @@ -36,13 +38,16 @@ Use separate suites for focused questions: To use Benchmarks, you need a factory with an agent to evaluate. Use a completed run from that agent when you want a task to reproduce real work, or write a task yourself. This video shows how to turn your team's coding tasks into a reusable benchmark suite. + + 1. In the {VARS.FACTORY_WEB_APP}, open your factory, click **Benchmarks**, then click **New**.
![The Benchmarks page showing saved benchmark suites, a search field, and the New button.](../../../assets/factories/factory-benchmarks-list.png)
The Benchmarks page for a factory.
+ 2. Enter a name and optional description, then choose the agent to evaluate. The suite runs every task as that agent.
@@ -57,19 +62,22 @@ This video shows how to turn your team's coding tasks into a reusable benchmark ![The Add task pane with a run search field, the list of completed runs, and the Start from scratch instead option.](../../../assets/factories/benchmark-task-source-run.png)
The task source picker.
+ 5. Review the task prompt and enter "Correctness criteria" for the task.
![The task editor with fields for a title, prompt, correctness criteria, and pinned repositories.](../../../assets/factories/benchmark-task-editor.png)
The task editor for a benchmark suite.
+ 6. Click **Run**. In the launch dialog, choose the harness and model, or an authorized custom factory router, and the runner for each configuration. 7. Add configurations, select Scorers, and set "Repetitions." The dialog shows the number of trials created. More trials and Scorers increase the run's cost. 8. Click **Run benchmark**. The benchmark page shows its status and scored trials. You can cancel a running or scoring benchmark. ## Review benchmark results -After the run completes, review the result as a comparison, not as a universal model ranking: +After the run completes, review the result as a comparison, not as a universal model ranking. +
![A completed benchmark result showing the overall recommendation, additional recommendations, total cost, and a correctness versus average cost chart.](../../../assets/factories/benchmark-run-results-overview.png)
A completed benchmark result and comparison chart.
@@ -80,6 +88,7 @@ After the run completes, review the result as a comparison, not as a universal m * **Comparison chart** - Compare the selected result dimensions across configurations. * **Overall table** - Compare each Scorer's average and the combined Overall value. Expand a configuration, task, and repetition to inspect its individual trials. * **Scorer grids** - Show each task's results across configurations for a selected Scorer. +
![Expanded benchmark results showing trial run duration, cost, and scores for a configuration.](../../../assets/factories/benchmark-run-results-detail.png)
Expanded trial results for a configuration.
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..50ea27804 100644 --- a/src/content/docs/factories/code-forges/other-code-forges.mdx +++ b/src/content/docs/factories/code-forges/other-code-forges.mdx @@ -98,7 +98,7 @@ This code forge cannot start factory work from its own repository events. Start ## Related pages -* [Connect GitHub to your factory](/factories/integrations/github/) - Use GitHub's first-class code-forge connection. -* [Connect GitLab to your factory](/factories/integrations/gitlab/) - Use GitLab.com's first-class code-forge connection. +* [Connecting GitHub to your factory](/factories/integrations/github/) - Use GitHub's first-class code-forge connection. +* [Connecting GitLab to your factory](/factories/integrations/gitlab/) - Use GitLab.com's first-class code-forge connection. * [Connect your factory](/factories/connect-your-factory/) - Add the sources that start work after the repository is available. * [Cloud agent secrets](/platform/secrets/) - Store and scope credentials for cloud agents. diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index b34ef6cd4..b38230c46 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -17,7 +17,7 @@ GitHub, GitLab.com, and Azure DevOps Services connect both repositories and prov Pick the sources that match where work starts for your team. You can connect multiple sources, but not both Linear and Jira at the same time. Choose either issue tracker during setup, or connect one later from the factory's settings or [definition](/factories/factory-as-code/). -Once a source is connected, here's the concrete action that hands it work — each links to that integration's full instructions rather than repeating them. +Once a source is connected, this is the action that hands it work: | Source | Best for | Start work by | Continues in | | --- | --- | --- | --- | @@ -63,7 +63,7 @@ When you create a factory through the setup wizard, Warp adds default automation * **GitHub** - Starts work from mentions and assignments, when the factory's label is applied to an issue or pull request, and when a review is submitted on a labeled pull request. It also follows up when labeled pull requests close or merge, completing a linked tracker issue when it can. See the [GitHub integration guide](/factories/integrations/github/). * **GitLab** - Starts work when someone mentions the factory's bot in a merge request comment. See the [GitLab integration guide](/factories/integrations/gitlab/). -* [Azure DevOps](/factories/integrations/azure-devops/) - Starts work when someone mentions the factory identity in a pull request or work item, or assigns it a work item. +* **Azure DevOps** - Starts work when someone mentions the factory identity in a pull request or work item, or assigns it a work item. See the [Azure DevOps integration guide](/factories/integrations/azure-devops/). * **Jira** - Starts work when someone assigns or mentions Warp on a work item in one of the Jira projects you selected. See the [Jira integration guide](/factories/integrations/jira/). * **Linear** - Starts work when a new agent session arrives from one of the Linear teams you selected. See the [Linear integration guide](/factories/integrations/linear/). * **Slack** - Starts work from mentions and messages, as described in the [Slack integration guide](/factories/integrations/slack/). @@ -77,7 +77,7 @@ A [custom webhook](/factories/webhooks/) gives the factory an authenticated URL ## Factory endpoints -[Factory endpoints](/factories/factory-api/) let your own code discover a factory and dispatch a task to it by UID, without knowing which agent handles the work. Use them to build a custom integration for a tool Warp doesn't connect to directly - see [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) for a worked example. +[Factory endpoints](/factories/factory-api/) let your own code discover a factory and send it work by UID, without knowing which agent handles the work. Use them to build a custom integration for a tool Warp doesn't connect to directly. For a worked example, see [build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/). ## Factory MCP @@ -105,3 +105,10 @@ Run the weekly dependency audit. List outdated and vulnerable dependencies, apply safe minor and patch upgrades on a branch, run the tests, and open a PR with the changes and a summary of anything that needs a human decision. ``` + +## Related pages + +* [Factory automations](/factories/automations/) - How triggers and filters decide which events start work. +* [How Warp Factories work](/factories/how-factories-work/) - What happens to a work item after it reaches the foreman. +* [Factory agents](/factories/factory-agents/) - The foreman and the agents it dispatches. +* [Troubleshooting Warp Factories](/factories/troubleshooting/) - What to check when an event doesn't start work. diff --git a/src/content/docs/factories/deployment-patterns.mdx b/src/content/docs/factories/deployment-patterns.mdx index 1fbd9908b..7dd6ad905 100644 --- a/src/content/docs/factories/deployment-patterns.mdx +++ b/src/content/docs/factories/deployment-patterns.mdx @@ -32,14 +32,14 @@ See the [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-life ### 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, connected integrations, Factory MCP, or factory endpoints +* **Execution** - Warp-hosted sandboxes +* **Visibility** - The factory dashboard, session sharing, and the API ### 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 integrations](/factories/connect-your-factory/) let teammates send work from Slack, Microsoft Teams, GitHub, GitLab, Azure DevOps, Linear, and Jira. * [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. diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx index ce324b322..327fb379d 100644 --- a/src/content/docs/factories/developer-tools.mdx +++ b/src/content/docs/factories/developer-tools.mdx @@ -12,14 +12,14 @@ The {VARS.WARP_PLATFORM_API} serves both factories and standalone cloud agent ru ## Choose an API surface -* **[Factory endpoints](/factories/factory-api/)** - Find a factory and send work to it by UID from your application or service. -* **[Agent & run endpoints](/factories/api-and-sdk/)** - Start, monitor, continue, and cancel cloud agent runs from scripts, CI, and backend services. -* **[{VARS.WARP_PLATFORM_API} reference](/api)** - Look up the full HTTP schema, parameters, and responses. -* **[Python SDK](https://pypi.org/project/warp-platform-sdk/)** - Install `warp-platform-sdk` to make typed requests from Python. -* **[TypeScript SDK](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk)** - Install `@warp-dot-dev/warp-platform-sdk` to make typed requests from TypeScript. -* **[API errors](/factories/api-and-sdk/troubleshooting/errors/)** - Resolve error responses by HTTP status and machine-readable code. -* **[Factory MCP](/factories/factory-mcp/)** - Exchange work between a factory and a connected coding agent or MCP client. -* **[Webhooks](/factories/webhooks/)** - Receive events from systems that can send JSON and route matching deliveries into factory automations. +* [Factory endpoints](/factories/factory-api/) - Find a factory and send work to it by UID from your application or service. +* [Agent and run endpoints](/factories/api-and-sdk/) - Start, monitor, continue, and cancel cloud agent runs from scripts, CI, and backend services. +* [{VARS.WARP_PLATFORM_API} reference](/api) - Look up the full HTTP schema, parameters, and responses. +* [Python SDK](https://pypi.org/project/warp-platform-sdk/) - Install `warp-platform-sdk` to make typed requests from Python. +* [TypeScript SDK](https://www.npmjs.com/package/@warp-dot-dev/warp-platform-sdk) - Install `@warp-dot-dev/warp-platform-sdk` to make typed requests from TypeScript. +* [API errors](/factories/api-and-sdk/troubleshooting/errors/) - Resolve error responses by HTTP status and machine-readable code. +* [Factory MCP](/factories/factory-mcp/) - Exchange work between a factory and a connected coding agent or MCP client. +* [Custom webhooks](/factories/webhooks/) - Receive events from systems that can send JSON and route matching deliveries into factory automations. ## Get started diff --git a/src/content/docs/factories/factory-agents.mdx b/src/content/docs/factories/factory-agents.mdx index ad7510bec..9b1c6a98a 100644 --- a/src/content/docs/factories/factory-agents.mdx +++ b/src/content/docs/factories/factory-agents.mdx @@ -11,7 +11,7 @@ Every factory has a **foreman**, the agent you talk to from the tool that sends ## 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, and you choose one to four other agents to go with it. These defaults are a starting point; [add custom agents](#add-custom-agents) 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. | Agent | What it does | What it produces | | --- | --- | --- | @@ -27,7 +27,7 @@ For the complete lifecycle, see [how Warp Factories work](/factories/how-factori ### 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** 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. 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. @@ -55,7 +55,7 @@ Review independently examines the change for unmet requirements, broken conventi ## 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. +A new factory's definition includes skills for code quality, code review, and UI verification, plus one for each tool you connect: your code host, Slack or Microsoft Teams, and Linear or Jira. They live in the definition's `skills/` directory, so every agent can use them. See [factory skills](/factories/factory-skills/) for what each one covers and how to add your own. ## Configure agent behavior @@ -73,13 +73,12 @@ Every default agent comes with GitHub skills, and the foreman also comes with a
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. +Where you make these changes depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives): -For more information about the two locations, see [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). +* **Warp-managed factory** - Edit everything, including harness, auth, and credential strategy, from the dashboard. +* **GitHub-backed factory** - The settings live in the definition files. The dashboard shows them read-only, and you change them by editing the files. -Factory setup doesn't choose models for you. To change the model an agent uses, edit that agent. +Setup assigns each default agent a model suited to its role. To change it, edit the agent. ## Choose models and harnesses per agent @@ -124,26 +123,21 @@ Change an agent's harness to Claude Code or Codex to run it with that provider's 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 custom agents 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: +A custom agent gets the factory-wide skills under `skills/` but no role instructions of its own, so write its job into `agent.md`. For procedures only that agent needs, add a skill under `agents//skills/`. See [factory skills](/factories/factory-skills/). -* **One agent** - Put the skill under `agents//skills/`. -* **Every agent** - Put the skill under `skills/`. +### How the foreman dispatches agents -### Choose a configured factory agent +The foreman starts the factory's other agents as child runs with the `run_agents` tool, selecting each one by its UID in `agent_run_configs[].agent_identity_uid`. A child run started this way inherits that agent's environment, runner, host, harness, and model unless the call overrides them; a child started without a factory agent's UID runs with no factory configuration, as in [multi-agent orchestration](/platform/orchestration/) from any Warp conversation. Keep that dispatch step if you rewrite the foreman's instructions or add a custom coordinating 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. +### Automations -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/). +[Automations](/factories/automations/) start a chosen agent on a [schedule](/factories/factory-as-code/#triggersschedule) or when an event arrives from a connected tool. They're one more way for work to enter the factory; the foreman still coordinates whatever they start. For every way to route work into a factory, see [connect your factory](/factories/connect-your-factory/). ## Human decision points and permissions @@ -153,8 +147,12 @@ Automations start a chosen agent on a [schedule](/factories/factory-as-code/#tri | Merging | Agents never merge; the foreman hands the finished pull request to a human | 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. +Instructions decide what an agent is told to do; configuration and provider permissions decide what it can reach. Enforce merge policy with branch protection and repository permissions, and enforce access with each agent's configuration. -So enforce with the real controls: branch protection and repository permissions decide who merges, and each agent's configuration decides what it can reach. +## Related pages -Next, capture these choices in [factory definitions as code](/factories/factory-as-code/). +* [How Warp Factories work](/factories/how-factories-work/) - The stages a work item moves through and where people decide. +* [Factory skills](/factories/factory-skills/) - The built-in skills every agent starts with, and how to add your own. +* [Factory definition syntax](/factories/factory-as-code/) - Every `agent.md` key, including per-agent model, harness, and runner overrides. +* [Harnesses for cloud agents](/platform/harnesses/) - What each harness supports and how to authenticate it. +* [Connect your factory](/factories/connect-your-factory/) - The sources that send work to the foreman. diff --git a/src/content/docs/factories/factory-api.mdx b/src/content/docs/factories/factory-api.mdx index 8e044192a..75459308a 100644 --- a/src/content/docs/factories/factory-api.mdx +++ b/src/content/docs/factories/factory-api.mdx @@ -12,25 +12,23 @@ The factory endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to find ## How it works -* `GET /factory` - list factories your account can access. Add `search` to filter by name or alias, case-insensitive. -* `GET /factory/{uid}` - get one factory by UID. -* `POST /factory/{uid}/runs` - dispatch a run to the factory's foreman agent. Pass a `prompt`; the server resolves the foreman for you. +* `GET /factory` - List the factories your account can access. Add `search` to filter by name or alias, case-insensitive. +* `GET /factory/{uid}` - Get one factory by UID. +* `POST /factory/{uid}/runs` - Dispatch a run to the factory's foreman agent. Pass a `prompt`; the server resolves the foreman for you. A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [agent and run endpoints](/factories/api-and-sdk/) used for any run. ## Choosing an endpoint family -Use factory endpoints to find or start work on a factory. Use Agent & run endpoints for everything else: a standalone cloud agent, run management, or orchestration. +Use factory endpoints to find a factory or start work on it. Use the agent and run endpoints for everything else: a standalone cloud agent, run management, or orchestration. | Task | Recommended API | | --- | --- | -| Find a factory by name before dispatching to it | factory endpoints - `GET /factory?search=` | -| Start a new task on a factory | factory endpoints - `POST /factory/{uid}/runs` | -| Continue, monitor, or cancel a run (factory or standalone) | Agent & run endpoints - `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` | -| Run a standalone cloud agent with no factory involved | Agent & run endpoints - `POST /agent/runs` | -| 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. +| Find a factory by name before dispatching to it | `GET /factory?search=` (factory endpoints) | +| Start new work on a factory | `POST /factory/{uid}/runs` (factory endpoints) | +| Continue, monitor, or cancel a run (factory or standalone) | `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` (agent and run endpoints) | +| Run a standalone cloud agent with no factory involved | `POST /agent/runs` (agent and run endpoints) | +| Build a multi-agent orchestration | The agent and run endpoints; see [multi-agent orchestration](/platform/orchestration/) | ## Discover a factory @@ -42,11 +40,11 @@ from warp_platform_sdk import WarpClient client = WarpClient(api_key=os.environ.get("WARP_API_KEY")) -# Find a factory by name or alias — no UIDs needed up front +# Find a factory by name or alias, with no UID needed up front page = client.factories.list(search="payments") factory = page.factories[0] -# With the pagination scheme wired, iteration auto-pages +# Iterating over the result fetches every page of matches for f in client.factories.list(search="payments"): print(f.uid, f.name) ``` @@ -95,7 +93,7 @@ Content-Type: application/json } ``` -Every field except `prompt` is optional. Omit `title` and the server derives one from the prompt. `ticket_ref` identifies the originating ticket in `:` form (for example `linear:PAY-123` or `jira:PROJ-456`); pass `ticket_url` to link the factory's task record back to it, or omit both for an adhoc reference. +Every field except `prompt` is optional. Omit `title` and the server derives one from the prompt. `ticket_ref` identifies the originating ticket in `:` form (for example `linear:PAY-123` or `jira:PROJ-456`); pass `ticket_url` to link the factory's work item back to it, or omit both for an ad hoc reference. ## Continue and monitor the run @@ -120,7 +118,7 @@ See [key endpoints](/factories/api-and-sdk/#key-endpoints) for the full set of r ## Related pages * [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including factory endpoints alongside Slack, GitHub, and Factory MCP. -* [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) - A worked example that discovers a factory and dispatches and continues a task from a custom chat integration. +* [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) - A worked example that discovers a factory, dispatches work, and continues it from a custom chat integration. * [Factory MCP](/factories/factory-mcp/) - Connect a local coding agent to a factory instead of calling the REST API directly. -* [Agent & run endpoints](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying {VARS.WARP_PLATFORM_API}. -* [How Warp Factories work](/factories/how-factories-work/) - The stages a dispatched task moves through after the foreman picks it up. +* [Agent and run endpoints](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying {VARS.WARP_PLATFORM_API}. +* [How Warp Factories work](/factories/how-factories-work/) - The stages a dispatched work item moves through after the foreman picks it up. diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 1c6cc480f..052197bcc 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -4,7 +4,7 @@ description: >- Look up the files and public keys in a factory definition: factory.yaml, agents, automations, runners, routers, benchmarks, scorers, skills, and webhooks. sidebar: - label: "Factory definition" + label: "Definitions as code" --- import { VARS } from '@data/vars'; @@ -897,7 +897,7 @@ Pair `workerHost` with a runner whose `platform` matches the worker. Follow the ## 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 the schema and validate a tree from any coding agent, and send work to a factory. +* [Connecting GitHub to your factory](/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. diff --git a/src/content/docs/factories/factory-dashboard.mdx b/src/content/docs/factories/factory-dashboard.mdx index 56076ba31..de043d8ee 100644 --- a/src/content/docs/factories/factory-dashboard.mdx +++ b/src/content/docs/factories/factory-dashboard.mdx @@ -8,27 +8,17 @@ sidebar: --- import { VARS } from '@data/vars'; -The factory dashboard is the web app for operating a single factory. Open the {VARS.FACTORY_WEB_APP}, then select a factory to track its work, inspect its runs and pull requests, and manage its agents, automations, and settings. - -:::note -"Factory dashboard" names the whole surface. **Dashboard**, in bold, is one page inside it: the metrics page you land on when you open a factory. -::: +The factory dashboard is the web app for operating a single factory. Open the {VARS.FACTORY_WEB_APP}, then select a factory to track its work, inspect its runs and pull requests, and manage its agents, automations, and settings. The factory opens on its **Dashboard** page, the metrics view described below. ## Getting oriented -Select a factory in the sidebar to open its pages. **Runs**, **MCPs and apps**, **Secrets**, and **Integrations** sit above the factory list and cover your whole team, not a single factory. **Inbox** sits there too, but it's neither team-wide nor per-factory: there's a single global Inbox page, and it shows only the items waiting on you personally, across every factory you have access to. Everything else on this page is scoped to the factory you select. +Select a factory in the sidebar to open its pages. **Runs**, **MCPs and apps**, **Secrets**, and **Integrations** sit above the factory list and cover your whole team, not a single factory. **Inbox** sits there too, but it's personal rather than team-wide: one page lists the items waiting on you across every factory you can access. Everything else on this page is scoped to the factory you select. -A factory opens on its **Dashboard** page, covered next. **Factory definition** appears only on Warp-managed factories, since a factory whose definition lives in your own repository is edited there instead. +**Factory definition** appears only on Warp-managed factories. A factory whose definition lives in your own repository is edited there instead. ## Read metrics on the Dashboard page -**Dashboard** is the factory's landing page. It summarizes the factory over a date range you choose: - -* **Autonomy** - The share of the factory's merged PRs that needed no human code push before merging. Opening the PR counts as a push, so a human-authored PR that a factory run later revised doesn't count as autonomous; comments, reviews, requested changes, and the merge itself don't count as a push. -* **PR cycle time** - The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with an independent median for each stage - the stage medians don't sum to the headline. -* **Cost per PR** - The median cost of PRs opened in the range. When a single run produces more than one PR, its cost splits evenly across them. Treat it as a lower-bound estimate: it can miss some run usage and does not match billing. See [Measure and improve a factory](/factories/measure-and-improve/) for its limitations. - -The page also charts opened versus merged PRs and a breakdown of runs, and the **Cost per PR** card expands to list the most expensive PRs in the range. When Scorers are set up, Scorer cards summarize recent classification results. +**Dashboard** summarizes the factory over a date range you choose: runs, pull requests opened and merged, **Autonomy** (the share of merged PRs that needed no human code push), **PR cycle time**, and **Cost per PR**, which expands to list the most expensive PRs in the range. When Scorers are set up, Scorer cards summarize recent classification results. For how each metric is calculated and what it leaves out, see [measure and improve a factory](/factories/measure-and-improve/#read-metrics-on-the-dashboard-page).
![The Dashboard page showing a Cost per PR chart broken down by compute, platform, and inference cost, plus two example Scorer cards.](../../../assets/factories/factory-dashboard-metrics.png) @@ -53,25 +43,25 @@ Run pages don't include a chat input, but you can still steer a run: **View sess ## Manage agents and automations -**Agents** lists the factory's agents. Create agents and edit their instructions, model or harness, runner, host, secrets, and MCP servers. **Automations** defines the triggers that start runs: a schedule (including custom cron expressions), a GitHub, Linear, Slack, or Jira event, or a delivery to a custom webhook. **Webhooks** is a tab within **Automations** that lists the factory's [custom webhooks](/factories/webhooks/), where you create them, copy their URLs, rotate secrets, and read the delivery log. +**Agents** lists the factory's agents. Create agents and edit their instructions, model or harness, runner, host, secrets, and MCP servers. **Automations** defines the triggers that start runs: a schedule (including custom cron expressions), an event from a connected tool such as GitHub or Slack, or a delivery to a custom webhook. **Webhooks** is a tab within **Automations** that lists the factory's [custom webhooks](/factories/webhooks/), where you create them, copy their URLs, rotate secrets, and read the delivery log. {/* VISUAL: The Automations editor, to complement the Agents list already shown in Configure agent behavior on the factory agents page. */} -The automation editor doesn't change execution settings; an automation only overrides them through [execution overrides in the definition files](/factories/factory-as-code/#execution-overrides). When the factory's definition lives in an external repository, Agents, Automations, and Scorers are read-only; make changes there through pull requests. +The automation editor doesn't change execution settings; an automation only overrides them through [execution overrides in the definition files](/factories/factory-as-code/#execution-overrides). On a GitHub-backed factory, Agents, Automations, and Scorers are read-only; make changes through pull requests to the definition repository. ## Edit definitions in the Factory definition tab -**Factory definition** is the factory dashboard's view of the definition files that [definitions as code](/factories/factory-as-code/) describes in full. Where the definition lives decides what you get: +**Factory definition** is the factory dashboard's view of the definition files that the [factory definition syntax](/factories/factory-as-code/) describes in full. Where the definition lives decides what you get: * **Warp-managed** - Browse and edit the definition files. Saving validates the definition and commits all changes together. -* **Managed in GitHub** - The tab doesn't appear. Edit the definition through pull requests in your repository, and **Settings** links back to it. +* **GitHub-backed** - The tab doesn't appear. Edit the definition through pull requests in your repository, and **Settings** links back to it. * **Live-managed** - The factory is managed through the API, so there are no definition files to browse. When an agent proposes a change to a Warp-managed definition, a spec review for the branch appears in your [inbox](/factories/factory-inbox/). Open it to comment on the diff, use **Request changes** to send feedback back to the agent, or **Approve & merge**. ## Score and benchmark -**Scorers** is where you create Scorers and read their results. **Self-improvement** lists the pull requests the self-improvement flow opens after analyzing runs your Scorers mark as failing, and **Benchmarks** compares model and runner configurations against a fixed set of tasks. See [Configuring Scorers](/factories/measure-and-improve/scorers/), [Configuring and reviewing Self-improvement](/factories/measure-and-improve/self-improvement/), and [benchmarking factory agent configurations](/factories/benchmarks/) for what each one is and how to use it. +**Scorers** is where you create Scorers and read their results. **Self-improvement** lists the pull requests Self-improvement opens after analyzing runs your Scorers mark as failing, and **Benchmarks** compares model, harness, and runner configurations against a fixed set of tasks. See [configuring Scorers](/factories/measure-and-improve/scorers/), [configuring and reviewing Self-improvement](/factories/measure-and-improve/self-improvement/), and [factory benchmarks](/factories/benchmarks/). ## Change factory settings @@ -85,14 +75,14 @@ When an agent proposes a change to a Warp-managed definition, a spec review for * **Integrations** - The integrations this factory can access. * **Deletion** - Deletes the factory. This cannot be undone. -For a file-managed factory, `runners/*.yaml` in the repository is the source of truth. Anything managed in an external repository is read-only in Settings. +On a GitHub-backed factory, `runners/*.yaml` in the repository is the source of truth, and anything defined there is read-only in Settings. ## Related pages * [Factory inbox](/factories/factory-inbox/) - See and resolve the questions, spec approvals, and PR reviews waiting on you. * [How Warp Factories work](/factories/how-factories-work/) - The stages work moves through and where humans stay in the loop. -* [Definitions as code](/factories/factory-as-code/) - Define agents, automations, runners, and source ownership in code. +* [Factory definition syntax](/factories/factory-as-code/) - Define agents, automations, runners, and source ownership in code. * [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure it. -* [Measure and improve a factory](/factories/measure-and-improve/) - Configure Scorers and use them in an improvement loop. -* [Benchmarking factory agent configurations](/factories/benchmarks/) - Create a benchmark suite and compare configurations on fixed tasks. +* [Measure and improve a factory](/factories/measure-and-improve/) - What each dashboard metric means, and how to use Scorers in an improvement loop. +* [Factory benchmarks](/factories/benchmarks/) - Create a benchmark suite and compare configurations on fixed tasks. * [Troubleshooting Warp Factories](/factories/troubleshooting/) - Fixes for setup problems, work that doesn't start, and stuck runs. diff --git a/src/content/docs/factories/factory-inbox.mdx b/src/content/docs/factories/factory-inbox.mdx index 4f0f93cfb..d600e29e9 100644 --- a/src/content/docs/factories/factory-inbox.mdx +++ b/src/content/docs/factories/factory-inbox.mdx @@ -7,7 +7,7 @@ sidebar: label: "Factory inbox" --- -**Inbox** collects everything your factories need from you specifically, across every factory you have access to, in one place. Instead of checking each factory's Runs page for stalled or waiting work, open Inbox from the sidebar to see it all at a glance. +**Inbox** collects everything your factories need from you, across every factory you have access to. Open it from the sidebar instead of checking each factory's Runs page for stalled or waiting work. ## What appears in your inbox @@ -17,19 +17,19 @@ Each item is one of six kinds: * **Answered question** - An agent already answered a question, for your information. No action is required. * **Spec review** - A spec needs your approval before implementation starts. * **PR review** - One or more pull requests are ready for your review. -* **Blocked** - A run stopped and needs attention, and nothing else on that task already needs yours. +* **Blocked** - A run stopped and needs attention, and nothing else on that work item already needs yours. * **Failed** - A run ended in an error, under the same condition as Blocked. -Inbox only shows work tied to tasks *you* started. It's a personal queue, not a team-wide feed: a teammate's task, even a blocked or failed one, never appears in your inbox. +Inbox only shows work items *you* started. It's a personal queue, not a team-wide feed: a teammate's work item, even a blocked or failed one, never appears in your inbox. Items clear on their own once they stop being relevant. For example, a PR review clears when someone reviews or merges the pull request, and a question clears once it's answered. You can also resolve any item yourself. ## Reviewing your inbox -1. Click a row to open its details in a side pane. From there, click a chip or the primary action, like **View run**, to open the underlying resource: the run, pull request, spec, or originating thread or ticket. -2. Once you've handled an item, mark it **resolved**. Click **Undo** in the confirmation to bring it back if you resolved it by mistake. -3. Mark items **read** or **unread** to track what you've reviewed without resolving them. -4. Filter by factory, read state, or kind, or search titles and descriptions, to narrow a long inbox. +* **Open an item** - Click a row to open its details in a side pane. From there, click a chip or the primary action, such as **View run**, to open the underlying resource: the run, pull request, spec, or originating thread or ticket. +* **Resolve it** - Once you've handled an item, mark it **resolved**. Click **Undo** in the confirmation to bring it back if you resolved it by mistake. +* **Track what you've seen** - Mark items **read** or **unread** without resolving them. +* **Narrow the list** - Filter by factory, read state, or kind, or search titles and descriptions. ## Related pages diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 9b4bfc330..2dcc0048a 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -9,14 +9,14 @@ sidebar: import AgentOnly from '@components/AgentOnly.astro'; import { VARS } from '@data/vars'; -Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your team's factories. An agent can send work to a factory, pull down a task to continue locally, and return the result. +Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your team's factories. An agent can send work to a factory, pull down a task to continue locally, and return the result. A task is what the MCP tools call a factory [work item](/factories/how-factories-work/). ## What you can use it for * **Send work in** - Turn anything from your local session into a factory task: a bug you found, review feedback, or a half-finished change. * **Continue a task locally** - Pull a task's context into your own checkout, work with your own tools, and return the result to the same task. -* **Stay in sync** - List and search tasks, read a task's conversation, and message its [foreman](/factories/factory-agents/), the agent that orchestrates each task inside the factory. -* **Create a factory** - Let your coding agent guide you through choosing a team, code host, repositories, factory agents, and integrations. +* **Stay in sync** - List and search tasks, read a task's conversation, message its [foreman](/factories/factory-agents/), and check what's waiting on you in your [inbox](/factories/factory-inbox/). +* **Create and connect a factory** - Let your coding agent guide you through choosing a team, code host, repositories, factory agents, and integrations, and attach Slack, Linear, or Jira to a factory later. * **Edit a factory's definition** - Read the definition schema and validate a factory's [definition files](/factories/factory-as-code/) before opening a pull request. ## Connect and authenticate @@ -121,23 +121,25 @@ Sending work to a factory means you're no longer watching it. To be notified whe ## Tool reference -Your MCP client fetches the full input schemas from the server, and tool results include links that open the corresponding task or run in the factory's [factory dashboard](/factories/factory-dashboard/). -The onboarding tools from `list_teams` through `create_factory` require browser sign-in. +Your MCP client fetches the full input schemas from the server, and tool results include links that open the corresponding task or run in the [factory dashboard](/factories/factory-dashboard/). The onboarding tools from `list_teams` through `create_factory` require browser sign-in. | Tool | What it does | | --- | --- | | `list_factories` | Lists the factories you can access. | +| `list_inbox` | Lists the unresolved [inbox](/factories/factory-inbox/) items waiting on you, or on your team. | | `get_factory_file_schema` | Returns the JSON Schema documents for factory definition files, as a catalog or one document at a time. | | `validate_factory_files` | Validates a complete factory definition tree without saving or applying it. | | `list_teams` | Lists current memberships and first-time joinable team choices. | | `create_team` | Creates the authenticated user's first team with a confirmed name. | | `join_team` | Joins a team selected from the first-time discovery choices. | -| `get_team_funding_status` | Checks first-team credit readiness and returns the browser checkout step when required. | +| `get_team_funding_status` | Checks whether a first team has credits and returns the browser checkout step when it doesn't. | | `list_forge_repositories` | Lists repositories available through a team's connected GitHub or GitLab account. | -| `list_tracker_scopes` | Lists the Linear teams or Jira projects that can be scoped to route issues to a new factory. | +| `list_tracker_scopes` | Lists the Linear teams or Jira projects that can route issues to a new factory. | | `start_connection` | Starts or checks setup for GitHub, GitLab, Slack, Linear, or Jira. | | `get_connection_status` | Checks whether a browser authorization flow completed. | | `create_factory` | Creates a factory with the selected repositories, integrations, and optional factory agents. | +| `start_factory_learning` | Starts a foreman run that customizes a new or existing factory from its definition, integrations, and repository conventions. It consumes credits, so the agent asks before starting it. | +| `attach_integration` | Adds Slack, Linear, or Jira to an existing factory. | | `list_tasks` | Lists the tasks in one factory, with filters such as creator, stage, and date. | | `search_task` | Searches task titles across all factories you can access. | | `get_task` | Reads a task's status, run history, and outputs. Accepts a task ID or a reference such as a URL, issue, pull request, or branch. With `start_working=true`, also returns local setup guidance. | @@ -149,7 +151,7 @@ The onboarding tools from `list_teams` through `create_factory` require browser ## Related pages -* [**Definitions as code**](/factories/factory-as-code/) - Every file and key in a factory definition, the JSON Schema behind them, and how to validate a change. -* [**Factory agents**](/factories/factory-agents/) - The foreman and the other agents that carry out a factory's tasks. -* [**How Warp Factories work**](/factories/how-factories-work/) - The task lifecycle and the agents that move work through it. -* [**Warp Factories quickstart**](/factories/quickstart/) - Create a factory and send it its first work item. +* [Factory definition syntax](/factories/factory-as-code/) - Every file and key in a factory definition, the JSON Schema behind them, and how to validate a change. +* [Factory agents](/factories/factory-agents/) - The foreman and the other agents that carry out a factory's work. +* [How Warp Factories work](/factories/how-factories-work/) - The work-item lifecycle and the agents that move work through it. +* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send it its first work item. diff --git a/src/content/docs/factories/factory-skills.mdx b/src/content/docs/factories/factory-skills.mdx index e279b6fb7..5965538d5 100644 --- a/src/content/docs/factories/factory-skills.mdx +++ b/src/content/docs/factories/factory-skills.mdx @@ -7,19 +7,28 @@ sidebar: label: "Factory skills" --- -A skill tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override [default agents](/factories/factory-agents/), without editing their prompts directly. +A skill tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override the [default agents](/factories/factory-agents/) without editing their prompts directly. -## Skill sources in a factory +A factory's agents draw on three kinds of skills: -A factory run can use skills from three sources: +* **Built-in skills** - `SKILL.md` files Warp adds to the factory definition for the code host, chat tool, and issue tracker you connect, plus shared code-quality and review procedures. +* **Custom skills** - `SKILL.md` files your team adds to the definition, available to every agent or scoped to one. +* **Bundled Warp skills** - Skills that ship with the Warp Agent harness, such as `factory-files` for editing definitions and `factory-mcp` for working with a factory through [Factory MCP](/factories/factory-mcp/). -* **Factory role and integration skills** - Baseline procedures that come from the default agent roles and integrations you configure, such as GitHub, Slack, Linear, or Jira. -* **Warp-provided platform-bundled skills** - Product capabilities that Warp provides, such as `oz-platform`, `factory-files`, and `factory-mcp`. -* **Custom file-based factory skills** - Team-owned `SKILL.md` files in the factory definition, available to every agent or scoped to one agent. +## Built-in skills -## Custom file-based factory skills +When you create a factory, Warp writes a set of skills into the definition's `skills/` directory so the agents know how to work with your tools before you write anything custom: -A custom skill is a directory containing a `SKILL.md`. It's part of the factory's [definition](/factories/factory-as-code/), not an agent's settings. Where you place the directory decides who can use it: +* **Code quality, code review, and UI verification** - Every factory gets these three: the standard a code change is held to, how to review a change and write up findings, and how to capture visual proof of a UI change with [Computer Use](/agents/capabilities/computer-use/). +* **Code host** - The skill for your connected code host: `github`, `gitlab`, or `azuredevops`. It covers branches, commits, draft pull requests, review comments, and CI status. +* **Chat tool** - A `slack` or `microsoft-teams` skill when you connect that tool. The foreman's instructions tell it to use the skill, since it's the agent that replies in threads. +* **Issue tracker** - A `linear` or `jira` skill when you connect that tracker. Connecting a tracker later adds its skill then. + +Because these live under `skills/`, every agent in the factory can use them, including custom agents. They're ordinary files: read them in the **Factory definition** tab of a Warp-managed factory or in the repository of a GitHub-backed one, and edit them the same way you edit any other skill. Anything you add alongside them extends the set rather than replacing it. + +## Custom skills + +A custom skill is a directory containing a `SKILL.md`. It's part of the factory's [definition](/factories/factory-as-code/), not an agent's settings, and where you place the directory decides who can use it: ```text skills/ @@ -33,79 +42,41 @@ agents/ ``` * **`skills//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. - -## Warp-provided platform-bundled skills +* **`agents//skills//SKILL.md`** - Available only to that agent. Use this for procedures specific to one role, such as how the review agent applies your security checklist. -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`. +Both forms use the same `SKILL.md` format as skills anywhere else in Warp. See [Skills](/agents/capabilities/skills/) for the file format, frontmatter, and argument syntax. -Warp provides these stable bundled-skill IDs: +### When to add a custom skill -| 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. | +Add a custom skill when an agent needs to do something the built-in set doesn't cover, such as: -See [skill actions in conversation data](/factories/api-and-sdk/#skill-actions-in-conversation-data) for the API reference. - -## Attribute team-owned skill usage - -The [Conversation API](/api) returns skill loads as `read_skill` actions. Use the action's `input` to classify the skill: - -* **`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 a custom skill when a default agent needs to do something the built-in baseline doesn't cover, such as: - -* Enforcing a specific test, lint, or validation command before a change is considered complete. +* Running a specific test, lint, or validation command before a change counts as 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. +* Teaching a custom agent its job. Custom agents start with the factory-wide skills but no role instructions of their own. -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). +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 [configure agent behavior](/factories/factory-agents/#configure-agent-behavior) and [credential boundaries](/factories/infrastructure-and-security/#credential-boundaries). -## Add or edit a skill +### Add or edit a skill Where you edit a skill depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives): -* **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. +* **Warp-managed** - Add or edit `SKILL.md` files in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step. +* **GitHub-backed** - Add or edit the files in the 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. + +For a factory-wide skill and a per-agent skill side by side, 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. + +## Bundled Warp skills -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. +Agents on the Warp Agent harness also carry Warp's bundled skills, which aren't files in your definition. The ones that matter for factory work are `factory-files`, which reads the definition schema and validates a definition tree, `factory-mcp`, which sends work to a factory and takes it back through Factory MCP, and `oz-platform`, which runs and inspects cloud agents through the API and CLI. In run data, a bundled skill load carries a `bundled_skill_id`; see [skill actions in conversation data](/factories/api-and-sdk/#skill-actions-in-conversation-data) for the full list and how to tell bundled loads apart from your own skills. -## Skills and self-improvement +## 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. +A factory can propose changes to a skill. When [Self-improvement](/factories/measure-and-improve/self-improvement/) is on for a Scorer and that Scorer flags a recurring failure, the follow-up run can edit the responsible skill the same way it can edit application code. The change arrives as a pull request for your team to review, in the factory dashboard or on 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. +* [Factory definition syntax](/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. diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index c4a4af401..13fecf7d9 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -7,18 +7,18 @@ sidebar: label: "Infrastructure & 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. +You choose where a factory's code runs, which providers serve its inference, and which credentials each agent receives. Warp coordinates the work and stores transcripts and artifacts. -## Control plane and execution plane +## What runs where -Each factory uses two planes: +Warp receives triggers, starts and tracks runs, routes inference requests, and stores run records. The code itself is checked out, built, and exercised in one of two places: -* **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. +* **A Warp-hosted sandbox** - The default. Warp provisions and discards the sandbox for each run. +* **A managed self-hosted worker** - A worker you run on your own infrastructure. Warp sends it the task, its configuration, and scoped runtime credentials; the worker checks out code, runs setup, invokes tools, and executes commands. ```mermaid flowchart LR - I["Integrations and triggers"] --> C["Warp control plane
coordination · identity/config
observability · inference routing"] + I["Integrations and triggers"] --> C["Warp
runs, configuration,
observability, inference routing"] C --> H["Warp-hosted sandbox"] C -->|"task, config, and scoped
runtime credentials"| S["Managed self-hosted worker"] H -->|"results, transcripts,
artifacts, telemetry"| C @@ -27,7 +27,7 @@ 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 the providers you configure. 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. ![Self-hosted data security and boundaries diagram showing what stays in customer infrastructure, what Warp retains, and what transits Warp to model providers](../../../assets/agent-platform/data-security-boundaries.png) @@ -76,7 +76,6 @@ The worker backend sets isolation and scheduling on your infrastructure: | **[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 | - ## Choose inference independently Execution hosting doesn't select inference. Configure that boundary separately. @@ -135,10 +134,10 @@ Warp meters hosted compute, Warp-provided inference, and platform services. Self ## 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 credits**](/support-and-community/plans-and-billing/platform-credits/) - Understand factory metering. +* [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 credits](/support-and-community/plans-and-billing/platform-credits/) - Understand factory metering. diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx index 6cc8edb96..829c8324f 100644 --- a/src/content/docs/factories/integrations/github.mdx +++ b/src/content/docs/factories/integrations/github.mdx @@ -1,5 +1,5 @@ --- -title: Connect GitHub to your factory +title: Connecting GitHub to your factory description: >- Connect GitHub to your factory so issues, pull requests, reviews, and CI events start factory work and results post back to GitHub. @@ -71,7 +71,6 @@ For a review automation that fires when pull requests open, see [`04-code-review - For the exact `event` value each trigger uses in a definition file, see [triggers](/factories/factory-as-code/#triggers). ### Automation filters @@ -158,3 +157,10 @@ Check that the installation still covers the target repository and grants the re ### A factory-definition check doesn't appear The check runs only for factories whose [definition is managed as code](/factories/factory-as-code/) in a GitHub repository. Confirm the pull request targets the branch the factory runs from and that the GitHub App covers the repository. + +## Related pages + +* [Connect your factory](/factories/connect-your-factory/) - Every other way to route work into the factory. +* [Factory automations](/factories/automations/) - How triggers and filters decide which GitHub activity starts work. +* [Factory definition syntax](/factories/factory-as-code/) - Declare GitHub triggers and filters as code, and keep the definition itself in GitHub. +* [GitHub integration](/platform/integrations/github/) - Install the Warp GitHub App and review its permission model. diff --git a/src/content/docs/factories/integrations/gitlab.mdx b/src/content/docs/factories/integrations/gitlab.mdx index de285ec09..91ffa2fa1 100644 --- a/src/content/docs/factories/integrations/gitlab.mdx +++ b/src/content/docs/factories/integrations/gitlab.mdx @@ -1,5 +1,5 @@ --- -title: Connect GitLab to your factory +title: Connecting GitLab to your factory description: >- Connect GitLab to your factory so merge request events and bot mentions start factory work and results post back as comments and merge requests. @@ -114,7 +114,7 @@ triggers: Triage newly opened merge requests and post an initial review. ``` -A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out. Warp seeds it with the factory's bot username and rejects definitions that set it. GitLab isn't yet supported as a definition-hosting repository, so declare these triggers in a Warp-managed or GitHub-hosted definition even when the factory's automations and mentions run through GitLab; see [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). +A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out: Warp fills it in with the factory's bot username and rejects definitions that set it. GitLab isn't yet supported as a definition-hosting repository, so declare these triggers in a Warp-managed or GitHub-backed definition even when the factory's automations and mentions run through GitLab; see [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). ## Troubleshooting @@ -138,4 +138,9 @@ Confirm the target project is one of the factory's selected projects and the ope Only top-level groups you own appear, and a group already connected to another Warp workspace can't be connected again. If you don't own the group, ask an owner to establish the connection in Warp. -For the other ways to route work into a factory, see [Connect your factory](/factories/connect-your-factory/). +## Related pages + +* [Connect your factory](/factories/connect-your-factory/) - Every other way to route work into the factory. +* [Factory automations](/factories/automations/) - How triggers and filters decide which GitLab activity starts work. +* [Factory definition syntax](/factories/factory-as-code/) - Declare GitLab triggers and filters as code. +* [Connecting other code forges to your factory](/factories/code-forges/other-code-forges/) - Repository access for self-managed GitLab instances. diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 1c06677da..cc6906703 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -1,5 +1,5 @@ --- -title: Connect Jira to your factory +title: Connecting Jira to your factory description: >- Connect Jira Cloud to your factory so work items assigned to Warp start factory runs and return results in Jira. @@ -22,7 +22,7 @@ Connect Jira Cloud to your factory so your team can start factory work without l 1. **Open Jira setup.** Choose **Jira** while creating a factory. To connect it later, open the top-level **Integrations** page in the {VARS.FACTORY_WEB_APP}, find **Jira**, and click **Connect**. 2. **Install Warp for Jira and connect the site.** A Jira site admin installs the app on the Jira Cloud site. In Jira, open **Apps** > **Manage apps** > **Warp** > **Configure**, then click **Connect to Warp**. Once connected, Jira is available to every factory in the workspace. See the [Jira installation steps](/platform/integrations/jira/#setup) for the full app flow. -If you aren't a Jira site admin, choose **Someone else** during setup and email the request or copy the approval link to a site admin. The link expires after seven days, and you can resend or revoke it while the request is pending. + If you aren't a Jira site admin, choose **Someone else** during setup and email the request or copy the approval link to a site admin. The link expires after seven days, and you can resend or revoke it while the request is pending. 3. **Connect Jira to the factory.** In the factory dashboard, open **Settings** > **Integrations**, connect **Jira**, select the projects this factory works with, then click **Enable**. If you connected Jira while creating the factory, select the projects before finishing setup. Each factory opts in separately even though the Jira site is connected to the workspace. @@ -94,4 +94,9 @@ Warp's built-in Jira tools read Jira as the person who created the run; that per * **The session shows no result** - Open the matching automation's run to see whether the agent is still working, waiting for input, or failed. * **A Jira update fails** - Confirm the app can access the work item's project and that the requested action or workflow transition is valid. -For the other ways to route work into a factory, see [Connect your factory](/factories/connect-your-factory/). +## Related pages + +* [Connect your factory](/factories/connect-your-factory/) - Every other way to route work into the factory. +* [Factory automations](/factories/automations/) - How triggers and filters decide which Jira sessions start work. +* [Jira integration](/platform/integrations/jira/) - Install the Warp app on a Jira site and connect your Atlassian account. +* [Connecting Linear to your factory](/factories/integrations/linear/) - The other issue tracker a factory can connect. diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx index ce7367791..250855553 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -1,5 +1,5 @@ --- -title: Connect Linear to your factory +title: Connecting Linear to your factory description: >- Connect Linear to your factory so planned issues flow in automatically and progress flows back to the issue. @@ -16,7 +16,7 @@ When the factory needs an answer, reply in Linear, or open the live run to steer * **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. +* **Code host access** - Repository access comes from the factory's connected code host ([GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), or [Azure DevOps](/factories/integrations/azure-devops/)), not from Linear. The factory needs it to change code or create a pull request. For workspace-level installation, reconnection, and removal steps, see the [Linear integration setup guide](/platform/integrations/linear/). @@ -82,3 +82,10 @@ Connecting Linear doesn't grant repository access. Branches and pull requests us * **An event doesn't start work** - Confirm the automation is enabled, the event type matches, and every filter matches the issue's current values or the state change. * **One action starts multiple runs** - Look for overlapping agent-session and comment triggers, then narrow or remove one. * **No pull request appears** - Check the factory's code-host credentials and repository access. Linear authorization alone doesn't allow code changes. + +## Related pages + +* [Connect your factory](/factories/connect-your-factory/) - Every other way to route work into the factory. +* [Factory automations](/factories/automations/) - How triggers and filters decide which Linear activity starts work. +* [Linear integration](/platform/integrations/linear/) - Install, reconnect, or remove the Warp app for your Linear workspace. +* [Connecting Jira to your factory](/factories/integrations/jira/) - The other issue tracker a factory can connect. diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index 9fcdcf3e9..c72771660 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -1,5 +1,5 @@ --- -title: Connect Slack to your factory +title: Connecting Slack to your factory description: >- Connect Slack to your factory so your team can start work with mentions, direct messages, and automations, and get results back in the same thread. @@ -27,11 +27,11 @@ Each factory appears in Slack as its own app with the factory's name and avatar. Use a factory automation to start work from Slack activity automatically, without anyone mentioning the app, such as on every message in a triage channel or on a specific emoji reaction. Add a **Slack** trigger to an automation and pick one of these events. To learn how to edit those filters, see [Automations](/factories/automations/#edit-filters-on-an-automation). -- **App mentioned** - Filter by joined conversations, authors, and keywords. -- **Direct message received** (`message_dm`) - Filter by direct-message conversations, authors, and keywords. -- **Message posted in channel** - Filter by joined conversations, authors, and keywords. -- **Reaction added** - Filter by conversations, reactors, keywords, emoji, and reacted-message authors. -- **Member joined channel** - Filter by conversations and members. +* **App mentioned** - Filter by joined conversations, authors, and keywords. +* **Direct message received** - Filter by direct-message conversations, authors, and keywords. +* **Message posted in channel** - Filter by joined conversations, authors, and keywords. +* **Reaction added** - Filter by conversations, reactors, keywords, emoji, and reacted-message authors. +* **Member joined channel** - Filter by conversations and members. For the exact `event` value each of these triggers uses in a definition file, see [triggers](/factories/factory-as-code/#triggers). @@ -117,15 +117,20 @@ Work started by an automation runs as the factory agent you chose for it, not as ## Troubleshooting and reconnection -- **The app doesn't acknowledge a request** - Confirm Slack is connected for that factory, that you mentioned the right factory's app, and that the app is in the channel. -- **A channel is missing from an automation** - Invite the app to that channel, then reload the **Conversations** picker. -- **Installation is pending** - Ask a Slack workspace administrator to approve the app, then finish the installation. -- **Two runs start for one mention** - Remove or narrow overlapping app-mention and channel-message triggers. +* **The app doesn't acknowledge a request** - Confirm Slack is connected for that factory, that you mentioned the right factory's app, and that the app is in the channel. +* **A channel is missing from an automation** - Invite the app to that channel, then reload the **Conversations** picker. +* **Installation is pending** - Ask a Slack workspace administrator to approve the app, then finish the installation. +* **Two runs start for one mention** - Remove or narrow overlapping app-mention and channel-message triggers. -To disconnect Slack, either delete the factory — which removes its Slack app along with it — or [remove the app from your Slack workspace](https://slack.com/help/articles/360003125231-Remove-apps-and-custom-integrations-from-your-workspace), which stops new Slack requests reaching that factory. To reconnect afterward, click **Add to Slack** in factory setup again. - -To route work into the factory from other tools, see [Connect your factory](/factories/connect-your-factory/). +To disconnect Slack, delete the factory, which removes its Slack app, or [remove the app from your Slack workspace](https://slack.com/help/articles/360003125231-Remove-apps-and-custom-integrations-from-your-workspace), which stops new Slack requests reaching that factory. To reconnect afterward, click **Add to Slack** in factory setup again. ## Privacy The factory's app reads messages only where it's mentioned, directly messaged, or subscribed by an automation you configured. Message content and supported attachments are used to run the factory's work, and your Slack profile email is used to map you to your Warp account. Data is handled per the [Warp Privacy Policy](https://www.warp.dev/privacy). + +## Related pages + +* [Connect your factory](/factories/connect-your-factory/) - Every other way to route work into the factory. +* [Factory automations](/factories/automations/) - How triggers and filters decide which Slack activity starts work. +* [Connecting Microsoft Teams to your factory](/factories/integrations/teams/) - The other chat intake path for factories. +* [How Warp Factories work](/factories/how-factories-work/) - What happens to a request after the factory picks it up. diff --git a/src/content/docs/factories/integrations/teams.mdx b/src/content/docs/factories/integrations/teams.mdx index 139205348..956a82759 100644 --- a/src/content/docs/factories/integrations/teams.mdx +++ b/src/content/docs/factories/integrations/teams.mdx @@ -1,5 +1,5 @@ --- -title: Connect Microsoft Teams to your factory +title: Connecting Microsoft Teams to your factory description: >- Connect Microsoft Teams to your factory so mentions in standard and shared channels start work and results post back in the same thread. @@ -49,7 +49,7 @@ Automation-started work runs as the factory agent selected in that automation. T ## Choose what starts work -Connect Microsoft Teams in the UI, then edit the seeded **teams-app-mentions** automation. Its **App mentioned** trigger starts work only when someone mentions **@Warp**, the default for general-purpose channels. +Connect Microsoft Teams in the UI, then edit the default **teams-app-mentions** automation. Its **App mentioned** trigger starts work only when someone mentions **@Warp**, the right default for general-purpose channels. Use **Message posted in channel** when every matching message in a dedicated standard channel should start work without a mention. In the automation editor, choose exactly one team and at least one standard channel. You can narrow either event with keywords; definition files can also filter by author. @@ -80,7 +80,7 @@ These tools are separate from [configured MCP servers](/platform/mcp/). They can ## Configure Microsoft Teams as code -Prefer the UI setup above, then edit the seeded **teams-app-mentions** automation. The seeded file already contains the correct team and channel IDs. +Prefer the UI setup above, then edit the default **teams-app-mentions** automation. Its file already contains the correct team and channel IDs. ```yaml title="factory.yaml" integrations: @@ -113,7 +113,7 @@ The two events have these definition-file values: Each trigger requires one Microsoft Graph team UUID in `team_ids` and one or more Bot Framework channel conversation IDs in `channel_ids`. Channel IDs use the `19:…@thread.tacv2` form. These filters are inclusion lists only. -For UI-selected teams and standard channels, copy these values from the seeded automation. You can also read them from the factory Microsoft Teams list-teams and list-channels API response fields named `id`. For a shared channel, copy its channel conversation ID from the Teams link or Microsoft Graph, then add it to `channel_ids`. +For UI-selected teams and standard channels, copy these values from the default automation. For a shared channel, copy its channel conversation ID from the Teams link or Microsoft Graph, then add it to `channel_ids`. Optional `keywords` and `user_ids` filters narrow matching by message content and author. @@ -139,7 +139,7 @@ The factory's app uses message content and supported attachments from the channe ## Related pages -* [**Connect your factory**](/factories/connect-your-factory/) - Choose the sources that route work into the factory. -* [**Factory automations**](/factories/automations/) - Edit trigger filters and avoid overlapping Teams triggers. -* [**Factory definition**](/factories/factory-as-code/) - Declare `microsoft-teams` and `teams` triggers as code. -* [**Slack**](/factories/integrations/slack/) - The other chat intake path for factories. +* [Connect your factory](/factories/connect-your-factory/) - Choose the sources that route work into the factory. +* [Factory automations](/factories/automations/) - Edit trigger filters and avoid overlapping Teams triggers. +* [Factory definition syntax](/factories/factory-as-code/) - Declare the `microsoft-teams` integration and `teams` triggers as code. +* [Connecting Slack to your factory](/factories/integrations/slack/) - The other chat intake path for factories. diff --git a/src/content/docs/factories/measure-and-improve.mdx b/src/content/docs/factories/measure-and-improve.mdx index 191b1479d..eb428c073 100644 --- a/src/content/docs/factories/measure-and-improve.mdx +++ b/src/content/docs/factories/measure-and-improve.mdx @@ -25,9 +25,9 @@ The **Dashboard** page shows activity, cost, autonomy, and evaluation results: | **Total runs** | All agent runs, with breakdowns by agent type, status, source, model, and more. | | **PRs opened** | Pull requests created from factory work, counted once, in the period they were first observed. | | **PRs merged** | Of the PRs opened in a period, how many later merged. Opened and merged draw from different data sources, so a period's merged count can occasionally read higher than its opened count for that period. | -| **Autonomy** | The share of the factory's merged PRs that needed no human code push before merging. Opening the PR counts as a push, so a human-authored PR that a factory run later revised doesn't count as autonomous. | -| **PR cycle time** | The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with a median for each stage. | -| **Cost per PR** | The median cost of PRs opened in the range, split evenly across a run's PRs when one run produces more than one. View it broken down by cost component or by PR size (S/M/L/XL, split at 100/500/1,000 changed lines). | +| **Autonomy** | The share of the factory's merged PRs that needed no human code push before merging. Opening the PR counts as a push, so a human-authored PR that a factory run later revised doesn't count as autonomous. Comments, reviews, requested changes, and the merge itself don't count as a push. | +| **PR cycle time** | The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with an independent median for each stage. The stage medians don't sum to the headline. | +| **Cost per PR** | The median cost of PRs opened in the range, split evenly across a run's PRs when one run produces more than one. View it broken down by cost component or by PR size: S, M, L, or XL, split at 100, 500, and 1,000 changed lines. | | **Most expensive PRs** | The highest-cost pull requests. | | **Scorer cards** | Results from your Scorers. | | **Self-improvement PRs** | The three newest Self-improvement pull requests, regardless of the selected date range. | @@ -35,22 +35,22 @@ The **Dashboard** page shows activity, cost, autonomy, and evaluation results: **Cost per PR** is an estimate, not a billing figure: it counts recorded credits and can undercount actual usage. :::caution -**PRs merged**, **Autonomy**, **PR cycle time**, and the detail in **Most expensive PRs** require a connected code host - the GitHub App, or the GitLab webhook Warp installs when you [connect GitLab](/factories/integrations/gitlab/) - and only cover activity from after you connect it. A PR's cost, creator, source, and requested model come from the run itself, so those still show without that connection. +**PRs merged**, **Autonomy**, **PR cycle time**, and the detail in **Most expensive PRs** require a connected code host (the GitHub App, or the GitLab webhook Warp installs when you [connect GitLab](/factories/integrations/gitlab/)) and only cover activity from after you connect it. A PR's cost, creator, source, and requested model come from the run itself, so those still show without that connection. ::: Use the **Dashboard** page to pick which runs to investigate, not to conclude what caused a change. **Total runs** includes evaluation, benchmark, and Self-improvement runs, so a higher run count with a flat PR count could mean harder tasks, retries, or measurement activity. ## Configure Scorers -A **Scorer** uses an LLM judge to classify completed runs against criteria you write — for example, "did the agent run the tests before opening a PR?" See [Configuring Scorers](/factories/measure-and-improve/scorers/) for its fields and how automatic and on-demand scoring work. +A **Scorer** uses an LLM judge to classify completed runs against criteria you write, such as "did the agent run the tests before opening a PR?" Every factory starts with a set of default Scorers. See [configuring Scorers](/factories/measure-and-improve/scorers/) for the defaults, the fields, and how automatic and on-demand scoring work. ## Compare configurations with benchmarks -A benchmark compares model and runner configurations for a single agent on the same fixed tasks. Use it to test a configuration change before you apply it to production. See [benchmarking factory agent configurations](/factories/benchmarks/) for the workflow. +A benchmark compares model, harness, and runner configurations for a single agent on the same fixed tasks. Use it to test a configuration change before you apply it to production. See [factory benchmarks](/factories/benchmarks/) for the workflow. ## Configure and review Self-improvement -**Self-improvement** turns a Scorer's repeated failures into follow-up pull requests, against application code or the factory's own definition. See [Configuring and reviewing Self-improvement](/factories/measure-and-improve/self-improvement/) for how to turn it on and review its pull requests. +**Self-improvement** turns a Scorer's repeated failures into follow-up pull requests, against application code or the factory's own definition. See [configuring and reviewing Self-improvement](/factories/measure-and-improve/self-improvement/) for how to turn it on and review its pull requests. ## Run a practical improvement loop @@ -79,5 +79,5 @@ flowchart LR * [Configuring Scorers](/factories/measure-and-improve/scorers/) - What a Scorer is, its fields, and how it runs. * [Configuring and reviewing Self-improvement](/factories/measure-and-improve/self-improvement/) - Turn on Self-improvement and review its pull requests. -* [Benchmarking factory agent configurations](/factories/benchmarks/) - Compare model and runner configurations on the same tasks. -* [Definitions as code](/factories/factory-as-code/) - Record an adopted change so your team can review the factory configuration. +* [Factory benchmarks](/factories/benchmarks/) - Compare model, harness, and runner configurations on the same tasks. +* [Factory definition syntax](/factories/factory-as-code/) - Record an adopted change so your team can review the factory configuration. diff --git a/src/content/docs/factories/measure-and-improve/scorers.mdx b/src/content/docs/factories/measure-and-improve/scorers.mdx index 56f0a8839..2bbd7065b 100644 --- a/src/content/docs/factories/measure-and-improve/scorers.mdx +++ b/src/content/docs/factories/measure-and-improve/scorers.mdx @@ -7,9 +7,13 @@ sidebar: label: "Scorers" --- -A **Scorer** is an LLM-based evaluation, or eval, that checks whether completed runs from selected agents meet criteria you define. For example, it can check, "Did the agent run the tests before opening a pull request?" A Scorer assigns a classification, not a numeric grade, so keep each one focused on a question its failures can point back to. Create Scorers on the factory dashboard's **Scorers** page, which also holds each Scorer's results. For Scorers defined as files in a factory definition, see the [`scorers//scorer.md` syntax](/factories/factory-as-code/#scorersnamescorermd) and the two scorers in [`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. +A **Scorer** is an LLM-based evaluation that checks whether completed runs from selected agents meet criteria you define. For example, it can check, "Did the agent run the tests before opening a pull request?" A Scorer assigns a classification, not a numeric grade, so keep each one focused on a question its failures can point back to. -Configure these fields: +Every new factory starts with default Scorers: **Code Quality** for the implement agent, and **Efficiency**, **Task Compliance**, **Procedure Compliance**, and **Verbosity** for every agent. Each samples a tenth of the runs from its agents. Edit or delete them, or set their sample rate to 0, like any Scorer you create. + +Create and edit Scorers on the factory dashboard's **Scorers** page, which also holds each Scorer's results. For Scorers defined as files in a factory definition, see the [`scorers//scorer.md` syntax](/factories/factory-as-code/#scorersnamescorermd) and the two scorers in [`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. + +Each Scorer has these fields: * **Agent(s) to evaluate** - The agents this Scorer applies to. Select at least one. * **Judge instructions** - The criteria the judge checks for. @@ -24,9 +28,8 @@ With a sample rate above 0%, the Scorer automatically evaluates sampled runs aft You can also score any single run on demand, which is useful for testing new judge instructions before raising the sample rate. Scoring a run again replaces its previous result from that Scorer. - ## Related pages * [Measure and improve a factory](/factories/measure-and-improve/) - Read dashboard metrics and run a practical improvement loop. * [Configuring and reviewing Self-improvement](/factories/measure-and-improve/self-improvement/) - Turn repeated Scorer failures into follow-up pull requests. -* [Benchmarking factory agent configurations](/factories/benchmarks/) - Compare model and runner configurations on the same tasks. +* [Factory benchmarks](/factories/benchmarks/) - Compare model, harness, and runner configurations on the same tasks. diff --git a/src/content/docs/factories/measure-and-improve/self-improvement.mdx b/src/content/docs/factories/measure-and-improve/self-improvement.mdx index 532f84a13..949675bcd 100644 --- a/src/content/docs/factories/measure-and-improve/self-improvement.mdx +++ b/src/content/docs/factories/measure-and-improve/self-improvement.mdx @@ -23,4 +23,4 @@ The factory dashboard's **Self-improvement** page lists the pull requests these * [Measure and improve a factory](/factories/measure-and-improve/) - Read dashboard metrics and run a practical improvement loop. * [Configuring Scorers](/factories/measure-and-improve/scorers/) - Define the criteria whose failures Self-improvement investigates. -* [Benchmarking factory agent configurations](/factories/benchmarks/) - Compare model and runner configurations on the same tasks. +* [Factory benchmarks](/factories/benchmarks/) - Compare model, harness, and runner configurations on the same tasks. diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 5bca3ec50..29ab414db 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -14,7 +14,7 @@ Create a factory and take one small work item from prompt to pull request in abo * **A Warp account and team** - Get started with Warp, then join or create the team that will own the factory. * **Permission to create factories** - You need a team or workspace admin role, or the team-level Warp Factories Editor role. See [factory roles and permissions](/factories/infrastructure-and-security/#factory-roles-and-permissions). -* **Available team usage** - The factory's agents consume the team's [credits](/support-and-community/plans-and-billing/platform-credits/). +* **Team credits** - The factory's agents consume the team's [credits](/support-and-community/plans-and-billing/platform-credits/). * **Repository access** - Authorize GitHub, GitLab, or Azure DevOps during setup. Restricted organizations need owner approval. Azure DevOps also requires [one-time administrator approval](/factories/integrations/azure-devops/#requirements). ## Set up your factory @@ -89,10 +89,13 @@ Send work from Slack or an issue tracker. If you skipped integrations, start a r
A factory Slack thread with live progress.
-3. When the Implement agent finishes, review and merge the linked pull request as you would any other. +3. When the implement agent finishes, review and merge the linked pull request as you would any other. ## Next steps -* [**Connect your factory**](/factories/connect-your-factory/) - Configure intake sources. -* [**How Warp Factories work**](/factories/how-factories-work/) - Understand the work-item lifecycle. -* [**Troubleshooting Warp Factories**](/factories/troubleshooting/) - Fix common setup and run issues. +You have a factory connected to your repositories and a first pull request from it. + +* [Connect your factory](/factories/connect-your-factory/) - Route work in from Slack, your issue tracker, webhooks, and schedules. +* [How Warp Factories work](/factories/how-factories-work/) - The stages a work item moves through and where your team decides. +* [Factory agents](/factories/factory-agents/) - Tune each agent's instructions, model, and harness. +* [Troubleshooting Warp Factories](/factories/troubleshooting/) - Fix setup problems and work that doesn't start. diff --git a/src/content/docs/factories/runners.mdx b/src/content/docs/factories/runners.mdx index 2a60395e8..0abc742e5 100644 --- a/src/content/docs/factories/runners.mdx +++ b/src/content/docs/factories/runners.mdx @@ -15,7 +15,7 @@ A runner is a reusable compute configuration. Where an [environment](/platform/e ## 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. +Set a factory's default runner in `agentDefaults.runner`, then override it per agent or automation when the work needs different compute. For a GitHub-backed factory, edit `runners/*.yaml` in the definition repository. For a Warp-managed factory, edit the runner files in the factory dashboard. :::note Most runs don't need a custom runner. Every environment has a default runner, and Warp picks a sensible default shape when you don't specify one. Create a runner when you need a specific OS, architecture, instance size, or sandbox image. @@ -25,18 +25,18 @@ Most runs don't need a custom runner. Every environment has a default runner, an What runners give you: -* **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. -* **Flexible OS targets** – Run agents on Linux or macOS. -* **Independent of environments** – Override an environment's default runner per run without changing the environment itself. +* **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. +* **Flexible OS targets** - Run agents on Linux or macOS. +* **Independent of environments** - Override an environment's default runner per run without changing the environment itself. ## 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 on the runner's shape, then prepares the workspace defined by the environment (cloning repos and executing setup commands) before the agent begins. -* **Environment** – Defines the workspace: Docker image, repositories, and setup commands. See [Environments](/platform/environments/). -* **Runner** – Defines the compute: OS, architecture, instance shape (vCPUs and memory), and sandbox image. -* **Host** – Determines where execution happens (Warp-hosted or [self-hosted](/factories/self-hosting/) infrastructure). +* **Environment** - Defines the workspace: Docker image, repositories, and setup commands. See [Environments](/platform/environments/). +* **Runner** - Defines the compute: OS, architecture, instance shape (vCPUs and memory), and sandbox image. +* **Host** - Determines where execution happens (Warp-hosted or [self-hosted](/factories/self-hosting/) infrastructure). Each environment has a default runner. Specifying a runner for a run overrides that default for that run only. @@ -90,16 +90,16 @@ oz runner create \ Key flags: -* `--name` (`-n`) — human-readable label for the runner (required). -* `--description` (`-d`) — optional description (max 240 characters). -* `--os` — target operating system, `linux` (default) or `macos`. -* `--arch` — CPU architecture: `auto` (default), `x86-64`, or `aarch64`. `auto` uses the OS default (x86-64 on Linux, 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. +* `--name` (`-n`) - Human-readable label for the runner (required). +* `--description` (`-d`) - Optional description (max 240 characters). +* `--os` - Target operating system, `linux` (default) or `macos`. +* `--arch` - CPU architecture: `auto` (default), `x86-64`, or `aarch64`. `auto` uses the OS default (x86-64 on Linux, 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` or `--personal` - Create the runner at the team level or 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`. @@ -128,7 +128,7 @@ oz runner update --name "new name" oz runner update --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. ### Delete a runner @@ -150,6 +150,6 @@ You can also select a runner when [running orchestrated agents](/platform/orches ## Related pages -* [Environments](/platform/environments/) – Define the repos, image, and setup commands an agent works with. -* [Managing cloud agents](/platform/managing-cloud-agents/) – Start, monitor, and manage cloud agent runs. -* [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/) – Full command-line reference for runners and every other cloud agent command. +* [Environments](/platform/environments/) - Define the repos, image, and setup commands an agent works with. +* [Managing cloud agents](/platform/managing-cloud-agents/) - Start, monitor, and manage cloud agent runs. +* [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/) - Full command-line reference for runners and every other cloud agent command. diff --git a/src/content/docs/factories/self-hosting/index.mdx b/src/content/docs/factories/self-hosting/index.mdx index 25facef4e..31ac01715 100644 --- a/src/content/docs/factories/self-hosting/index.mdx +++ b/src/content/docs/factories/self-hosting/index.mdx @@ -39,11 +39,11 @@ Use the [unmanaged architecture](/platform/unmanaged-execution/) when any of the Use the managed architecture when the {VARS.WARP_AUTOMATION_PLATFORM} should accept the trigger and route the run. Then choose a backend: -* **[Docker backend](/factories/self-hosting/managed-docker/)** - Use the default backend when Docker is available. Each task runs in a container. -* **[Kubernetes backend](/factories/self-hosting/managed-kubernetes/)** - Use an existing cluster to run each task as a Kubernetes Job. -* **[Direct backend](/factories/self-hosting/managed-direct/)** - Run tasks on the worker host when a container runtime is unavailable or host access is required. -* **[Command backend](/factories/self-hosting/external-orchestrators/#using-the-command-backend)** - Keep a worker connected and dispatch each task to an external job API, queue, or runtime. -* **[One-shot Direct](/factories/self-hosting/external-orchestrators/#using-one-shot-direct)** - Let an external scheduler allocate a host and start one Direct worker for one task. +* [Docker backend](/factories/self-hosting/managed-docker/) - Use the default backend when Docker is available. Each task runs in a container. +* [Kubernetes backend](/factories/self-hosting/managed-kubernetes/) - Use an existing cluster to run each task as a Kubernetes Job. +* [Direct backend](/factories/self-hosting/managed-direct/) - Run tasks on the worker host when a container runtime is unavailable or host access is required. +* [Command backend](/factories/self-hosting/external-orchestrators/#using-the-command-backend) - Keep a worker connected and dispatch each task to an external job API, queue, or runtime. +* [One-shot Direct](/factories/self-hosting/external-orchestrators/#using-one-shot-direct) - Let an external scheduler allocate a host and start one Direct worker for one task. ## Managed prerequisites diff --git a/src/content/docs/factories/self-hosting/managed-direct.mdx b/src/content/docs/factories/self-hosting/managed-direct.mdx index 91b9e42cd..9b1cda2b7 100644 --- a/src/content/docs/factories/self-hosting/managed-direct.mdx +++ b/src/content/docs/factories/self-hosting/managed-direct.mdx @@ -8,7 +8,7 @@ sidebar: --- import { VARS } from '@data/vars'; -Run the `oz-agent-worker` daemon with the **Direct backend** — tasks execute directly on the worker host without Docker or Kubernetes. The {VARS.WARP_AUTOMATION_PLATFORM} still orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); the worker just runs the agent in a per-task workspace on its own filesystem. +Run the `oz-agent-worker` daemon with the **Direct backend** to execute tasks directly on the worker host without Docker or Kubernetes. The {VARS.WARP_AUTOMATION_PLATFORM} still orchestrates runs end to end from Slack, Linear, schedules, the API, or `oz agent run-cloud`; the worker runs the agent in a per-task workspace on its own filesystem. ## When to use the Direct backend @@ -20,8 +20,6 @@ Run the `oz-agent-worker` daemon with the **Direct backend** — tasks execute d The Direct backend does not provide per-task container isolation. Each task runs in an isolated workspace directory, but shares the host OS and kernel. Evaluate whether this fits your security requirements before using it in production. ::: ---- - ## How it works 1. The worker creates a per-task workspace directory under `workspace_root`. @@ -29,8 +27,6 @@ The Direct backend does not provide per-task container isolation. Each task runs 3. The `oz` CLI runs the agent task inside the workspace directory. 4. After the task completes, the optional `teardown_command` runs and the workspace is cleaned up. ---- - ## Prerequisites Complete the shared [managed prerequisites](/factories/self-hosting/#managed-prerequisites), then prepare: @@ -39,8 +35,6 @@ Complete the shared [managed prerequisites](/factories/self-hosting/#managed-pre * **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). ---- - ## Setup ### 1. Set your API key @@ -70,8 +64,6 @@ backend: **Expected outcome:** The worker connects to the {VARS.WARP_AUTOMATION_PLATFORM} and begins listening for tasks. Each assigned task runs in a freshly-created subdirectory of `workspace_root`. ---- - ## Workspace model Each task gets its own directory under `workspace_root`. The default is `/var/lib/oz/workspaces`; override it with the `workspace_root` config option shown above. @@ -82,23 +74,19 @@ To reuse a large monorepo without sharing one checkout between concurrent tasks, Setting `target_dir` makes every task run in one shared directory and disables per-task workspace isolation. Use it only when the worker processes one task at a time. ---- - ## Setup and teardown commands The `setup_command` runs before each task and receives the following environment variables: -* `OZ_WORKSPACE_ROOT` — The workspace directory for the task. -* `OZ_RUN_ID` — The unique task ID. -* `OZ_ENVIRONMENT_FILE` — Path to a file where the setup script can write additional `KEY=VALUE` environment variables to inject into the task. -* `OZ_WORKER_BACKEND` — Always set to `direct`. +* `OZ_WORKSPACE_ROOT` - The workspace directory for the task. +* `OZ_RUN_ID` - The unique task ID. +* `OZ_ENVIRONMENT_FILE` - Path to a file where the setup script can write additional `KEY=VALUE` environment variables to inject into the task. +* `OZ_WORKER_BACKEND` - Always set to `direct`. The `teardown_command` runs after each task and receives `OZ_WORKSPACE_ROOT`, `OZ_RUN_ID`, and `OZ_WORKER_BACKEND`. Use the setup command to clone repos, install dependencies, or write task-specific env vars into `OZ_ENVIRONMENT_FILE`. Use the teardown command for cleanup or reporting. ---- - ## Environment variables for Direct tasks :::note @@ -121,14 +109,12 @@ backend: value: "hello" ``` ---- - ## Related pages -* [Self-hosted worker reference](/factories/self-hosting/reference/#direct-backend-config) — Full config schema for the Direct backend. -* [External orchestrators](/factories/self-hosting/external-orchestrators/) — Start one Direct worker per external job or delegate runs through the Command backend. -* [Direct backend monorepo worktrees](/factories/self-hosting/direct-monorepo-worktrees/) — Create and remove one Git worktree per task with setup and teardown hooks. -* [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and the backend decision guide. -* [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. -* [Security and networking](/platform/execution-security/) — Data boundaries and security considerations for the Direct backend. -* [Troubleshooting](/factories/self-hosting/troubleshooting/#direct-backend) — Common Direct-backend issues. +* [Self-hosted worker reference](/factories/self-hosting/reference/#direct-backend-config) - Full config schema for the Direct backend. +* [External orchestrators](/factories/self-hosting/external-orchestrators/) - Start one Direct worker per external job or delegate runs through the Command backend. +* [Direct backend monorepo worktrees](/factories/self-hosting/direct-monorepo-worktrees/) - Create and remove one Git worktree per task with setup and teardown hooks. +* [Self-hosting overview](/factories/self-hosting/) - Managed vs unmanaged and the backend decision guide. +* [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) - How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. +* [Security and networking](/platform/execution-security/) - Data boundaries and security considerations for the Direct backend. +* [Troubleshooting](/factories/self-hosting/troubleshooting/#direct-backend) - Common Direct-backend issues. diff --git a/src/content/docs/factories/self-hosting/managed-docker.mdx b/src/content/docs/factories/self-hosting/managed-docker.mdx index 44128cd83..b10018b02 100644 --- a/src/content/docs/factories/self-hosting/managed-docker.mdx +++ b/src/content/docs/factories/self-hosting/managed-docker.mdx @@ -8,7 +8,7 @@ sidebar: --- import { VARS } from '@data/vars'; -Run the `oz-agent-worker` daemon with the **Docker backend** — the default managed path. Each agent task runs in an isolated Docker container spawned from the worker, with full orchestration by the {VARS.WARP_AUTOMATION_PLATFORM} (Slack, Linear, schedules, API, `oz agent run-cloud`). +Run the `oz-agent-worker` daemon with the **Docker backend**, the default managed path. Each agent task runs in an isolated Docker container spawned from the worker, and the {VARS.WARP_AUTOMATION_PLATFORM} orchestrates the runs from Slack, Linear, schedules, the API, or `oz agent run-cloud`. ## When to use the Docker backend @@ -16,8 +16,6 @@ Run the `oz-agent-worker` daemon with the **Docker backend** — the default man * You want per-task isolation without running a Kubernetes cluster. * You're not already deploying workloads into Kubernetes. ---- - ## Prerequisites Complete the shared [managed prerequisites](/factories/self-hosting/#managed-prerequisites), then prepare: @@ -36,8 +34,6 @@ docker info **Expected outcome:** `docker info` prints daemon details without errors. ---- - ## Set your API key Export your self-hosted worker API key so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}: @@ -97,8 +93,6 @@ Once started, the worker connects to the {VARS.WARP_AUTOMATION_PLATFORM}, waits You can run multiple workers with the same `--worker-id` for redundancy — the {VARS.WARP_AUTOMATION_PLATFORM} distributes tasks across connected workers. ---- - ## Docker backend configuration The worker can take configuration either via CLI flags or via a YAML [config file](/factories/self-hosting/reference/#config-file). CLI flags take precedence over config file values. @@ -154,8 +148,6 @@ backend: Pass it with `--config-file config.yaml`. See the [self-hosted worker reference](/factories/self-hosting/reference/) for the full flag and config schema. ---- - ## Docker connectivity The worker uses the standard Docker client discovery mechanism to find the Docker daemon. @@ -169,9 +161,9 @@ The published worker image runs as a non-root user. When you mount a rootful Lin Additional Docker environment variables the worker respects: -* `DOCKER_API_VERSION` — Specify Docker API version. -* `DOCKER_CERT_PATH` — Path to TLS certificates. -* `DOCKER_TLS_VERIFY` — Enable TLS verification. +* `DOCKER_API_VERSION` - Specify Docker API version. +* `DOCKER_CERT_PATH` - Path to TLS certificates. +* `DOCKER_TLS_VERIFY` - Enable TLS verification. **Example: Connecting to a remote Docker daemon** @@ -182,8 +174,6 @@ export DOCKER_CERT_PATH="/path/to/certs" oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` ---- - ## Private Docker registries The Docker backend reads task-image credentials from its Docker config. See the [private-registry Docker setup](/factories/self-hosting/private-container-registry/#configuring-the-docker-backend) for sidecar images and authenticated-registry limitations. @@ -221,19 +211,15 @@ docker run \ To mirror the worker and sidecar images as well as task images, see [Pulling self-hosted images from a private registry](/factories/self-hosting/private-container-registry/). ---- - ## Routing runs to this worker Once your Docker worker is connected, route tasks to it with `--host ""`. Routing is the same across all managed backends — see [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) for CLI, scheduled, integration, API, and web UI examples. ---- - ## Related pages -* [Self-hosting quickstart](/factories/self-hosting/quickstart/) — ~10-minute path to a running Docker worker. -* [Self-hosted worker reference](/factories/self-hosting/reference/) — Full CLI flag and config file schema. -* [Environments](/platform/environments/) — Define the Docker image, repos, and setup commands for tasks. -* [Private container registry](/factories/self-hosting/private-container-registry/) — Mirror worker and task images and configure private-registry pulls. -* [Security and networking](/platform/execution-security/) — Data boundaries, egress, and Docker socket considerations. -* [Troubleshooting](/factories/self-hosting/troubleshooting/) — Common issues with the Docker backend. +* [Self-hosting quickstart](/factories/self-hosting/quickstart/) - ~10-minute path to a running Docker worker. +* [Self-hosted worker reference](/factories/self-hosting/reference/) - Full CLI flag and config file schema. +* [Environments](/platform/environments/) - Define the Docker image, repos, and setup commands for tasks. +* [Private container registry](/factories/self-hosting/private-container-registry/) - Mirror worker and task images and configure private-registry pulls. +* [Security and networking](/platform/execution-security/) - Data boundaries, egress, and Docker socket considerations. +* [Troubleshooting](/factories/self-hosting/troubleshooting/) - Common issues with the Docker backend. diff --git a/src/content/docs/factories/self-hosting/managed-kubernetes.mdx b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx index b5865a123..298016e76 100644 --- a/src/content/docs/factories/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx @@ -16,8 +16,6 @@ Deploy the `oz-agent-worker` daemon into a Kubernetes cluster with the included * You need Kubernetes-native scheduling, resource management, or policy enforcement. * You want to use Kubernetes Secrets, ServiceAccounts, and admission policies to control task behavior. ---- - ## How it works 1. The worker connects to the Kubernetes API server (using in-cluster auth by default, or an explicit kubeconfig). @@ -26,8 +24,6 @@ Deploy the `oz-agent-worker` daemon into a Kubernetes cluster with the included 4. The worker monitors the Job and Pod status. 5. After the task completes, the worker removes successful Jobs. Failed Jobs remain available for diagnosis for 24 hours by default. ---- - ## Prerequisites Complete the shared [managed prerequisites](/factories/self-hosting/#managed-prerequisites), then prepare: @@ -35,11 +31,9 @@ Complete the shared [managed prerequisites](/factories/self-hosting/#managed-pre * **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. +* [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/). ---- - ## Install with the Helm chart The `oz-agent-worker` repository includes a namespace-scoped Helm chart at `charts/oz-agent-worker`. This is the recommended way to deploy the worker into a cluster. @@ -99,56 +93,52 @@ Set `image.tag` explicitly to pin the worker image. Check the [oz-agent-worker r To scale horizontally, deploy multiple Helm releases with distinct worker IDs rather than increasing replicas on a single release. ---- - ## Key chart values **Required:** -* `worker.workerId` — The worker ID (same as `--worker-id`). -* `image.tag` — The worker image tag to deploy. +* `worker.workerId` - The worker ID (same as `--worker-id`). +* `image.tag` - The worker image tag to deploy. **Worker configuration:** -* `worker.logLevel` — Log verbosity (`debug`, `info`, `warn`, `error`). Defaults to `info`. -* `worker.cleanup` — Whether to clean up task Jobs after execution. Defaults to `true`. -* `worker.maxConcurrentTasks` — Maximum concurrent tasks. Defaults to `0` (unlimited). -* `worker.idleOnComplete` — Duration to keep the oz process alive after task completion. -* `worker.resources` — Resource requests/limits for the worker Deployment. Defaults to `100m` CPU and `128Mi` memory. -* `worker.livenessProbe` — Liveness probe for the worker Deployment. Defaults to an `exec` probe (`kill -0 1`). Override with a custom probe or set to `null` to disable. -* `worker.terminationGracePeriodSeconds` — Grace period for worker Deployment shutdown. Defaults to `30`. -* `worker.nodeSelector`, `worker.tolerations`, `worker.affinity` — Scheduling constraints for the worker Deployment pod. +* `worker.logLevel` - Log verbosity (`debug`, `info`, `warn`, `error`). Defaults to `info`. +* `worker.cleanup` - Whether to clean up task Jobs after execution. Defaults to `true`. +* `worker.maxConcurrentTasks` - Maximum concurrent tasks. Defaults to `0` (unlimited). +* `worker.idleOnComplete` - Duration to keep the oz process alive after task completion. +* `worker.resources` - Resource requests/limits for the worker Deployment. Defaults to `100m` CPU and `128Mi` memory. +* `worker.livenessProbe` - Liveness probe for the worker Deployment. Defaults to an `exec` probe (`kill -0 1`). Override with a custom probe or set to `null` to disable. +* `worker.terminationGracePeriodSeconds` - Grace period for worker Deployment shutdown. Defaults to `30`. +* `worker.nodeSelector`, `worker.tolerations`, `worker.affinity` - Scheduling constraints for the worker Deployment pod. **Kubernetes backend:** -* `kubernetesBackend.namespace` — Namespace for task Jobs. Defaults to the release namespace. -* `kubernetesBackend.defaultImage` — Default Docker image for task pods when no [Warp environment](/platform/environments/) has been supplied. Set it when all tasks use the same base image and you don't need a Warp environment. Leave empty (default) to fall back to `ubuntu:22.04`. -* `kubernetesBackend.imagePullPolicy` — Image pull policy for task pods. Defaults to `IfNotPresent`. -* `kubernetesBackend.useImageVolumes` — Use native Kubernetes image volumes instead of root init containers to materialize sidecars. Defaults to `false`. -* `kubernetesBackend.preflightImage` — Image for the startup preflight Job. Set this if your cluster restricts allowed registries. -* `kubernetesBackend.preflightResources` — CPU and memory requests and limits for preflight containers. -* `kubernetesBackend.sidecarImage` — Internal-registry override for the Warp agent sidecar image. -* `kubernetesBackend.unschedulableTimeout` — How long a pod may remain unschedulable before failing. Defaults to `30s`. -* `kubernetesBackend.setupCommand` — Shell command to run before each task. -* `kubernetesBackend.teardownCommand` — Shell command to run after each task. -* `kubernetesBackend.extraLabels` — Additional labels for task Jobs and Pods. -* `kubernetesBackend.extraAnnotations` — Additional annotations for task Jobs and Pods. -* `kubernetesBackend.activeDeadlineSeconds` — Maximum task Job lifetime. Defaults to eight hours. -* `kubernetesBackend.ttlSecondsAfterFinished` — Retention period for failed Jobs and Jobs orphaned by worker disruption. Defaults to 24 hours when cleanup is enabled. -* `kubernetesBackend.workspaceSizeLimit` — Size limit for workspace `emptyDir` volume. -* `kubernetesBackend.podTemplate` — Raw PodSpec YAML for task Jobs (same as `backend.kubernetes.pod_template` in the [config file](/factories/self-hosting/reference/#config-file)). +* `kubernetesBackend.namespace` - Namespace for task Jobs. Defaults to the release namespace. +* `kubernetesBackend.defaultImage` - Default Docker image for task pods when no [Warp environment](/platform/environments/) has been supplied. Set it when all tasks use the same base image and you don't need a Warp environment. Leave empty (default) to fall back to `ubuntu:22.04`. +* `kubernetesBackend.imagePullPolicy` - Image pull policy for task pods. Defaults to `IfNotPresent`. +* `kubernetesBackend.useImageVolumes` - Use native Kubernetes image volumes instead of root init containers to materialize sidecars. Defaults to `false`. +* `kubernetesBackend.preflightImage` - Image for the startup preflight Job. Set this if your cluster restricts allowed registries. +* `kubernetesBackend.preflightResources` - CPU and memory requests and limits for preflight containers. +* `kubernetesBackend.sidecarImage` - Internal-registry override for the Warp agent sidecar image. +* `kubernetesBackend.unschedulableTimeout` - How long a pod may remain unschedulable before failing. Defaults to `30s`. +* `kubernetesBackend.setupCommand` - Shell command to run before each task. +* `kubernetesBackend.teardownCommand` - Shell command to run after each task. +* `kubernetesBackend.extraLabels` - Additional labels for task Jobs and Pods. +* `kubernetesBackend.extraAnnotations` - Additional annotations for task Jobs and Pods. +* `kubernetesBackend.activeDeadlineSeconds` - Maximum task Job lifetime. Defaults to eight hours. +* `kubernetesBackend.ttlSecondsAfterFinished` - Retention period for failed Jobs and Jobs orphaned by worker disruption. Defaults to 24 hours when cleanup is enabled. +* `kubernetesBackend.workspaceSizeLimit` - Size limit for workspace `emptyDir` volume. +* `kubernetesBackend.podTemplate` - Raw PodSpec YAML for task Jobs (same as `backend.kubernetes.pod_template` in the [config file](/factories/self-hosting/reference/#config-file)). **API key Secret:** -* `warp.apiKeySecret.create` — Set to `true` to have the chart create a Secret from `warp.apiKeySecret.value`. Defaults to `false` (expects a pre-existing Secret). -* `warp.apiKeySecret.value` — The API key value to store in the chart-managed Secret. Only used when `warp.apiKeySecret.create` is `true`. -* `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`. +* `warp.apiKeySecret.create` - Set to `true` to have the chart create a Secret from `warp.apiKeySecret.value`. Defaults to `false` (expects a pre-existing Secret). +* `warp.apiKeySecret.value` - The API key value to store in the chart-managed Secret. Only used when `warp.apiKeySecret.create` is `true`. +* `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. ---- - ## Cluster selection Cluster selection follows Kubernetes client config conventions: @@ -159,8 +149,6 @@ Cluster selection follows Kubernetes client config conventions: `namespace` selects the namespace inside the chosen cluster. It defaults to `default` when omitted. ---- - ## Pod template The `pod_template` field accepts standard Kubernetes PodSpec YAML and is the declarative way to configure task pod scheduling, service accounts, image pull secrets, resources, and environment variables. @@ -199,35 +187,27 @@ The worker Deployment ServiceAccount needs RBAC to manage Jobs and Pods. The tas A run's instance shape overrides the `task` container's CPU and memory values in `pod_template`. ---- - ## Preflight check On startup, the worker runs a preflight Job to check RBAC and admission policy for the configured task PodSpec, including its sidecar-loading method. If preflight fails, the worker exits before accepting tasks. Passing preflight does not validate task-specific images, Secrets, setup commands, or network access. The preflight image defaults to `busybox:1.36`. For an allowlisted or private image, set `kubernetesBackend.preflightImage`. The `kubernetesBackend.podTemplate.imagePullSecrets` value supplies registry credentials to task and preflight Pods. ---- - ## Environment variables for Kubernetes tasks There are two ways to pass environment variables to Kubernetes task containers: -1. **`pod_template`** (recommended for Kubernetes-native config) — Use standard Kubernetes `env` syntax in the `task` container, including `valueFrom.secretKeyRef` for Kubernetes Secrets. -2. **`-e` / `--env` flags** — Backend-agnostic runtime overrides that work across all managed backends. +1. **`pod_template`** (recommended for Kubernetes-native config) - Use standard Kubernetes `env` syntax in the `task` container, including `valueFrom.secretKeyRef` for Kubernetes Secrets. +2. **`-e` / `--env` flags** - Backend-agnostic runtime overrides that work across all managed backends. When configuring the Kubernetes backend via YAML or Helm, declarative task-container env belongs in `pod_template` rather than a separate top-level list. For an external secrets manager, inject task secrets through a CSI driver or operator. Add the provider's `volumes`, `volumeMounts`, and annotations to `pod_template`. ---- - ## Setup and teardown commands Use `kubernetesBackend.setupCommand` (Helm value) or `backend.kubernetes.setup_command` ([config file](/factories/self-hosting/reference/#kubernetes-backend-config)) to run a shell command before each task. Use `teardownCommand` / `teardown_command` for cleanup after the task finishes. These run inside the task Pod and are useful for workspace bootstrapping or post-run reporting. ---- - ## Protect active task pods from disruption Terminating the worker pod normally leaves active task Jobs running. Evicting a task pod interrupts the run and deletes its pod-local `emptyDir` workspace. Configure node lifecycle tooling to avoid voluntary disruption of active task pods. @@ -246,8 +226,6 @@ A PodDisruptionBudget (PDB) constrains tools that use the Kubernetes Eviction AP For other node lifecycle tools, use the equivalent protection and verify which disruption paths bypass it. A replacement pod cannot resume an interrupted run. ---- - ## Plan capacity and scheduling Task pods need capacity for their configured requests before the worker's unschedulable timeout expires. @@ -258,8 +236,6 @@ Task pods need capacity for their configured requests before the worker's unsche * Use `worker.nodeSelector`, `worker.tolerations`, and `worker.affinity` for the worker Deployment. Use the equivalent fields in `kubernetesBackend.podTemplate` for task pods. * A toleration makes a pod eligible for a tainted node; it does not reserve capacity. Pair dedicated-node tolerations with matching selectors or affinity and autoscaler capacity. ---- - ## Metrics The Helm chart includes built-in support for exporting OpenTelemetry metrics from the worker. Enable metrics by setting `metrics.enabled=true`: @@ -278,24 +254,20 @@ To push metrics to an OTLP collector instead, set `metrics.exporter=otlp` and co See [Monitoring](/factories/self-hosting/monitoring/) for the full list of Helm values, the metric catalog, and sample PromQL queries. ---- - ## Operational notes -* **Scaling** — The chart always deploys a single replica for a given `worker.workerId`. To run multiple workers, deploy multiple Helm releases with distinct worker IDs rather than scaling a single release horizontally. -* **Security context** — The Deployment defaults to a non-root security context (`runAsUser: 10001`) with `allowPrivilegeEscalation: false` and all capabilities dropped. -* **Liveness probe** — The Deployment includes a default `exec` liveness probe (`kill -0 1`). Override `worker.livenessProbe` for a custom probe, or set it to `null` to disable. -* **In-cluster auth** — The chart assumes the worker runs inside the target cluster and uses in-cluster Kubernetes auth by default. - ---- +* **Scaling** - The chart always deploys a single replica for a given `worker.workerId`. To run multiple workers, deploy multiple Helm releases with distinct worker IDs rather than scaling a single release horizontally. +* **Security context** - The Deployment defaults to a non-root security context (`runAsUser: 10001`) with `allowPrivilegeEscalation: false` and all capabilities dropped. +* **Liveness probe** - The Deployment includes a default `exec` liveness probe (`kill -0 1`). Override `worker.livenessProbe` for a custom probe, or set it to `null` to disable. +* **In-cluster auth** - The chart assumes the worker runs inside the target cluster and uses in-cluster Kubernetes auth by default. ## Related pages -* [Self-hosted worker reference](/factories/self-hosting/reference/) — Full CLI flag and config file schema, including every Kubernetes backend field. -* [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and the backend decision guide. -* [Routing runs to this worker](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. -* [Environments](/platform/environments/) — Define the task image, repos, and setup commands. -* [Private container registry](/factories/self-hosting/private-container-registry/) — Mirror the images used by self-hosted workers into an internal registry. -* [Monitoring](/factories/self-hosting/monitoring/) — OpenTelemetry metrics, including Helm chart metrics values. -* [Security and networking](/platform/execution-security/) — RBAC, admission policies, and data boundaries. -* [Troubleshooting](/factories/self-hosting/troubleshooting/#kubernetes-backend) — Common Kubernetes-backend issues. +* [Self-hosted worker reference](/factories/self-hosting/reference/) - Full CLI flag and config file schema, including every Kubernetes backend field. +* [Self-hosting overview](/factories/self-hosting/) - Managed vs unmanaged and the backend decision guide. +* [Routing runs to this worker](/factories/self-hosting/#routing-runs-to-self-hosted-workers) - How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. +* [Environments](/platform/environments/) - Define the task image, repos, and setup commands. +* [Private container registry](/factories/self-hosting/private-container-registry/) - Mirror the images used by self-hosted workers into an internal registry. +* [Monitoring](/factories/self-hosting/monitoring/) - OpenTelemetry metrics, including Helm chart metrics values. +* [Security and networking](/platform/execution-security/) - RBAC, admission policies, and data boundaries. +* [Troubleshooting](/factories/self-hosting/troubleshooting/#kubernetes-backend) - Common Kubernetes-backend issues. diff --git a/src/content/docs/factories/self-hosting/monitoring.mdx b/src/content/docs/factories/self-hosting/monitoring.mdx index e3355c986..c55410922 100644 --- a/src/content/docs/factories/self-hosting/monitoring.mdx +++ b/src/content/docs/factories/self-hosting/monitoring.mdx @@ -12,26 +12,24 @@ The `oz-agent-worker` daemon exports [OpenTelemetry](https://opentelemetry.io/) ## Key features -* **Prometheus scrape** — Expose a `/metrics` endpoint for Prometheus to scrape, with optional `PodMonitor` support for the Prometheus Operator. -* **OTLP push** — Push metrics to any OpenTelemetry-compatible collector (Grafana Alloy, Datadog Agent, New Relic, etc.). -* **Standard configuration** — Select an exporter with [OpenTelemetry environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/). -* **Pre-seeded series** — Metric series appear at startup before any tasks run. +* **Prometheus scrape** - Expose a `/metrics` endpoint for Prometheus to scrape, with optional `PodMonitor` support for the Prometheus Operator. +* **OTLP push** - Push metrics to any OpenTelemetry-compatible collector (Grafana Alloy, Datadog Agent, New Relic, etc.). +* **Standard configuration** - Select an exporter with [OpenTelemetry environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/). +* **Pre-seeded series** - Metric series appear at startup before any tasks run. ## How it works The worker uses the [OpenTelemetry autoexport package](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/exporters/autoexport) to select an exporter at runtime based on the `OTEL_METRICS_EXPORTER` environment variable. Supported values: -* `prometheus` — Starts an in-process HTTP server serving `/metrics`. -* `otlp` — Pushes metrics over OTLP (HTTP/protobuf by default). -* `console` — Writes metrics to stdout (useful for debugging). -* `none` — Disables metrics export entirely. +* `prometheus` - Starts an in-process HTTP server serving `/metrics`. +* `otlp` - Pushes metrics over OTLP (HTTP/protobuf by default). +* `console` - Writes metrics to stdout (useful for debugging). +* `none` - Disables metrics export entirely. When `OTEL_METRICS_EXPORTER` is unset, autoexport uses OTLP. Set it to `none` to disable metrics. All metrics carry resource attributes (`service.name=oz-agent-worker`, `service.version`, `worker.id`, `worker.backend`) so each worker process shows up as a distinct series in your monitoring system. ---- - ## Enable Prometheus scrape Set these environment variables before starting the worker to expose a Prometheus-compatible `/metrics` endpoint: @@ -55,8 +53,6 @@ curl -s localhost:9464/metrics | grep oz_worker_ Bind to `0.0.0.0` (not `localhost`) when running in Docker or Kubernetes so the Prometheus server, kubelet, or scrape target can reach the endpoint from outside the container. ::: ---- - ## Enable OTLP push Set these environment variables to push metrics to an OpenTelemetry collector: @@ -70,8 +66,6 @@ oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" The worker pushes metrics at the SDK's default interval. Configure the collector endpoint, protocol, and headers using standard [OTLP exporter environment variables](https://opentelemetry.io/docs/specs/otel/protocol/exporter/). ---- - ## Helm chart configuration The [Helm chart](/factories/self-hosting/managed-kubernetes/) includes built-in support for metrics. Enable metrics with `metrics.enabled=true`: @@ -95,23 +89,23 @@ With `metrics.enabled=true` and the default `metrics.exporter=prometheus`, the c **Core:** -* `metrics.enabled` — Enable metrics export. Defaults to `false`. -* `metrics.exporter` — Exporter type: `prometheus` (default), `otlp`, `console`, or `none`. -* `metrics.port` — Port for the Prometheus exporter. Defaults to `9464`. Ignored for `otlp`/`console`. -* `metrics.extraEnv` — Extra environment variables for the worker container (e.g., `OTEL_EXPORTER_OTLP_ENDPOINT`). +* `metrics.enabled` - Enable metrics export. Defaults to `false`. +* `metrics.exporter` - Exporter type: `prometheus` (default), `otlp`, `console`, or `none`. +* `metrics.port` - Port for the Prometheus exporter. Defaults to `9464`. Ignored for `otlp`/`console`. +* `metrics.extraEnv` - Extra environment variables for the worker container (e.g., `OTEL_EXPORTER_OTLP_ENDPOINT`). **Service (Prometheus scrape):** -* `metrics.service.create` — Create a metrics `Service`. Defaults to `true`. -* `metrics.service.type` — Service type. Defaults to `ClusterIP`. -* `metrics.service.annotations` — Annotations on the Service. Defaults include `prometheus.io/scrape: "true"`. +* `metrics.service.create` - Create a metrics `Service`. Defaults to `true`. +* `metrics.service.type` - Service type. Defaults to `ClusterIP`. +* `metrics.service.annotations` - Annotations on the Service. Defaults include `prometheus.io/scrape: "true"`. **PodMonitor (Prometheus Operator):** -* `metrics.podMonitor.create` — Create a `PodMonitor`. Defaults to `false` (avoids requiring `monitoring.coreos.com` CRDs). -* `metrics.podMonitor.interval` — Scrape interval. Defaults to `30s`. -* `metrics.podMonitor.scrapeTimeout` — Scrape timeout. Defaults to `10s`. -* `metrics.podMonitor.additionalLabels` — Extra labels on the `PodMonitor` resource. +* `metrics.podMonitor.create` - Create a `PodMonitor`. Defaults to `false` (avoids requiring `monitoring.coreos.com` CRDs). +* `metrics.podMonitor.interval` - Scrape interval. Defaults to `30s`. +* `metrics.podMonitor.scrapeTimeout` - Scrape timeout. Defaults to `10s`. +* `metrics.podMonitor.additionalLabels` - Extra labels on the `PodMonitor` resource. ### OTLP push via Helm @@ -126,24 +120,20 @@ metrics: value: http://otel-collector.observability.svc:4318 ``` ---- - ## Metric catalog All metrics use the `oz_worker_` prefix. Each worker process with metrics enabled emits a distinct set of series, identified by the resource attributes `service.name`, `service.version`, `worker.id`, and `worker.backend`. -* **`oz_worker_connected`** (gauge) — `1` while the worker has an active WebSocket connection to the {VARS.WARP_AUTOMATION_PLATFORM}'s backend, `0` otherwise. -* **`oz_worker_tasks_active`** (gauge / UpDownCounter) — Tasks currently executing on this worker. -* **`oz_worker_tasks_max_concurrent`** (gauge) — Configured concurrency limit (`0` means unlimited). -* **`oz_worker_tasks_claimed_total`** (counter) — Total tasks accepted since process start. -* **`oz_worker_tasks_rejected_total{reason}`** (counter) — Tasks the worker declined (e.g., `reason="at_capacity"`). -* **`oz_worker_tasks_completed_total{result}`** (counter) — Completed tasks labeled `result="succeeded"`, `result="failed"`, `result="cancelled"`, or `result="dispatched"`. -* **`oz_worker_task_duration_seconds{result}`** (histogram) — Wall-clock task duration on the worker, labeled by result. -* **`oz_worker_task_failures_total{phase,reason}`** (counter) — Task failures classified by execution phase and a bounded reason such as `image_pull`, `unschedulable`, `container_oom`, or `evicted`. -* **`oz_worker_websocket_reconnects_total{reason}`** (counter) — WebSocket reconnect attempts (e.g., `reason="dial_failed"`, `reason="remote_close"`). Spikes indicate flapping workers. -* **`oz_worker_info{version,backend,worker_id}`** (gauge, constant `1`) — Build and runtime metadata. Useful for joining other series by labels. - ---- +* **`oz_worker_connected`** (gauge) - `1` while the worker has an active WebSocket connection to the {VARS.WARP_AUTOMATION_PLATFORM}'s backend, `0` otherwise. +* **`oz_worker_tasks_active`** (gauge / UpDownCounter) - Tasks currently executing on this worker. +* **`oz_worker_tasks_max_concurrent`** (gauge) - Configured concurrency limit (`0` means unlimited). +* **`oz_worker_tasks_claimed_total`** (counter) - Total tasks accepted since process start. +* **`oz_worker_tasks_rejected_total{reason}`** (counter) - Tasks the worker declined (e.g., `reason="at_capacity"`). +* **`oz_worker_tasks_completed_total{result}`** (counter) - Completed tasks labeled `result="succeeded"`, `result="failed"`, `result="cancelled"`, or `result="dispatched"`. +* **`oz_worker_task_duration_seconds{result}`** (histogram) - Wall-clock task duration on the worker, labeled by result. +* **`oz_worker_task_failures_total{phase,reason}`** (counter) - Task failures classified by execution phase and a bounded reason such as `image_pull`, `unschedulable`, `container_oom`, or `evicted`. +* **`oz_worker_websocket_reconnects_total{reason}`** (counter) - WebSocket reconnect attempts (e.g., `reason="dial_failed"`, `reason="remote_close"`). Spikes indicate flapping workers. +* **`oz_worker_info{version,backend,worker_id}`** (gauge, constant `1`) - Build and runtime metadata. Useful for joining other series by labels. ## Sample PromQL queries @@ -198,8 +188,6 @@ All metrics use the `oz_worker_` prefix. Each worker process with metrics enable sum(rate(oz_worker_websocket_reconnects_total[5m])) > 0.1 ``` ---- - ## Disabling metrics Set `OTEL_METRICS_EXPORTER=none` to disable metrics export: @@ -216,12 +204,10 @@ metrics: enabled: false ``` ---- - ## Related pages -* [Self-hosting overview](/factories/self-hosting/) — Architecture, decision guide, and Enterprise requirements. -* [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags, config file schema, and metrics environment variables. -* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Helm chart deployment, including metrics values. -* [Troubleshooting](/factories/self-hosting/troubleshooting/) — Diagnostics for metrics issues and other common problems. -* [Security and networking](/platform/execution-security/) — Network egress and data boundaries. +* [Self-hosting overview](/factories/self-hosting/) - Architecture, decision guide, and Enterprise requirements. +* [Self-hosted worker reference](/factories/self-hosting/reference/) - CLI flags, config file schema, and metrics environment variables. +* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) - Helm chart deployment, including metrics values. +* [Troubleshooting](/factories/self-hosting/troubleshooting/) - Diagnostics for metrics issues and other common problems. +* [Security and networking](/platform/execution-security/) - Network egress and data boundaries. diff --git a/src/content/docs/factories/self-hosting/private-container-registry.mdx b/src/content/docs/factories/self-hosting/private-container-registry.mdx index 91e044eb9..d83c3a65a 100644 --- a/src/content/docs/factories/self-hosting/private-container-registry.mdx +++ b/src/content/docs/factories/self-hosting/private-container-registry.mdx @@ -289,7 +289,7 @@ Confirm `warp-registry` exists in the task namespace. The worker Deployment need ## Related pages -* [Managed: Docker backend](/factories/self-hosting/managed-docker/) — Configure Docker daemon and private-registry access. -* [Managed: Kubernetes backend](/factories/self-hosting/managed-kubernetes/) — Configure the Helm chart, task Pod template, and preflight job. -* [Environments](/platform/environments/) — Set the task image used by self-hosted runs. -* [Security and networking](/platform/execution-security/) — Review image egress and other network requirements. +* [Managed: Docker backend](/factories/self-hosting/managed-docker/) - Configure Docker daemon and private-registry access. +* [Managed: Kubernetes backend](/factories/self-hosting/managed-kubernetes/) - Configure the Helm chart, task Pod template, and preflight job. +* [Environments](/platform/environments/) - Set the task image used by self-hosted runs. +* [Security and networking](/platform/execution-security/) - Review image egress and other network requirements. diff --git a/src/content/docs/factories/self-hosting/quickstart.mdx b/src/content/docs/factories/self-hosting/quickstart.mdx index 1052df1ac..44c64bd1f 100644 --- a/src/content/docs/factories/self-hosting/quickstart.mdx +++ b/src/content/docs/factories/self-hosting/quickstart.mdx @@ -8,22 +8,18 @@ sidebar: --- import { VARS } from '@data/vars'; -Run your first cloud agent on your own infrastructure in ~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting. +Run your first cloud agent on your own infrastructure in about 10 minutes with the managed architecture and the Docker backend, the default path to self-hosting. :::note -This quickstart sets up the [managed architecture](/factories/self-hosting/#managed-architecture), where the {VARS.WARP_AUTOMATION_PLATFORM} orchestrates the agent and your worker provides the compute. **Prefer a CLI-only path with no Docker requirement?** Jump to the [Unmanaged quickstart](/platform/unmanaged-execution/#unmanaged-quickstart) to run `oz agent run` directly on any host. +This quickstart sets up the [managed architecture](/factories/self-hosting/#managed-architecture), where the {VARS.WARP_AUTOMATION_PLATFORM} orchestrates the agent and your worker provides the compute. For a CLI-only path with no Docker requirement, follow the [unmanaged quickstart](/platform/unmanaged-execution/#unmanaged-quickstart) to run `oz agent run` directly on any host. ::: ---- - ## 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). ---- - ## Run your first self-hosted agent _~10 minutes_ @@ -50,7 +46,7 @@ docker run \ warpdotdev/oz-agent-worker --worker-id "my-worker" ``` -**Expected outcome:** The worker connects to the {VARS.WARP_AUTOMATION_PLATFORM} and begins listening for tasks. You should see log output confirming the connection (something like `Connected to Oz` / `Waiting for tasks`). +**Expected outcome:** The worker connects to the {VARS.WARP_AUTOMATION_PLATFORM} and begins listening for tasks. The log confirms the connection with lines such as `Connected to Oz` and `Waiting for tasks`. :::caution For production deployments, pin to a specific image digest (e.g., `warpdotdev/oz-agent-worker@sha256:...`) instead of the `latest` tag. @@ -70,8 +66,6 @@ oz agent run-cloud --prompt "List the files in the current directory" --host "my Open the {VARS.DASHBOARD}, find the new task, and confirm the session transcript shows the agent running against your worker. You can attach to the session at any time via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer it. ---- - ## Troubleshooting **Worker won't start**\ @@ -87,6 +81,6 @@ For more, see [Troubleshooting](/factories/self-hosting/troubleshooting/). ## Next steps -* [Self-hosting overview](/factories/self-hosting/) — Compare managed and unmanaged architectures and choose a backend. -* [Managed: Docker](/factories/self-hosting/managed-docker/) — Full Docker backend setup, including private registries, volume mounts, and runtime configuration. -* [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) — How to route tasks from schedules, integrations (Slack, Linear), the API, and the {VARS.WEB_APP}. +* [Self-hosting overview](/factories/self-hosting/) - Compare managed and unmanaged architectures and choose a backend. +* [Managed: Docker](/factories/self-hosting/managed-docker/) - Full Docker backend setup, including private registries, volume mounts, and runtime configuration. +* [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) - How to route tasks from schedules, integrations (Slack, Linear), the API, and the {VARS.WEB_APP}. diff --git a/src/content/docs/factories/self-hosting/reference.mdx b/src/content/docs/factories/self-hosting/reference.mdx index 6519b51b4..c3e5f5663 100644 --- a/src/content/docs/factories/self-hosting/reference.mdx +++ b/src/content/docs/factories/self-hosting/reference.mdx @@ -7,29 +7,27 @@ description: >- Look up CLI flags and YAML config fields for the `oz-agent-worker` daemon's [managed backends](/factories/self-hosting/#managed-architecture). For installation, see [Install and run the worker](/factories/self-hosting/managed-docker/#install-and-run-the-worker). ---- - ## Worker flags The following flags are available when starting the worker. ### Required -* `--worker-id` — A string identifying this worker. This is the value you pass to `--host` when routing tasks. Choose something meaningful for your team (e.g., `prod-runner-1` or `ci-worker`). Multiple workers can share the same ID for load balancing. -* `--api-key` or `WARP_API_KEY` env var — Your [self-hosted worker API key](/agents/cli/oz-cli/api-keys/#creating-a-self-hosted-worker-api-key) for team authentication. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable. +* `--worker-id` - A string identifying this worker. This is the value you pass to `--host` when routing tasks. Choose something meaningful for your team (e.g., `prod-runner-1` or `ci-worker`). Multiple workers can share the same ID for load balancing. +* `--api-key` or `WARP_API_KEY` env var - Your [self-hosted worker API key](/agents/cli/oz-cli/api-keys/#creating-a-self-hosted-worker-api-key) for team authentication. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable. ### Optional -* `--config-file` — Path to a YAML [config file](#config-file). CLI flags take precedence over config file values. -* `--backend` — Backend type: `docker` (default), `kubernetes`, `direct`, or `command`. See [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/), [Managed: Direct](/factories/self-hosting/managed-direct/), and [External orchestrators](/factories/self-hosting/external-orchestrators/) for backend-specific setup. -* `--log-level` — Log verbosity. One of `debug`, `info`, `warn`, `error`. Defaults to `info`. -* `--no-cleanup` — Keep task containers, Kubernetes Jobs, or workspace directories after execution instead of removing them. For Direct tasks that use per-task workspaces, this also skips `teardown_command`. Useful for debugging failed tasks. -* `--target-dir` — Shared working directory for all Direct backend tasks. When set, the worker does not create or remove per-task workspace directories. This flag overrides `backend.direct.target_dir` in the config file. -* `-v` / `--volumes` — Mount host directories into task containers (Docker backend only). Format: `HOST_PATH:CONTAINER_PATH` or `HOST_PATH:CONTAINER_PATH:MODE` (where MODE is `ro` or `rw`). Can be specified multiple times. -* `-e` / `--env` — Set environment variables for tasks. Format: `KEY=VALUE` (explicit value) or `KEY` (pass through from host environment). Can be specified multiple times. -* `--max-concurrent-tasks` — Maximum number of tasks to run concurrently. Defaults to `0` (unlimited). When set, additional tasks wait until a slot is available. -* `--one-shot` — Exit after one accepted task succeeds, fails, or is cancelled. Supported only by the Direct backend and forces `max_concurrent_tasks` to `1`. -* `--idle-on-complete` — How long to keep the `oz` process alive after a task's conversation finishes, allowing follow-up interactions via session sharing. Uses duration format (e.g. `45m`, `10m`, `0s`). Defaults to `45m` when the task has no `config.idle_timeout_minutes` value. A task-level value takes precedence; runs created directly through the Agent API default to 10 minutes. See [Configure the completion timeout](/factories/self-hosting/external-orchestrators/#configure-the-completion-timeout). +* `--config-file` - Path to a YAML [config file](#config-file). CLI flags take precedence over config file values. +* `--backend` - Backend type: `docker` (default), `kubernetes`, `direct`, or `command`. See [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/), [Managed: Direct](/factories/self-hosting/managed-direct/), and [External orchestrators](/factories/self-hosting/external-orchestrators/) for backend-specific setup. +* `--log-level` - Log verbosity. One of `debug`, `info`, `warn`, `error`. Defaults to `info`. +* `--no-cleanup` - Keep task containers, Kubernetes Jobs, or workspace directories after execution instead of removing them. For Direct tasks that use per-task workspaces, this also skips `teardown_command`. Useful for debugging failed tasks. +* `--target-dir` - Shared working directory for all Direct backend tasks. When set, the worker does not create or remove per-task workspace directories. This flag overrides `backend.direct.target_dir` in the config file. +* `-v` / `--volumes` - Mount host directories into task containers (Docker backend only). Format: `HOST_PATH:CONTAINER_PATH` or `HOST_PATH:CONTAINER_PATH:MODE` (where MODE is `ro` or `rw`). Can be specified multiple times. +* `-e` / `--env` - Set environment variables for tasks. Format: `KEY=VALUE` (explicit value) or `KEY` (pass through from host environment). Can be specified multiple times. +* `--max-concurrent-tasks` - Maximum number of tasks to run concurrently. Defaults to `0` (unlimited). When set, additional tasks wait until a slot is available. +* `--one-shot` - Exit after one accepted task succeeds, fails, or is cancelled. Supported only by the Direct backend and forces `max_concurrent_tasks` to `1`. +* `--idle-on-complete` - How long to keep the `oz` process alive after a task's conversation finishes, allowing follow-up interactions via session sharing. Uses duration format (e.g. `45m`, `10m`, `0s`). Defaults to `45m` when the task has no `config.idle_timeout_minutes` value. A task-level value takes precedence; runs created directly through the Agent API default to 10 minutes. See [Configure the completion timeout](/factories/self-hosting/external-orchestrators/#configure-the-completion-timeout). Worker IDs starting with `warp` are reserved and cannot be used. The worker refuses to start if `--worker-id` begins with `warp`. @@ -57,8 +55,6 @@ docker run \ When running the worker via Docker, there are two levels of `-e` flags. Docker's `-e` passes env vars to the **worker container** (e.g., `WARP_API_KEY`). The worker's `-e` / `--env` flags pass env vars into the **task containers** the worker spawns. Keep these distinct. ::: ---- - ## Config file For complex setups, use a YAML config file instead of (or in addition to) CLI flags. Pass it with `--config-file`: @@ -151,90 +147,84 @@ backend: **Top-level:** -* `worker_id` — Worker identifier (same as `--worker-id` flag). -* `cleanup` — Whether to clean up after tasks. Defaults to `true`. Set to `false` to keep containers/workspaces for debugging (equivalent to `--no-cleanup`). -* `max_concurrent_tasks` — Maximum concurrent tasks. Defaults to unlimited. -* `one_shot` — Exit after one accepted Direct backend task reaches a terminal state. Defaults to `false` and forces `max_concurrent_tasks` to `1` when enabled. -* `idle_on_complete` — Duration to keep the `oz` process alive after task completion (e.g. `"45m"`, `"0s"`). Task-level timeout values take precedence; see [Configure the completion timeout](/factories/self-hosting/external-orchestrators/#configure-the-completion-timeout). -* `backend` — Backend configuration block. Only one backend (`docker`, `kubernetes`, `direct`, or `command`) may be specified. +* `worker_id` - Worker identifier (same as `--worker-id` flag). +* `cleanup` - Whether to clean up after tasks. Defaults to `true`. Set to `false` to keep containers/workspaces for debugging (equivalent to `--no-cleanup`). +* `max_concurrent_tasks` - Maximum concurrent tasks. Defaults to unlimited. +* `one_shot` - Exit after one accepted Direct backend task reaches a terminal state. Defaults to `false` and forces `max_concurrent_tasks` to `1` when enabled. +* `idle_on_complete` - Duration to keep the `oz` process alive after task completion (e.g. `"45m"`, `"0s"`). Task-level timeout values take precedence; see [Configure the completion timeout](/factories/self-hosting/external-orchestrators/#configure-the-completion-timeout). +* `backend` - Backend configuration block. Only one backend (`docker`, `kubernetes`, `direct`, or `command`) may be specified. **`backend.docker`:** -* `volumes` — List of volume mounts (same format as `-v` flag). -* `image_pull_policy` — Pull policy for task and sidecar images. One of `Always`, `Never`, or `IfNotPresent`. Defaults to `Always`. Requires worker release `v2026-08-20-16-38-31` or newer. -* `sidecar_image` — Image reference for the Warp Agent sidecar mounted at `/agent`. It does not affect additional sidecars. Requires worker release `v2026-08-28-21-43-14` or newer. -* `environment` — List of environment variables with `name` and optional `value`. If `value` is omitted, the variable is inherited from the host. +* `volumes` - List of volume mounts (same format as `-v` flag). +* `image_pull_policy` - Pull policy for task and sidecar images. One of `Always`, `Never`, or `IfNotPresent`. Defaults to `Always`. Requires worker release `v2026-08-20-16-38-31` or newer. +* `sidecar_image` - Image reference for the Warp Agent sidecar mounted at `/agent`. It does not affect additional sidecars. Requires worker release `v2026-08-28-21-43-14` or newer. +* `environment` - List of environment variables with `name` and optional `value`. If `value` is omitted, the variable is inherited from the host. **`backend.kubernetes`:** -* `namespace` — Kubernetes namespace for task Jobs. Defaults to `default`. Selects the namespace inside the chosen cluster; does not choose the cluster. -* `kubeconfig` — Path to an explicit kubeconfig file. If omitted, the worker uses in-cluster config when running inside Kubernetes, or falls back to the default kubeconfig loading rules. -* `default_image` — Default Docker image for task Jobs when the run has no Warp environment image. Precedence: Warp environment image > `default_image` > `ubuntu:22.04`. Set this to skip creating a Warp environment when all your tasks use the same base image. -* `image_pull_policy` — Pull policy for task, sidecar, and preflight images. One of `Always`, `Never`, or `IfNotPresent`. Defaults to `IfNotPresent`. -* `use_image_volumes` — Use native image volumes instead of root init containers. Defaults to `false` and requires cluster and runtime support. -* `preflight_image` — Startup preflight Job image. Defaults to `busybox:1.36`. Override this if your cluster only allows pulling from an internal or allowlisted registry. -* `preflight_resources` — CPU and memory requests and limits for startup preflight containers. -* `sidecar_image` — Image reference that replaces the Warp Agent sidecar mounted at `/agent`. -* `coding_cli_sidecars` — Map of harness names such as `claude` or `codex` to coding CLI sidecar images. -* `setup_command` — Shell command to run before each task. -* `teardown_command` — Shell command to run after each task completes. -* `extra_labels` — Map of additional labels to add to task Jobs and Pods. -* `extra_annotations` — Map of additional annotations to add to task Jobs and Pods. -* `active_deadline_seconds` — Maximum task Job lifetime (Kubernetes `activeDeadlineSeconds`). The worker has no default; the Helm chart defaults `kubernetesBackend.activeDeadlineSeconds` to eight hours. -* `ttl_seconds_after_finished` — Retention period for failed or orphaned Jobs. Defaults to 24 hours when cleanup is enabled. -* `workspace_size_limit` — Size limit for the workspace `emptyDir` volume (e.g., `10Gi`). -* `unschedulable_timeout` — How long a pod may remain unschedulable before the task is failed early. Defaults to `30s`. Set to `0s` to disable the fail-fast behavior. -* `pod_template` — Raw Kubernetes PodSpec YAML merged with the worker's required fields at runtime. Use this to configure task pod scheduling, `serviceAccountName`, `imagePullSecrets`, `nodeSelector`, `tolerations`, resources, and environment variables (including `valueFrom.secretKeyRef` for Kubernetes Secrets). Define a container named `task` to customize the main task container directly; otherwise the worker appends its own. +* `namespace` - Kubernetes namespace for task Jobs. Defaults to `default`. Selects the namespace inside the chosen cluster; does not choose the cluster. +* `kubeconfig` - Path to an explicit kubeconfig file. If omitted, the worker uses in-cluster config when running inside Kubernetes, or falls back to the default kubeconfig loading rules. +* `default_image` - Default Docker image for task Jobs when the run has no Warp environment image. Precedence: Warp environment image > `default_image` > `ubuntu:22.04`. Set this to skip creating a Warp environment when all your tasks use the same base image. +* `image_pull_policy` - Pull policy for task, sidecar, and preflight images. One of `Always`, `Never`, or `IfNotPresent`. Defaults to `IfNotPresent`. +* `use_image_volumes` - Use native image volumes instead of root init containers. Defaults to `false` and requires cluster and runtime support. +* `preflight_image` - Startup preflight Job image. Defaults to `busybox:1.36`. Override this if your cluster only allows pulling from an internal or allowlisted registry. +* `preflight_resources` - CPU and memory requests and limits for startup preflight containers. +* `sidecar_image` - Image reference that replaces the Warp Agent sidecar mounted at `/agent`. +* `coding_cli_sidecars` - Map of harness names such as `claude` or `codex` to coding CLI sidecar images. +* `setup_command` - Shell command to run before each task. +* `teardown_command` - Shell command to run after each task completes. +* `extra_labels` - Map of additional labels to add to task Jobs and Pods. +* `extra_annotations` - Map of additional annotations to add to task Jobs and Pods. +* `active_deadline_seconds` - Maximum task Job lifetime (Kubernetes `activeDeadlineSeconds`). The worker has no default; the Helm chart defaults `kubernetesBackend.activeDeadlineSeconds` to eight hours. +* `ttl_seconds_after_finished` - Retention period for failed or orphaned Jobs. Defaults to 24 hours when cleanup is enabled. +* `workspace_size_limit` - Size limit for the workspace `emptyDir` volume (e.g., `10Gi`). +* `unschedulable_timeout` - How long a pod may remain unschedulable before the task is failed early. Defaults to `30s`. Set to `0s` to disable the fail-fast behavior. +* `pod_template` - Raw Kubernetes PodSpec YAML merged with the worker's required fields at runtime. Use this to configure task pod scheduling, `serviceAccountName`, `imagePullSecrets`, `nodeSelector`, `tolerations`, resources, and environment variables (including `valueFrom.secretKeyRef` for Kubernetes Secrets). Define a container named `task` to customize the main task container directly; otherwise the worker appends its own. **`backend.direct`:** -* `workspace_root` — Directory where per-task workspaces are created. Defaults to `/var/lib/oz/workspaces`. -* `target_dir` — Shared directory used as the working directory for every task. When set, the worker does not create or remove per-task workspace directories. -* `oz_path` — Path to the oz CLI binary. If omitted, the worker looks up `oz` in `PATH`. -* `setup_command` — Shell command to run before each task. Receives `OZ_WORKSPACE_ROOT`, `OZ_RUN_ID`, `OZ_ENVIRONMENT_FILE`, and `OZ_WORKER_BACKEND` as environment variables. -* `teardown_command` — Shell command to run after each task completes. -* `environment` — List of environment variables (same format as the Docker backend). +* `workspace_root` - Directory where per-task workspaces are created. Defaults to `/var/lib/oz/workspaces`. +* `target_dir` - Shared directory used as the working directory for every task. When set, the worker does not create or remove per-task workspace directories. +* `oz_path` - Path to the oz CLI binary. If omitted, the worker looks up `oz` in `PATH`. +* `setup_command` - Shell command to run before each task. Receives `OZ_WORKSPACE_ROOT`, `OZ_RUN_ID`, `OZ_ENVIRONMENT_FILE`, and `OZ_WORKER_BACKEND` as environment variables. +* `teardown_command` - Shell command to run after each task completes. +* `environment` - List of environment variables (same format as the Docker backend). **`backend.command`:** -* `dispatch_command` — Required shell command that accepts a JSON task payload on standard input and hands the task to an external runtime. -* `cancel_command` — Optional shell command invoked when a dispatched task is cancelled. -* `dispatch_timeout` — Maximum runtime for the dispatch command. Defaults to `60s`. -* `environment` — Environment variables for the dispatch and cancellation commands. Task credentials remain in the standard-input payload. +* `dispatch_command` - Required shell command that accepts a JSON task payload on standard input and hands the task to an external runtime. +* `cancel_command` - Optional shell command invoked when a dispatched task is cancelled. +* `dispatch_timeout` - Maximum runtime for the dispatch command. Defaults to `60s`. +* `environment` - Environment variables for the dispatch and cancellation commands. Task credentials remain in the standard-input payload. Only one backend can be configured at a time. Specifying more than one of `docker`, `kubernetes`, `direct`, and `command` in the same config file is an error. ---- - ## Metrics configuration Configure OpenTelemetry metrics with environment variables on the worker process or container: -* `OTEL_METRICS_EXPORTER` — Exporter to use: `prometheus`, `otlp`, `console`, or `none`. When unset, the worker uses the OpenTelemetry autoexport default, OTLP. Set it to `none` to disable metrics initialization. -* `OTEL_EXPORTER_PROMETHEUS_HOST` — Bind address for the Prometheus exporter. Defaults to `localhost`. Set to `0.0.0.0` when running in Docker or Kubernetes. -* `OTEL_EXPORTER_PROMETHEUS_PORT` — Port for the Prometheus exporter. Defaults to `9464`. -* `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP collector endpoint (e.g., `http://otel-collector.observability.svc:4318`). -* `OTEL_EXPORTER_OTLP_PROTOCOL` — OTLP protocol: `http/protobuf` (default) or `grpc`. +* `OTEL_METRICS_EXPORTER` - Exporter to use: `prometheus`, `otlp`, `console`, or `none`. When unset, the worker uses the OpenTelemetry autoexport default, OTLP. Set it to `none` to disable metrics initialization. +* `OTEL_EXPORTER_PROMETHEUS_HOST` - Bind address for the Prometheus exporter. Defaults to `localhost`. Set to `0.0.0.0` when running in Docker or Kubernetes. +* `OTEL_EXPORTER_PROMETHEUS_PORT` - Port for the Prometheus exporter. Defaults to `9464`. +* `OTEL_EXPORTER_OTLP_ENDPOINT` - OTLP collector endpoint (e.g., `http://otel-collector.observability.svc:4318`). +* `OTEL_EXPORTER_OTLP_PROTOCOL` - OTLP protocol: `http/protobuf` (default) or `grpc`. When deploying with the Helm chart, use the `metrics.*` values instead of setting these variables manually. See [Monitoring](/factories/self-hosting/monitoring/) for the full setup guide, metric catalog, Helm values, and sample PromQL queries. ---- - ## Routing runs to self-hosted workers Once a worker is running, route cloud agent runs to it with the `--host` flag or its equivalents. See [Routing runs to self-hosted workers](/factories/self-hosting/#routing-runs-to-self-hosted-workers) for examples across the CLI, schedules, integrations, the API, and the web UI. ---- - ## Related pages -* [Managed: Docker](/factories/self-hosting/managed-docker/) — Docker backend setup, connectivity, and private registries. -* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Kubernetes backend setup, Helm chart, pod template, and operational notes. -* [Private container registry](/factories/self-hosting/private-container-registry/) — Mirror and pull worker, task, sidecar, and preflight images from an internal registry. -* [Managed: Direct](/factories/self-hosting/managed-direct/) — Direct backend setup and workspace model. -* [External orchestrators](/factories/self-hosting/external-orchestrators/) — One-shot Direct and Command backend dispatch. -* [Direct backend monorepo worktrees](/factories/self-hosting/direct-monorepo-worktrees/) — Setup and teardown hooks for isolated monorepo worktrees. -* [Self-hosting overview](/factories/self-hosting/) — Architecture, decision guide, and Enterprise requirements. -* [Environments](/platform/environments/) — Define the Docker image, repos, and setup commands used by task containers. -* [Monitoring](/factories/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. -* [Troubleshooting](/factories/self-hosting/troubleshooting/) — Worker and task failure diagnostics. +* [Managed: Docker](/factories/self-hosting/managed-docker/) - Docker backend setup, connectivity, and private registries. +* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) - Kubernetes backend setup, Helm chart, pod template, and operational notes. +* [Private container registry](/factories/self-hosting/private-container-registry/) - Mirror and pull worker, task, sidecar, and preflight images from an internal registry. +* [Managed: Direct](/factories/self-hosting/managed-direct/) - Direct backend setup and workspace model. +* [External orchestrators](/factories/self-hosting/external-orchestrators/) - One-shot Direct and Command backend dispatch. +* [Direct backend monorepo worktrees](/factories/self-hosting/direct-monorepo-worktrees/) - Setup and teardown hooks for isolated monorepo worktrees. +* [Self-hosting overview](/factories/self-hosting/) - Architecture, decision guide, and Enterprise requirements. +* [Environments](/platform/environments/) - Define the Docker image, repos, and setup commands used by task containers. +* [Monitoring](/factories/self-hosting/monitoring/) - OpenTelemetry metrics for worker health, task throughput, and capacity. +* [Troubleshooting](/factories/self-hosting/troubleshooting/) - Worker and task failure diagnostics. diff --git a/src/content/docs/factories/self-hosting/troubleshooting.mdx b/src/content/docs/factories/self-hosting/troubleshooting.mdx index 5197ccabc..9739e183c 100644 --- a/src/content/docs/factories/self-hosting/troubleshooting.mdx +++ b/src/content/docs/factories/self-hosting/troubleshooting.mdx @@ -14,8 +14,6 @@ Use these checks when the `oz-agent-worker` daemon won't start or connect, tasks The steps below apply to the [managed architecture](/factories/self-hosting/#managed-architecture) (`oz-agent-worker` daemon). For [unmanaged](/platform/unmanaged-execution/) deployments, refer to the documentation for the environment running `oz agent run` (e.g., GitHub Actions, Kubernetes). ::: ---- - ## Worker won't start ### Docker backend @@ -52,8 +50,6 @@ A successful preflight validates the configured pod shape, not task-specific ima 1. Install the {VARS.WARP_AGENT_CLI} on the worker host. See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli). 2. If the CLI isn't on `PATH`, set `oz_path` in the config file to the absolute path of the `oz` binary. ---- - ## Worker won't connect **Cause:** The API key is invalid, expired, or the host cannot reach the {VARS.WARP_AUTOMATION_PLATFORM}'s backend. @@ -68,8 +64,6 @@ A successful preflight validates the configured pod shape, not task-specific ima See [Security and networking](/platform/execution-security/#network-requirements) for the full list of outbound endpoints the worker needs. ---- - ## Tasks not being picked up **Cause:** The worker isn't running, the `--host` value doesn't match the worker's `--worker-id`, or the worker and task belong to different teams. @@ -80,8 +74,6 @@ See [Security and networking](/platform/execution-security/#network-requirements 2. Verify the `--host` (or `worker_host`) value you passed matches your `--worker-id` exactly. Case-sensitive. 3. Ensure the worker's team matches the team creating the task. ---- - ## Metrics not appearing **Cause:** The worker is running but metrics aren't showing up in Prometheus or your collector. @@ -98,8 +90,6 @@ See [Security and networking](/platform/execution-security/#network-requirements See [Monitoring](/factories/self-hosting/monitoring/) for the full setup guide. ---- - ## Task failures **Cause:** The backend logs identify why the task failed. @@ -144,8 +134,6 @@ The worker API key authenticates the worker to Warp; it is not a task credential 1. Verify the {VARS.WARP_AGENT_CLI} is accessible. 2. Verify the workspace root directory has write permissions for the user running the worker. ---- - ## Image pull failures ### Docker backend (image pull) @@ -163,11 +151,9 @@ The worker API key authenticates the worker to Warp; it is not a task credential * Verify the image exists and the tag is correct. * Check network connectivity from the worker/cluster to the registry. ---- - ## Related pages -* [Self-hosting overview](/factories/self-hosting/) — Architecture and decision guide. -* [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags and config schema, including every flag mentioned here. -* [Security and networking](/platform/execution-security/) — Outbound endpoints the worker needs. -* [Agent Session Sharing](/agents/local-agents/session-sharing/) — Attach to running tasks to debug interactively. +* [Self-hosting overview](/factories/self-hosting/) - Architecture and decision guide. +* [Self-hosted worker reference](/factories/self-hosting/reference/) - CLI flags and config schema, including every flag mentioned here. +* [Security and networking](/platform/execution-security/) - Outbound endpoints the worker needs. +* [Agent Session Sharing](/agents/local-agents/session-sharing/) - Attach to running tasks to debug interactively. diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx index d32d4e782..8a06a919c 100644 --- a/src/content/docs/factories/troubleshooting.mdx +++ b/src/content/docs/factories/troubleshooting.mdx @@ -8,7 +8,7 @@ sidebar: --- import { VARS } from '@data/vars'; -Fix the problems teams hit most often when setting up a factory and running their first work through it. Each entry below names the symptom you'd see in the {VARS.FACTORY_WEB_APP}. +Fix the problems teams hit most often when setting up a factory and running their first work through it. ## Setting up a factory @@ -96,8 +96,8 @@ Then check the causes specific to where the work came from: ## Related pages -* [**Warp Factories quickstart**](/factories/quickstart/) - Create a factory and submit your first work item. -* [**Connect your factory**](/factories/connect-your-factory/) - Route work in from Slack threads, Linear issues, and other intake paths. -* [**Automations**](/factories/automations/) - The matching rules that decide which events start work. -* [**Factory inbox**](/factories/factory-inbox/) - See and resolve the questions, spec approvals, and PR reviews waiting on you. -* [**Factory dashboard**](/factories/factory-dashboard/) - Where to watch work items, runs, and their outputs. +* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and submit your first work item. +* [Connect your factory](/factories/connect-your-factory/) - Route work in from Slack threads, Linear issues, and other intake paths. +* [Factory automations](/factories/automations/) - The matching rules that decide which events start work. +* [Factory inbox](/factories/factory-inbox/) - See and resolve the questions, spec approvals, and PR reviews waiting on you. +* [Factory dashboard](/factories/factory-dashboard/) - Where to watch work items, runs, and their outputs. diff --git a/src/content/docs/factories/warp-hosting.mdx b/src/content/docs/factories/warp-hosting.mdx index 29d3b3dfe..65df05f8c 100644 --- a/src/content/docs/factories/warp-hosting.mdx +++ b/src/content/docs/factories/warp-hosting.mdx @@ -14,22 +14,21 @@ Use it when your factory's repositories and services are reachable from the publ ## Sandbox environment -All Warp-hosted agents run in fully-isolated sandboxes. Warp uses a mix of infrastructure providers to ensure reliable sandbox startup. +All Warp-hosted agents run in isolated sandboxes. Warp uses a mix of infrastructure providers for sandbox capacity. ### 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. -They are compatible with any Linux x86-64 image that includes a `bash` shell and core utilities like `ls` and `mkdir`. +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 accept any x86-64 or aarch64 image that includes a `bash` shell and core utilities like `ls` and `mkdir`; macOS runners run in a Warp-provided VM. See [runners](/factories/runners/) for the options. ### Resources -The resources available to Warp-hosted agents depend on your [plan](https://www.warp.dev/pricing) - see the latest details there. +The resources available to Warp-hosted agents depend on your [plan](https://www.warp.dev/pricing). -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. +On [Enterprise](/enterprise/) plans, resources are configurable up to 32 vCPUs and 64 GiB of memory. If you need more, contact Warp support about custom provisioning. ### Concurrency -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. +To allocate resources fairly across all Warp users, Warp limits how many hosted agents a team can run at once. An agent started at the limit is queued and starts as soon as another agent completes. ### Networking @@ -48,8 +47,6 @@ Warp's hosted agents have network egress enabled by default. Outgoing requests m * `16.145.188.113/32` * `16.145.133.251/32` ---- - ## Related pages * [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) - Configure the shared cloud-agent primitives behind a factory. diff --git a/src/content/docs/factories/webhooks.mdx b/src/content/docs/factories/webhooks.mdx index 151c5d31a..d0f18cfba 100644 --- a/src/content/docs/factories/webhooks.mdx +++ b/src/content/docs/factories/webhooks.mdx @@ -33,7 +33,7 @@ Choose the mode that fits what the sender can do: | **URL token** | `url_token` | Posts to a URL that embeds the secret as a path segment | Senders that only take a URL and can't set headers | | **Provider signature** | `signature` | Signs each request with its own scheme; Warp verifies the signature with the provider's signing secret | Vercel, Stripe, GitHub, Sentry, PagerDuty, and any sender that implements [Standard Webhooks](https://www.standardwebhooks.com/) (Svix-compatible headers are accepted) | -Warp generates the secret for bearer token and URL token webhooks and shows it once when you create the webhook. For a provider signature webhook, you supply the provider's own signing secret instead — or leave it blank for a Standard Webhooks-compatible sender, and Warp generates one for you to give the sender. Vercel, Stripe, and PagerDuty only issue their secret after you give them a URL; leave the secret blank for those too, and Warp takes it in a second step. See [Setting up a Vercel webhook](/factories/webhooks/vercel/), which covers all three. See [Manage webhooks](#manage-webhooks) to rotate a secret or roll a webhook over. +Warp generates the secret for bearer token and URL token webhooks and shows it once when you create the webhook. For a provider signature webhook, you supply the provider's own signing secret instead, or leave it blank for a Standard Webhooks-compatible sender and Warp generates one for you to give the sender. Vercel, Stripe, and PagerDuty only issue their secret after you give them a URL; leave the secret blank for those too, and Warp takes it in a second step, as described in [setting up a Vercel webhook](/factories/webhooks/vercel/). To rotate a secret or roll a webhook over, see [manage webhooks](#manage-webhooks). A URL token webhook's URL is itself the credential: treat it like a secret, and rotate it if it leaks. @@ -178,9 +178,9 @@ find the failing code path, and open a pull request with a fix and a test. ## Related pages -* [**Setting up a Vercel webhook**](/factories/webhooks/vercel/) - The two-step setup for providers that issue their signing secret only after they have a URL. -* [**Automations**](/factories/automations/) - How triggers and filters decide which events start work, including the payload filter grammar. -* [**Connect your factory**](/factories/connect-your-factory/) - Every way work reaches a factory, alongside custom webhooks. -* [**Definitions as code**](/factories/factory-as-code/) - The full schema for `webhooks/.yaml` and webhook triggers. -* [**Cloud agent secrets**](/platform/secrets/) - Create and rotate the managed secrets that file-defined webhooks reference. -* [**Factory dashboard**](/factories/factory-dashboard/) - Where the **Automations** page and its **Webhooks** tab live. +* [Setting up a Vercel webhook](/factories/webhooks/vercel/) - The two-step setup for providers that issue their signing secret only after they have a URL. +* [Factory automations](/factories/automations/) - How triggers and filters decide which events start work, including the payload filter grammar. +* [Connect your factory](/factories/connect-your-factory/) - Every way work reaches a factory, alongside custom webhooks. +* [Factory definition syntax](/factories/factory-as-code/#webhooksnameyaml) - The full schema for `webhooks/.yaml` and webhook triggers. +* [Cloud agent secrets](/platform/secrets/) - Create and rotate the managed secrets that file-defined webhooks reference. +* [Factory dashboard](/factories/factory-dashboard/) - Where the **Automations** page and its **Webhooks** tab live. diff --git a/src/content/docs/factories/webhooks/vercel.mdx b/src/content/docs/factories/webhooks/vercel.mdx index 752dd447c..4eb0ea00a 100644 --- a/src/content/docs/factories/webhooks/vercel.mdx +++ b/src/content/docs/factories/webhooks/vercel.mdx @@ -72,7 +72,7 @@ The secret Warp verifies with doesn't match the one Vercel signs with: the place ## Related pages -* [**Triggering automations with custom webhooks**](/factories/webhooks/) - Authentication modes, delivery rules, payload filters, and managing webhooks. -* [**Definitions as code**](/factories/factory-as-code/#webhooksnameyaml) - Every key in `webhooks/.yaml`. -* [**Cloud agent secrets**](/platform/secrets/) - The managed secrets that webhooks reference, and the `oz secret` commands. -* [**Vercel webhooks**](https://vercel.com/docs/webhooks) - Vercel's reference for webhook events and payloads. +* [Triggering automations with custom webhooks](/factories/webhooks/) - Authentication modes, delivery rules, payload filters, and managing webhooks. +* [Factory definition syntax](/factories/factory-as-code/#webhooksnameyaml) - Every key in `webhooks/.yaml`. +* [Cloud agent secrets](/platform/secrets/) - The managed secrets that webhooks reference, and the `oz secret` commands. +* [Vercel webhooks](https://vercel.com/docs/webhooks) - Vercel's reference for webhook events and payloads. diff --git a/src/content/docs/platform/orchestration/index.mdx b/src/content/docs/platform/orchestration/index.mdx index 65e1a3791..6c3582562 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/#how-the-foreman-dispatches-agents). ## Run state transitions diff --git a/src/sidebar.ts b/src/sidebar.ts index 5ac2af3a5..89a5f25d9 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -399,7 +399,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ label: 'Overview', items: [ { slug: 'factories', label: 'Overview' }, - { slug: 'factories/how-factories-work', label: 'How Factories work' }, + { slug: 'factories/how-factories-work', label: 'How factories work' }, { slug: 'factories/quickstart', label: 'Quickstart' }, ], },