diff --git a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py index fec643842..483bb47cd 100644 --- a/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py +++ b/.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py @@ -34,6 +34,20 @@ def test_all_review_findings_must_supply_actionable_details(self): self.assertIn("critical, important, suggestion, or nit", self.workflow) self.assertIn("file and line or quoted text", self.workflow) + def test_review_signal_is_passed_through_a_file(self): + self.assertIn('oz "${args[@]}" > /tmp/agent-output.txt', self.workflow) + self.assertIn("--agent-output /tmp/agent-output.txt", self.workflow) + self.assertNotIn(".agent-docs-review-signal.txt", self.workflow) + self.assertNotIn( + "AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}", self.workflow + ) + + def test_review_uses_a_signed_oz_package(self): + self.assertIn("0913165C78D5B7A41B42AC657FF7AB39D60F803F", self.workflow) + self.assertIn("signed-by=/etc/apt/keyrings/warpdotdev.gpg", self.workflow) + self.assertIn("sudo apt-get install -y oz-stable", self.workflow) + self.assertIn("oz --version", self.workflow) + if __name__ == "__main__": unittest.main() diff --git a/.agents/skills/doc_quality_policy/test_verify_review_signal.py b/.agents/skills/doc_quality_policy/test_verify_review_signal.py index 9d02c1063..be53282cc 100644 --- a/.agents/skills/doc_quality_policy/test_verify_review_signal.py +++ b/.agents/skills/doc_quality_policy/test_verify_review_signal.py @@ -78,6 +78,18 @@ def test_escaped_action_output_signal_passes(self): problems = vrs.check_review_signal("o/r", "1", "sha1", output) self.assertEqual(problems, []) + def test_signal_with_braces_in_an_actionable_finding_passes(self): + output = ( + '[SIGNAL:pr-review] {"pr":"1","head_sha":"sha1",' + '"reviewer_login":"github-actions[bot]","verdict":"Approve with nits",' + '"critical":0,"important":0,"suggestions":1,"nits":0,' + '"actionable_findings":["`factory-api.mdx:20` — Check ' + '`POST /factory/{uid}/runs`."]}' + ) + with mock.patch.object(vrs.cpc, "_fetch_reviews", return_value=[{**GOOD_REVIEW, "body": output}]): + problems = vrs.check_review_signal("o/r", "1", "sha1", output) + self.assertEqual(problems, []) + def test_distinct_signals_fail(self): different_signal = GOOD_OUTPUT.replace('"Approve"', '"Approve with nits"') output = f"{GOOD_OUTPUT}\n\n{different_signal}" diff --git a/.agents/skills/doc_quality_policy/verify_review_signal.py b/.agents/skills/doc_quality_policy/verify_review_signal.py index f38866f18..626664aec 100644 --- a/.agents/skills/doc_quality_policy/verify_review_signal.py +++ b/.agents/skills/doc_quality_policy/verify_review_signal.py @@ -5,7 +5,6 @@ import argparse import importlib.util import json -import re import sys from pathlib import Path from typing import Dict, List, Optional, Tuple @@ -16,7 +15,7 @@ sys.modules[_spec.name] = cpc _spec.loader.exec_module(cpc) -_SIGNAL_RE = re.compile(r"\[SIGNAL:pr-review\]\s*(\{.*?\})", re.DOTALL) +_SIGNAL_PREFIX = "[SIGNAL:pr-review]" _PASSING_VERDICTS = {"approve", "approve with nits", "approve_with_nits"} @@ -25,25 +24,24 @@ def _parse_signal( pr_number: Optional[str] = None, head_sha: Optional[str] = None, ) -> Tuple[Optional[Dict[str, object]], List[str]]: - matches = _SIGNAL_RE.findall(text) - if not matches: + occurrences = text.count(_SIGNAL_PREFIX) + if not occurrences: return None, ["expected exactly one [SIGNAL:pr-review] record, found 0"] unique_signals = {} - for match in matches: - try: - signal = json.loads(match) - except json.JSONDecodeError as original_error: + offset = 0 + while True: + marker = text.find(_SIGNAL_PREFIX, offset) + if marker == -1: + break + offset = marker + len(_SIGNAL_PREFIX) + candidate = text[offset:].lstrip() + signal = None + for payload in (candidate, candidate.replace('\\"', '"')): try: - # The GitHub Action can serialize its text output once more, - # leaving an otherwise valid object in the form - # {\"key\":\"value\"}. Decode that wrapper only after direct - # JSON parsing has failed. - signal = json.loads(match.replace('\\"', '"')) + signal, _ = json.JSONDecoder().raw_decode(payload) + break except json.JSONDecodeError: - # Agent output includes the skill's marker examples and prior - # review transcripts. Ignore malformed candidates and require - # a valid, current-head record below. continue if not isinstance(signal, dict): continue @@ -57,7 +55,7 @@ def _parse_signal( if len(signals) != 1: return None, [ "expected one valid [SIGNAL:pr-review] record for the current PR head, " - f"found {len(signals)} across {len(matches)} occurrences" + f"found {len(signals)} across {occurrences} occurrences" ] return signals[0], [] diff --git a/.github/workflows/agent-docs-review.yml b/.github/workflows/agent-docs-review.yml index 6b7b267c7..fa6946366 100644 --- a/.github/workflows/agent-docs-review.yml +++ b/.github/workflows/agent-docs-review.yml @@ -37,12 +37,30 @@ jobs: uses: actions/checkout@v4 - name: Run independent review-docs-pr agent - id: oz-review - uses: warpdotdev/oz-agent-action@main - with: - warp_api_key: ${{ secrets.WARP_API_KEY }} - profile: ${{ vars.WARP_AGENT_PROFILE || '' }} - prompt: | + env: + WARP_API_KEY: ${{ secrets.WARP_API_KEY }} + WARP_AGENT_PROFILE: ${{ vars.WARP_AGENT_PROFILE || '' }} + run: | + sudo apt-get update + sudo apt-get install -y gpg + curl --fail --location https://releases.warp.dev/linux/keys/warp.asc \ + --output /tmp/warpdotdev.asc + # Verified against releases.warp.dev/linux/keys/warp.asc on 2026-09-18. + # Reverify this fingerprint before updating the Warp signing key. + test "$( + gpg --show-keys --with-colons /tmp/warpdotdev.asc | + awk -F: '/^fpr:/ { print $10; exit }' + )" = "0913165C78D5B7A41B42AC657FF7AB39D60F803F" + gpg --dearmor --output /tmp/warpdotdev.gpg /tmp/warpdotdev.asc + sudo install -D -o root -g root -m 644 /tmp/warpdotdev.gpg \ + /etc/apt/keyrings/warpdotdev.gpg + sudo tee /etc/apt/sources.list.d/warpdotdev.list > /dev/null <<'EOF' + deb [arch=amd64 signed-by=/etc/apt/keyrings/warpdotdev.gpg] https://releases.warp.dev/linux/deb stable main + EOF + sudo apt-get update + sudo apt-get install -y oz-stable + oz --version + PROMPT="$(cat <<'EOF' Run the review-docs-pr skill against warpdotdev/docs PR #${{ github.event.pull_request.number }} at head SHA ${{ github.event.pull_request.head.sha }}. This PR carries the warpy-factory agent marker, so it requires the independent v1 agent-doc quality review pass (see @@ -60,6 +78,15 @@ jobs: changed file and line or quoted text, explain the problem, and state the requested resolution. Set reviewer_login to `github-actions[bot]`, the runner account that will publish the review. + 5. Your final response must contain only the single [SIGNAL:pr-review] JSON record. + Do not repeat the diff, review rationale, or findings outside that record. + EOF + )" + args=(agent run --output-format text --prompt "$PROMPT") + if [ -n "$WARP_AGENT_PROFILE" ]; then + args+=(--profile "$WARP_AGENT_PROFILE") + fi + oz "${args[@]}" > /tmp/agent-output.txt - name: Dismiss stale automated change requests env: GH_TOKEN: ${{ github.token }} @@ -78,9 +105,7 @@ jobs: - name: Publish the independent review env: GH_TOKEN: ${{ github.token }} - AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }} run: | - printf '%s' "$AGENT_OUTPUT" > /tmp/agent-output.txt python3 .agents/skills/doc_quality_policy/publish_review_signal.py \ --agent-output /tmp/agent-output.txt \ --pr "${{ github.event.pull_request.number }}" \ @@ -96,9 +121,7 @@ jobs: - name: Verify the current review signal and GitHub review env: GH_TOKEN: ${{ github.token }} - AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }} run: | - printf '%s' "$AGENT_OUTPUT" > /tmp/agent-output.txt python3 .agents/skills/doc_quality_policy/verify_review_signal.py \ --repo "${{ github.repository }}" \ --pr "${{ github.event.pull_request.number }}" \ diff --git a/astro.config.mjs b/astro.config.mjs index 3393454db..0e7f43640 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -228,7 +228,6 @@ export default defineConfig({ { label: 'Enterprise', description: 'Enterprise features, SSO, team management, and security.', paths: ['enterprise/**'] }, { label: 'Getting Started', description: 'Installation, quickstart, and migration guides.', paths: ['index', 'quickstart', 'getting-started/**'] }, { label: 'Knowledge and Collaboration', description: 'Warp Drive, teams, and the Admin Panel.', paths: ['knowledge-and-collaboration/**'] }, - { label: 'API & Reference', description: 'CLI and API reference.', paths: ['reference/**'] }, // All support-and-community/ pages. open-source-licenses.mdx is excluded // globally above (stack overflow in hast-util-to-text); the patch ensures // it's excluded from this custom set as well. diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml index eef3209a8..7f7c59d71 100644 --- a/developers/agent-api-openapi.yaml +++ b/developers/agent-api-openapi.yaml @@ -1,8 +1,8 @@ openapi: 3.0.0 info: - title: Warp Agent API + title: Warp Platform API version: 1.0.0 - description: "API for creating, managing, and querying Warp cloud agent runs.\n\nThese endpoints allow users to programmatically spawn agents, list runs, \nand retrieve detailed run information.\n" + description: "API for creating, managing, and querying factory and cloud agent runs.\n\nThese endpoints allow users to send work to factories, start standalone agents, list runs, \nand retrieve detailed run information.\n" contact: name: Warp Support url: https://docs.warp.dev diff --git a/src/content/docs/agents/agent-memory/index.mdx b/src/content/docs/agents/agent-memory/index.mdx index 76227aaf6..f4c8b38cb 100644 --- a/src/content/docs/agents/agent-memory/index.mdx +++ b/src/content/docs/agents/agent-memory/index.mdx @@ -85,8 +85,8 @@ Attach stores to agents with read-only or read-write access. Each attachment inc These capabilities aren't part of the research preview yet, but they're on the way: -* **Programmatic API access** - Read and manage memories and stores through the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), in addition to managing them in the {VARS.WEB_APP}. -* **Self-hosting support** - Run Agent Memory on a [self-hosted {VARS.WARP_AUTOMATION_PLATFORM}](/platform/self-hosting/) instance to meet security, privacy, and compliance requirements. +* **Programmatic API access** - Read and manage memories and stores through the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), in addition to managing them in the {VARS.WEB_APP}. +* **Self-hosting support** - Run Agent Memory on a [self-hosted {VARS.WARP_AUTOMATION_PLATFORM}](/factories/self-hosting/) instance to meet security, privacy, and compliance requirements. ## Join the waitlist diff --git a/src/content/docs/agents/capabilities/computer-use/index.mdx b/src/content/docs/agents/capabilities/computer-use/index.mdx index 3cbd73ae2..8f4dc46d8 100644 --- a/src/content/docs/agents/capabilities/computer-use/index.mdx +++ b/src/content/docs/agents/capabilities/computer-use/index.mdx @@ -44,7 +44,7 @@ Runs started from the Warp app don't use the server default: they always follow ### CLI -When running cloud agents with the [{VARS.WARP_AGENT_CLI}](/reference/cli/), use flags to control Computer Use per run: +When running cloud agents with the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), use flags to control Computer Use per run: ```bash oz agent run-cloud --computer-use --prompt "" @@ -53,7 +53,7 @@ oz agent run-cloud --no-computer-use --prompt "" ### API -When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp's built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run: +When creating a cloud agent run with the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp's built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run: ```json { @@ -65,7 +65,7 @@ When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/reference/api-an } ``` -For full API documentation, see the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) reference. +For full API documentation, see the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) reference. ### Web app diff --git a/src/content/docs/reference/cli/agent-profiles.mdx b/src/content/docs/agents/cli/oz-cli/agent-profiles.mdx similarity index 90% rename from src/content/docs/reference/cli/agent-profiles.mdx rename to src/content/docs/agents/cli/oz-cli/agent-profiles.mdx index b79d1c77e..b22350238 100644 --- a/src/content/docs/reference/cli/agent-profiles.mdx +++ b/src/content/docs/agents/cli/oz-cli/agent-profiles.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: Agent profiles control what the agent can do, how it behaves, and where it can act when running from the {VARS.WARP_AGENT_CLI}. Create profiles in the Warp app to configure file access, command execution, MCP server usage, model selection, and directory permissions, then reference them by ID in CLI commands. diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/agents/cli/oz-cli/api-keys.mdx similarity index 92% rename from src/content/docs/reference/cli/api-keys.mdx rename to src/content/docs/agents/cli/oz-cli/api-keys.mdx index 6e3862617..bda48d596 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/agents/cli/oz-cli/api-keys.mdx @@ -8,7 +8,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: API keys let the {VARS.WARP_AGENT_CLI} and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments. @@ -46,7 +46,7 @@ You can create an API key in either the -![API key management interface in Warp settings](../../../../assets/reference/api-key-management.png) +![API key management interface in Warp settings](../../../../../assets/reference/api-key-management.png)
API key management interface in Warp settings.
@@ -86,7 +86,7 @@ $ oz agent run --api-key "wk-xxx..." --prompt "analyze this codebase" ``` :::note -API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be [invalid or from an older format](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be [invalid or from an older format](/factories/api-and-sdk/troubleshooting/errors/authentication-required/). ::: ## Managing API keys @@ -107,11 +107,11 @@ The Warp app also shows additional metadata that isn't surfaced in the {VARS.WEB To delete an API key, find it in either the {VARS.WEB_APP} or the Warp app's API Keys list and click the delete icon next to the key. -Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access and may return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access and may return an [`authentication_required` error](/factories/api-and-sdk/troubleshooting/errors/authentication-required/). ## Manage API keys from the CLI -In addition to the web and Warp app surfaces, you can manage API keys directly with the [{VARS.WARP_AGENT_CLI}](/reference/cli/). These commands are useful for scripting key rotation and for headless environments. +In addition to the web and Warp app surfaces, you can manage API keys directly with the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/). These commands are useful for scripting key rotation and for headless environments. ### List keys diff --git a/src/content/docs/reference/cli/artifacts.mdx b/src/content/docs/agents/cli/oz-cli/artifacts.mdx similarity index 85% rename from src/content/docs/reference/cli/artifacts.mdx rename to src/content/docs/agents/cli/oz-cli/artifacts.mdx index de7bb6f6d..cf2acab1a 100644 --- a/src/content/docs/reference/cli/artifacts.mdx +++ b/src/content/docs/agents/cli/oz-cli/artifacts.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: Artifacts are files that an agent produces during a run and uploads to Warp — screenshots, generated reports, build outputs, logs, or any other file the agent saves alongside its conversation. Use `oz artifact` to inspect those files from outside the run and pull them down to your machine. @@ -22,7 +22,7 @@ Use artifacts when you need to retrieve files an agent produced after a run comp * **Local inspection** - Pull a generated file (HTML, image, CSV) onto your laptop to review. * **CI integration** - Fetch an agent-produced build artifact from a pipeline step that runs after the agent finishes. -Artifacts are referenced by an artifact UID. You can find UIDs in the agent's run detail view, in the JSON returned by [`oz run get`](/reference/cli/), or in the response from the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). +Artifacts are referenced by an artifact UID. You can find UIDs in the agent's run detail view, in the JSON returned by [`oz run get`](/agents/cli/oz-cli/), or in the response from the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/). ## `oz artifact get` @@ -78,5 +78,5 @@ oz artifact download "$ARTIFACT_UID" --out ./latest-report.html ## Related -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - retrieve artifacts programmatically over HTTP. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - retrieve artifacts programmatically over HTTP. * [Scheduled cloud agents](/platform/triggers/scheduled-agents/) - common producer of recurring artifacts that downstream tooling consumes. diff --git a/src/content/docs/reference/cli/federate.mdx b/src/content/docs/agents/cli/oz-cli/federate.mdx similarity index 95% rename from src/content/docs/reference/cli/federate.mdx rename to src/content/docs/agents/cli/oz-cli/federate.mdx index a2bda5c55..38283ee29 100644 --- a/src/content/docs/reference/cli/federate.mdx +++ b/src/content/docs/agents/cli/oz-cli/federate.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: `oz federate` issues short-lived OIDC identity tokens for the agent that's currently running. Use these tokens to authenticate to cloud providers (AWS, GCP, Azure, and other OIDC-aware systems) without baking long-lived credentials into your environment. diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/agents/cli/oz-cli/index.mdx similarity index 92% rename from src/content/docs/reference/cli/index.mdx rename to src/content/docs/agents/cli/oz-cli/index.mdx index e301e9259..6fa1b9bb5 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/agents/cli/oz-cli/index.mdx @@ -9,7 +9,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary, which previously shipped as `warp-cli`) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. The [Warp Agent CLI reference](/agents/cli/reference/) does not yet document `warp` equivalents for every workflow on this page. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary, which previously shipped as `warp-cli`) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: The {VARS.WARP_AGENT_CLI} is the command-line tool for running and managing Warp's cloud agents from any terminal, script, or CI pipeline. Use it to start agents locally or in the cloud, connect MCP servers, configure integrations, and authenticate without requiring the Warp desktop app. @@ -18,7 +18,7 @@ The {VARS.WARP_AGENT_CLI} is the command-line tool for running and managing Warp The {VARS.WARP_AGENT_CLI} is the command-line tool that lets you run [Cloud Agents](/platform/) from anywhere, including terminals, scripts, automated systems, or services. -It's the standard runtime entry point that turns a **prompt** plus **configuration** into an **executable agent task** that runs on either a **Warp-hosted or [self-hosted](/platform/self-hosting/) runner**. +It's the standard runtime entry point that turns a **prompt** plus **configuration** into an **executable agent task** that runs on either a **Warp-hosted or [self-hosted](/factories/self-hosting/) runner**. With the {VARS.WARP_AGENT_CLI}, you can: @@ -189,7 +189,7 @@ If you weren't logged in, the command prints `You are not logged in.` and exits. Use an API key when the environment must authenticate on its own, such as CI pipelines, headless servers, VMs, Codespaces, or containers. API keys let the CLI authenticate non-interactively. -For detailed instructions on creating, managing, and using API keys, see [API Keys](/reference/cli/api-keys/). +For detailed instructions on creating, managing, and using API keys, see [API Keys](/agents/cli/oz-cli/api-keys/). **Quickstart:** @@ -230,10 +230,10 @@ oz agent run --prompt "set up a new Rust crate named warp-cli" * `--cwd ` (`-C`) — run from a different directory. * `--name ` (`-n`) — label the run for grouping and traceability. -* `--share` — share the session with teammates (see [Collaboration](/reference/cli/#collaboration)). -* `--profile ` — use a specific agent profile (see [Using Agent Profiles](/reference/cli/#using-agent-profiles)). +* `--share` — share the session with teammates (see [Collaboration](/agents/cli/oz-cli/#collaboration)). +* `--profile ` — use a specific agent profile (see [Using Agent Profiles](/agents/cli/oz-cli/#using-agent-profiles)). * `--model ` — override the default model (see [Model Choice](/agents/inference/model-choice/)). -* `--skill ` — use a skill as the base prompt (see [Using Skills](/reference/cli/#using-skills)). +* `--skill ` — use a skill as the base prompt (see [Using Skills](/agents/cli/oz-cli/#using-skills)). * `--mcp ` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated. * `--environment ` (`-e`) — run in a specific cloud environment. * `--file ` (`-f`) — load run configuration from a YAML or JSON file. @@ -263,13 +263,13 @@ oz agent run-cloud \ * `--environment ` (`-e`) — select the environment to run in. * `--no-environment` — run without an environment (not recommended). * `--open` — view the agent's session in Warp once it's available. -* `--name ` (`-n`) — label the run for grouping and traceability (see [Naming runs](/reference/cli/#naming-runs) below). -* `--title ` — set the title shown for the run and its conversation (see [Titling runs](/reference/cli/#titling-runs) below). -* `--parent-run-id <RUN_ID>` — start the run as an orchestration child of an existing run (see [Starting a run as an orchestration child](/reference/cli/#starting-a-run-as-an-orchestration-child) below). -* `--agent <UID>` — run as a saved [named agent](/platform/agents/), applying its configuration (skills, secrets, base model, and default environment) and attributing credit usage to it (see [Managing named agents](/reference/cli/#managing-named-agents) below). +* `--name <NAME>` (`-n`) — label the run for grouping and traceability (see [Naming runs](/agents/cli/oz-cli/#naming-runs) below). +* `--title <TITLE>` — set the title shown for the run and its conversation (see [Titling runs](/agents/cli/oz-cli/#titling-runs) below). +* `--parent-run-id <RUN_ID>` — start the run as an orchestration child of an existing run (see [Starting a run as an orchestration child](/agents/cli/oz-cli/#starting-a-run-as-an-orchestration-child) below). +* `--agent <UID>` — run as a saved [named agent](/platform/agents/), applying its configuration (skills, secrets, base model, and default environment) and attributing credit usage to it (see [Managing named agents](/agents/cli/oz-cli/#managing-named-agents) below). * `--mcp <SPEC>` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated. * `--model <MODEL_ID>` — override the default model. -* `--skill <SPEC>` — use a skill from the environment's repository as the base prompt (see [Using Skills](/reference/cli/#using-skills)). +* `--skill <SPEC>` — use a skill from the environment's repository as the base prompt (see [Using Skills](/agents/cli/oz-cli/#using-skills)). * `--host <WORKER_ID>` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. * `--attach <PATH>` — attach an image file to the agent query. Can be repeated (maximum 5). * `--computer-use` / `--no-computer-use` — enable or disable [Computer Use](/agents/capabilities/computer-use/) for this run. @@ -306,7 +306,7 @@ The `--name` flag assigns a config name to the run. Use it to group related runs **Why naming matters:** -When your team runs many agents across schedules, integrations, and ad-hoc triggers, `name` lets you answer questions like "how many distinct workflows are we running?" and "how often does this particular workflow run?" You can filter runs by name using the `name` query parameter on `GET /agent/runs` in the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). +When your team runs many agents across schedules, integrations, and ad-hoc triggers, `name` lets you answer questions like "how many distinct workflows are we running?" and "how often does this particular workflow run?" You can filter runs by name using the `name` query parameter on `GET /agent/runs` in the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/). **Examples:** @@ -359,7 +359,7 @@ Pass the run ID of the run doing the spawning. Omit the flag for ordinary standa #### Reusing saved prompts and Warp Drive objects -You can reuse saved prompts with `--saved-prompt`, and reference notebooks, workflows, and rules inline in any `--prompt` string. See [Referencing Warp Drive objects](/reference/cli/warp-drive/) for details. +You can reuse saved prompts with `--saved-prompt`, and reference notebooks, workflows, and rules inline in any `--prompt` string. See [Referencing Warp Drive objects](/agents/cli/oz-cli/warp-drive/) for details. #### Choosing an execution harness @@ -379,19 +379,19 @@ Create the auth secret first with `oz secret create claude api-key <SECRET_NAME> Agent profiles control what the agent can do, how it behaves, and where it can act. Use the `--profile` flag with `oz agent run` to apply a specific profile. -See [Agent profiles](/reference/cli/agent-profiles/) for how to find profile IDs and apply them. +See [Agent profiles](/agents/cli/oz-cli/agent-profiles/) for how to find profile IDs and apply them. ## Using MCP servers MCP servers connect agents to external systems like GitHub, Linear, or Sentry. Use the `--mcp` flag with any of three formats: a Warp MCP server UUID, inline JSON, or a path to a JSON config file. -See [MCP Servers](/reference/cli/mcp-servers/) for full details, including how to find UUIDs, combine multiple servers, and handle environment variables on remote machines. +See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) for full details, including how to find UUIDs, combine multiple servers, and handle environment variables on remote machines. ## Using skills [Skills](/agents/capabilities/skills/) are reusable instruction sets that teach agents how to perform specific tasks. Use the `--skill` flag to run an agent from a skill stored in a repository. -See [Skills](/reference/cli/skills/) for supported spec formats and examples for both local and cloud agent runs. +See [Skills](/agents/cli/oz-cli/skills/) for supported spec formats and examples for both local and cloud agent runs. ## Collaboration @@ -557,14 +557,14 @@ oz environment image list ### `oz artifact get` / `oz artifact download` -Inspect and retrieve files an agent produced during a run. See [Artifacts](/reference/cli/artifacts/) for details. +Inspect and retrieve files an agent produced during a run. See [Artifacts](/agents/cli/oz-cli/artifacts/) for details. ### `oz federate issue-token` -Issue a short-lived OIDC identity token from inside a running agent to authenticate to cloud providers without long-lived credentials. See [Federated identity tokens](/reference/cli/federate/) for details. +Issue a short-lived OIDC identity token from inside a running agent to authenticate to cloud providers without long-lived credentials. See [Federated identity tokens](/agents/cli/oz-cli/federate/) for details. --- ## Troubleshooting -For built-in CLI help commands and solutions to common errors — including authentication issues, agent failures, environment problems, and Docker image issues — see [Troubleshooting](/reference/cli/troubleshooting/). +For built-in CLI help commands and solutions to common errors — including authentication issues, agent failures, environment problems, and Docker image issues — see [Troubleshooting](/agents/cli/oz-cli/troubleshooting/). diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/agents/cli/oz-cli/integration-setup.mdx similarity index 94% rename from src/content/docs/reference/cli/integration-setup.mdx rename to src/content/docs/agents/cli/oz-cli/integration-setup.mdx index e158952da..5bb3b80cd 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/agents/cli/oz-cli/integration-setup.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: This article describes the environment and integration setup that is required before you can trigger agents from external tools, like Slack or Linear. You will learn how to: @@ -60,9 +60,9 @@ Setting up an integration consists of three steps. :::tip If setup fails, use the returned error code to narrow the fix. Common errors include: -* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) (environment initialization issues) -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or external-service authorization) -* [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) (incomplete integration setup) +* [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) (environment initialization issues) +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or external-service authorization) +* [`integration_not_configured`](/factories/api-and-sdk/troubleshooting/errors/integration-not-configured/) (incomplete integration setup) ::: --- @@ -191,7 +191,7 @@ You typically only need to handle this once per team, unless your repo access ch #### Team-level GitHub authorization -For automated workflows that use an [agent API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Warp Factories GitHub App instead of an individual's personal token. +For automated workflows that use an [agent API key](/agents/cli/oz-cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Warp Factories GitHub App instead of an individual's personal token. This requires a Warp team admin to enable the GitHub organization in the Admin Panel (**Settings** > **Admin Panel** > **Platform**). Once configured, tasks initiated with an agent API key can clone repos and open pull requests using the GitHub App installation token. @@ -309,4 +309,4 @@ You now have everything needed to trigger agents from your team's tools. From he * [Cloud Agents Overview](/platform/) * [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) * [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), [GitHub](/platform/integrations/github/), and [GitHub Actions](/platform/integrations/github-actions/) integrations -* [Troubleshooting](/reference/cli/troubleshooting/) +* [Troubleshooting](/agents/cli/oz-cli/troubleshooting/) diff --git a/src/content/docs/reference/cli/mcp-servers.mdx b/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx similarity index 95% rename from src/content/docs/reference/cli/mcp-servers.mdx rename to src/content/docs/agents/cli/oz-cli/mcp-servers.mdx index 4e32feca0..2c2fb78f9 100644 --- a/src/content/docs/reference/cli/mcp-servers.mdx +++ b/src/content/docs/agents/cli/oz-cli/mcp-servers.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: MCP servers connect agents to external systems like GitHub, Linear, or Sentry. To use a [Model Context Protocol (MCP)](/agents/capabilities/mcp/) server from the CLI, use the `--mcp` flag with `oz agent run` or `oz agent run-cloud`. @@ -49,7 +49,7 @@ $ oz mcp list Alternatively, copy the UUID from Warp in **Settings** > **Agents** > **MCP servers**. <figure style={{ maxWidth: "375px" }}> -![MCP servers page, showing a server with its UUID](../../../../assets/reference/mcp-server-id.png) +![MCP servers page, showing a server with its UUID](../../../../../assets/reference/mcp-server-id.png) <figcaption>MCP servers page, showing a server with its UUID.</figcaption> </figure> diff --git a/src/content/docs/reference/cli/quickstart.mdx b/src/content/docs/agents/cli/oz-cli/quickstart.mdx similarity index 71% rename from src/content/docs/reference/cli/quickstart.mdx rename to src/content/docs/agents/cli/oz-cli/quickstart.mdx index 2303b2535..a636edc7a 100644 --- a/src/content/docs/reference/cli/quickstart.mdx +++ b/src/content/docs/agents/cli/oz-cli/quickstart.mdx @@ -9,7 +9,7 @@ import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: This guide walks you through the essentials to get up and running with the {VARS.WARP_AGENT_CLI} in less than 5 minutes: installing the CLI, authenticating, running your first local agent, and optionally connecting MCP servers to give the agent access to external tools. @@ -21,7 +21,7 @@ Watch this short demo of the {VARS.WARP_AGENT_CLI} workflow: If you already have the [Warp desktop app installed](/getting-started/quickstart/installation-and-setup/), the **CLI is included** and available in Warp. -If not, see [Installing the CLI](/reference/cli/#installing-the-cli) for installation options for all platforms. +If not, see [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli) for installation options for all platforms. ## 2. Authenticate @@ -44,7 +44,7 @@ Interactive login works on both **local** and **remote** machines, and does not export WARP_API_KEY="wk-..." ``` -Create an API key in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. See [API Keys](/reference/cli/api-keys/) for guidance on personal vs. [agent keys](/platform/agents/) and on security best practices. +Create an API key in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. See [API Keys](/agents/cli/oz-cli/api-keys/) for guidance on personal vs. [agent keys](/platform/agents/) and on security best practices. ::: ## 3. Run an agent @@ -83,17 +83,17 @@ You can connect MCP servers to give the agent access to external tools like GitH oz agent run --mcp '{"github": {"url": "https://api.githubcopilot.com/mcp/"}}' --prompt "Open a pull request that fixes TODOs in this repo" ``` -See [MCP Servers](/reference/cli/mcp-servers/) for all supported formats, including UUID references and multi-server configurations. +See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) for all supported formats, including UUID references and multi-server configurations. ## Next steps Once you've successfully set up and run your agent, explore other configurations and workflows with the {VARS.WARP_AGENT_CLI}: -* Customize behavior with [agent profiles](/reference/cli/agent-profiles/). -* [Reuse prompts](/reference/cli/warp-drive/) with `--saved-prompt`. -* Connect agents to external systems using [MCP Servers](/reference/cli/mcp-servers/). -* Authenticate with [API keys](/reference/cli/api-keys/) for automated environments or workflows. -* Get up-to-date information about the {VARS.WARP_AGENT_CLI} using the [`oz help` command](/reference/cli/troubleshooting/#getting-help). +* Customize behavior with [agent profiles](/agents/cli/oz-cli/agent-profiles/). +* [Reuse prompts](/agents/cli/oz-cli/warp-drive/) with `--saved-prompt`. +* Connect agents to external systems using [MCP Servers](/agents/cli/oz-cli/mcp-servers/). +* Authenticate with [API keys](/agents/cli/oz-cli/api-keys/) for automated environments or workflows. +* Get up-to-date information about the {VARS.WARP_AGENT_CLI} using the [`oz help` command](/agents/cli/oz-cli/troubleshooting/#getting-help). * Run agents in CI with the [GitHub Actions quickstart](/platform/integrations/quickstart-github-actions/). -Continue reading the [{VARS.WARP_AGENT_CLI} reference](/reference/cli/) to learn how to install the CLI on different platforms, authenticate in different environments, and configure agents for real-world workflows. +Continue reading the [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/) to learn how to install the CLI on different platforms, authenticate in different environments, and configure agents for real-world workflows. diff --git a/src/content/docs/reference/cli/skills.mdx b/src/content/docs/agents/cli/oz-cli/skills.mdx similarity index 89% rename from src/content/docs/reference/cli/skills.mdx rename to src/content/docs/agents/cli/oz-cli/skills.mdx index e873bb474..460e4d7a6 100644 --- a/src/content/docs/reference/cli/skills.mdx +++ b/src/content/docs/agents/cli/oz-cli/skills.mdx @@ -9,7 +9,7 @@ description: >- import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: [Skills](/agents/capabilities/skills/) are reusable instruction sets that teach agents how to perform specific tasks. Use the `--skill` flag to run an agent from a skill in a repository accessible to your environment. diff --git a/src/content/docs/reference/cli/troubleshooting.mdx b/src/content/docs/agents/cli/oz-cli/troubleshooting.mdx similarity index 88% rename from src/content/docs/reference/cli/troubleshooting.mdx rename to src/content/docs/agents/cli/oz-cli/troubleshooting.mdx index 3fa5130a0..1c96360fd 100644 --- a/src/content/docs/reference/cli/troubleshooting.mdx +++ b/src/content/docs/agents/cli/oz-cli/troubleshooting.mdx @@ -7,7 +7,7 @@ description: >- import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: Solutions for common {VARS.WARP_AGENT_CLI} errors, including authentication issues, agent failures, environment configuration, GitHub access problems, and Docker image compatibility. Use `oz help` for built-in documentation on any command. @@ -39,10 +39,10 @@ oz --version **Authentication issues** * Interactive login: ensure you've completed the browser-based flow with `oz login`. -* API keys: confirm the key is valid, not expired, and exported correctly. Invalid, expired, or missing keys can return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/). +* API keys: confirm the key is valid, not expired, and exported correctly. Invalid, expired, or missing keys can return an [`authentication_required` error](/factories/api-and-sdk/troubleshooting/errors/authentication-required/). **Agent or MCP errors**\ -Ensure your agent profile and [MCP servers](/agents/capabilities/mcp/) are configured properly, with correct permissions. See [MCP Servers](/reference/cli/mcp-servers/) and [Agent profiles](/reference/cli/agent-profiles/) for details. +Ensure your agent profile and [MCP servers](/agents/capabilities/mcp/) are configured properly, with correct permissions. See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) and [Agent profiles](/agents/cli/oz-cli/agent-profiles/) for details. --- @@ -118,7 +118,7 @@ oz environment delete <ID> Add `--force` to skip confirmation checks for environments used by integrations. -Only do this once you've confirmed no active integrations are relying on that environment. If an integration points to a deleted environment, requests from Slack/Linear will fail with a [`resource_not_found` error](/reference/api-and-sdk/troubleshooting/errors/resource-not-found/) until you create a new integration with a valid environment. +Only do this once you've confirmed no active integrations are relying on that environment. If an integration points to a deleted environment, requests from Slack/Linear will fail with a [`resource_not_found` error](/factories/api-and-sdk/troubleshooting/errors/resource-not-found/) until you create a new integration with a valid environment. ### Integrations @@ -149,7 +149,7 @@ This happens when: * You add a repo that Warp doesn’t have access to yet, or * You personally haven’t granted the Warp GitHub app permissions for that repo. -Follow the GitHub popup flow to install/adjust the Warp GitHub app. Missing external authorization can return an [`external_authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). +Follow the GitHub popup flow to install/adjust the Warp GitHub app. Missing external authorization can return an [`external_authentication_required` error](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/). #### **The agent can’t open PRs or push changes to my repo** @@ -160,7 +160,7 @@ Check the following: 2. **Warp GitHub app has access to that repo** 1. In GitHub’s settings, confirm the Warp app is installed and that the repo is selected. 3. **You have write access** - 1. The agent inherits your GitHub permissions. If you only have read access, Warp can’t open PRs or push branches on your behalf, and the run may return a [`not_authorized` error](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). + 1. The agent inherits your GitHub permissions. If you only have read access, Warp can’t open PRs or push branches on your behalf, and the run may return a [`not_authorized` error](/factories/api-and-sdk/troubleshooting/errors/not-authorized/). ### Docker image & environment failures @@ -172,7 +172,7 @@ Check: 2. The image is public on Docker Hub. 3. You can pull it locally: `docker pull <image_name>` -If local docker pull fails, fix the image visibility/name first, then recreate or update the environment with a working image. Image pull and setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). +If local docker pull fails, fix the image visibility/name first, then recreate or update the environment with a working image. Image pull and setup failures can surface as [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/). #### **The agent can’t find tools or runtimes inside the environment** @@ -183,7 +183,7 @@ This usually means the Docker image is missing required dependencies. Fix by eit #### **I see "VM failed before the agent could run. This is likely an issue with your Docker image"** -This typically means your Docker image uses musl libc instead of glibc. Alpine Linux and other musl-based images are not compatible with the agent runtime, and this can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). +This typically means your Docker image uses musl libc instead of glibc. Alpine Linux and other musl-based images are not compatible with the agent runtime, and this can surface as [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/). Fix: diff --git a/src/content/docs/reference/cli/warp-drive.mdx b/src/content/docs/agents/cli/oz-cli/warp-drive.mdx similarity index 86% rename from src/content/docs/reference/cli/warp-drive.mdx rename to src/content/docs/agents/cli/oz-cli/warp-drive.mdx index 6d501db51..e15cb8439 100644 --- a/src/content/docs/reference/cli/warp-drive.mdx +++ b/src/content/docs/agents/cli/oz-cli/warp-drive.mdx @@ -9,7 +9,7 @@ sidebar: import { VARS } from '@data/vars'; :::caution -The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today. +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change. ::: Reference saved Warp Drive objects in {VARS.WARP_AGENT_CLI} commands to reuse prompts, notebooks, workflows, and rules as agent context. Pass a saved prompt ID with `--saved-prompt` or inline Warp Drive references using `<workflow:id>`, `<notebook:id>`, or `<rule:id>` syntax. diff --git a/src/content/docs/agents/cli/quickstart.mdx b/src/content/docs/agents/cli/quickstart.mdx index 13b369e84..389a9e094 100644 --- a/src/content/docs/agents/cli/quickstart.mdx +++ b/src/content/docs/agents/cli/quickstart.mdx @@ -80,7 +80,7 @@ When login completes, the CLI shows its start screen with the version, a short " WARP_API_KEY=YOUR_API_KEY warp ``` -You can also pass the `--api-key` flag, but prefer the environment variable. Command-line arguments can be captured in shell history and process listings. See [API keys](/reference/cli/api-keys/) to learn how to create one. +You can also pass the `--api-key` flag, but prefer the environment variable. Command-line arguments can be captured in shell history and process listings. See [API keys](/agents/cli/oz-cli/api-keys/) to learn how to create one. ::: ## 3. Run your first prompt diff --git a/src/content/docs/agents/cli/reference.mdx b/src/content/docs/agents/cli/reference.mdx index 79f770b25..bbd1ccd5e 100644 --- a/src/content/docs/agents/cli/reference.mdx +++ b/src/content/docs/agents/cli/reference.mdx @@ -32,7 +32,7 @@ warp --api-key YOUR_API_KEY Command-line arguments can be captured in shell history and process listings. Prefer the `WARP_API_KEY` environment variable, ideally populated from a secret manager. ::: -Create a key in the Warp app under **Settings** > **Cloud platform** > **API keys**. See the [API keys reference](/reference/cli/api-keys/) for details. +Create a key in the Warp app under **Settings** > **Cloud platform** > **API keys**. See the [API keys reference](/agents/cli/oz-cli/api-keys/) for details. ### `--auto-approve` diff --git a/src/content/docs/agents/inference/model-choice.mdx b/src/content/docs/agents/inference/model-choice.mdx index 44addc041..3c3bca0b6 100644 --- a/src/content/docs/agents/inference/model-choice.mdx +++ b/src/content/docs/agents/inference/model-choice.mdx @@ -16,7 +16,7 @@ Warp lets you choose from a curated set of large language models (LLMs) to power **Warp supports the following models.** -The `model_id` values shown below can be used when configuring models via the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) or [CLI](/reference/cli/). +The `model_id` values shown below can be used when configuring models via the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) or [CLI](/agents/cli/oz-cli/). ### Auto models diff --git a/src/content/docs/changelog/2025.mdx b/src/content/docs/changelog/2025.mdx index a87fa2fa0..118869e0f 100644 --- a/src/content/docs/changelog/2025.mdx +++ b/src/content/docs/changelog/2025.mdx @@ -192,7 +192,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd **New Features** -* Warp agents are now available via the command line. See the [CLI reference](https://docs.warp.dev/reference/cli). +* Warp agents are now available via the command line. See the [CLI reference](https://docs.warp.dev/agents/cli/oz-cli). * Added support for custom Regex names in Enterprise Secret Redaction. **Improvements** diff --git a/src/content/docs/changelog/2026.mdx b/src/content/docs/changelog/2026.mdx index 136430e66..9d8a85995 100644 --- a/src/content/docs/changelog/2026.mdx +++ b/src/content/docs/changelog/2026.mdx @@ -1673,7 +1673,7 @@ Oz is Warp's orchestration platform for cloud agents: launch parallel agents, au * **Cloud environments for consistent execution** — configure Docker-based environments (unlimited repos + setup commands) and run agents in isolated cloud sandboxes. [Environments docs →](https://docs.warp.dev/platform/environments) * **Track agents from the web** — manage runs, create schedules, configure environments, and set up integrations from any browser in the <a href="https://oz.warp.dev">Oz web app</a>. * **Schedule agents based on Skills** — run agents automatically on a cron schedule for code cleanup, dependency updates, and issue triage. See [Scheduled Agents](/platform/triggers/scheduled-agents/). -* **Programmable by default** — orchestrate agents via the CLI and integrate Oz into tools and services via the [API and CLI reference](/reference/). +* **Programmable by default** — orchestrate agents via the CLI and integrate Oz into tools and services via the [API reference](/factories/developer-tools/). #### Warp Upgrades diff --git a/src/content/docs/enterprise/enterprise-features/analytics-api.mdx b/src/content/docs/enterprise/enterprise-features/analytics-api.mdx index 3dae9cf28..11f3a801d 100644 --- a/src/content/docs/enterprise/enterprise-features/analytics-api.mdx +++ b/src/content/docs/enterprise/enterprise-features/analytics-api.mdx @@ -29,7 +29,7 @@ Before you can call the API, your team must satisfy all of the following: * **Enterprise plan** - The Analytics API is available to all enterprise teams during Early Access; no separate enrollment is required. * **Admin role on the team** - Calls are rejected unless the authenticated user has admin-level permissions on the enterprise team. See [Roles and permissions](/enterprise/team-management/roles-and-permissions/). -* **A personal Warp API key** - Authenticate requests with a key from **Settings** > **Cloud platform** > **API keys** in the Warp app. See [API Keys](/reference/cli/api-keys/) for step-by-step instructions. Agent API keys (including legacy team keys) are not accepted by these endpoints — only personal API keys belonging to a team admin work. +* **A personal Warp API key** - Authenticate requests with a key from **Settings** > **Cloud platform** > **API keys** in the Warp app. See [API Keys](/agents/cli/oz-cli/api-keys/) for step-by-step instructions. Agent API keys (including legacy team keys) are not accepted by these endpoints — only personal API keys belonging to a team admin work. * **Enterprise Usage Reporting toggle enabled** - In the Warp app, go to **Admin Panel** > **Privacy** and turn on **Enterprise Usage Reporting (Early Access)**. Until this toggle is on, no usage data is recorded for your team and the endpoints will return empty datasets even if every other prerequisite is met. :::caution @@ -297,7 +297,7 @@ Any authenticated user with admin-level permissions on an enterprise team. Calls ### What kind of API key works? -Only **personal** Warp API keys created by an admin from **Settings** > **Cloud platform** > **API keys**. Agent API keys (including legacy team keys) are explicitly rejected by these endpoints. See [API Keys](/reference/cli/api-keys/) for how to create one. +Only **personal** Warp API keys created by an admin from **Settings** > **Cloud platform** > **API keys**. Agent API keys (including legacy team keys) are explicitly rejected by these endpoints. See [API Keys](/agents/cli/oz-cli/api-keys/) for how to create one. ### Are these calls billed? @@ -309,7 +309,7 @@ The `events` endpoint enforces a hard 365-day window between `start_date` and `e ## Related resources -* [API Keys](/reference/cli/api-keys/) - Create and manage personal Warp API keys. +* [API Keys](/agents/cli/oz-cli/api-keys/) - Create and manage personal Warp API keys. * [Admin Panel](/enterprise/team-management/admin-panel/) - Manage team settings, including the **Privacy** section. * [Roles and permissions](/enterprise/team-management/roles-and-permissions/) - Required admin role for Analytics API access. * [Architecture and deployment](/enterprise/enterprise-features/architecture-and-deployment/) - Where enterprise data is stored and how it transits Warp's infrastructure. diff --git a/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx b/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx index b516e1313..2cbcf52d3 100644 --- a/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx +++ b/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx @@ -157,7 +157,7 @@ Consider the following when selecting a deployment model: ## Related resources * [Architecture reference](/platform/architecture/) - Diagrams of the stack, the run lifecycle, self-hosted execution, and data boundaries -* [Deployment Patterns](/platform/deployment-patterns/) - Detailed patterns for CLI-only, {VARS.WARP_AUTOMATION_PLATFORM}-hosted, and self-hosted setups +* [Deployment Patterns](/factories/deployment-patterns/) - Detailed patterns for CLI-only, {VARS.WARP_AUTOMATION_PLATFORM}-hosted, and self-hosted setups * [Security overview](/enterprise/security-and-compliance/security-overview/) - Data handling, encryption, and compliance details * [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) - Route inference through your own cloud infrastructure * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure agent policies and security settings diff --git a/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx b/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx index c21fb46bc..25e380115 100644 --- a/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx +++ b/src/content/docs/enterprise/getting-started/getting-started-enterprise.mdx @@ -164,7 +164,7 @@ Once your team is set up: * **BYOLLM** - Set up [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through your cloud infrastructure for data locality and cost control * **Team-managed API keys and endpoints** - Configure [shared provider API keys and custom endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) for your team in the Admin Panel, available in both interactive sessions and cloud agents * **Monitor usage** - Review usage analytics in the Admin Panel to track adoption and measure engineering productivity gains -* **Self-hosting** - Run agents on your own infrastructure to control where agents run and keep repository clones on your own machines. See [Self-hosting](/platform/self-hosting/) for setup instructions +* **Self-hosting** - Run agents on your own infrastructure to control where agents run and keep repository clones on your own machines. See [Self-hosting](/factories/self-hosting/) for setup instructions ## Troubleshooting diff --git a/src/content/docs/enterprise/team-management/admin-panel.mdx b/src/content/docs/enterprise/team-management/admin-panel.mdx index 896571486..c225b9f8c 100644 --- a/src/content/docs/enterprise/team-management/admin-panel.mdx +++ b/src/content/docs/enterprise/team-management/admin-panel.mdx @@ -269,7 +269,7 @@ Controls how screenshots and video recordings captured with [Computer Use](/agen **Enabled GitHub Orgs** -The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations. That association does two things: it lets cloud agents initiated with an [agent API key](/reference/cli/api-keys/) clone repositories and open pull requests using the Warp Factories GitHub App, and it tells Warp which team owns runs started from the [GitHub integration](/platform/integrations/github/) when someone mentions `@warp-agent` in those repositories. +The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations. That association does two things: it lets cloud agents initiated with an [agent API key](/agents/cli/oz-cli/api-keys/) clone repositories and open pull requests using the Warp Factories GitHub App, and it tells Warp which team owns runs started from the [GitHub integration](/platform/integrations/github/) when someone mentions `@warp-agent` in those repositories. To configure: diff --git a/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx similarity index 88% rename from src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx rename to src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index 3bdfd4c2f..b45b694f7 100644 --- a/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/factories/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: "Demo: Sentry monitoring with SDK" description: >- Build a Sentry webhook handler that triggers agents to investigate errors @@ -17,6 +18,8 @@ Example repository: [**Sentry monitor example repository**](https://github.com/w In this demo, Ben builds a small TypeScript “Sentry monitor” service that listens for specific Sentry alerts (like a Go nil pointer dereference) and triggers a Warp cloud agent to investigate. The server validates the webhook, extracts the stack trace, and injects it into an agent run inside a Warp Environment so the agent can inspect the repo and propose a fix. +To route the alert through a factory's named agents and workflow instead, use [factory endpoints](/factories/factory-api/) to dispatch the request. This example remains useful for custom standalone cloud-agent intake. + He also covers the task lifecycle basics in the TypeScript SDK (running an agent, polling task state to fetch a session link for debugging), and shows the end result: a draft GitHub pull request created from the Sentry event for a maintainer to review. **What Ben covers** diff --git a/src/content/docs/reference/api-and-sdk/index.mdx b/src/content/docs/factories/api-and-sdk/index.mdx similarity index 68% rename from src/content/docs/reference/api-and-sdk/index.mdx rename to src/content/docs/factories/api-and-sdk/index.mdx index 2815e592d..7746f0776 100644 --- a/src/content/docs/reference/api-and-sdk/index.mdx +++ b/src/content/docs/factories/api-and-sdk/index.mdx @@ -1,23 +1,24 @@ --- -title: "{{API_SDK_NAME}} reference" +topic: factories +title: Agent & run endpoints sidebar: - label: "{{API_SDK_NAME}}" + label: "Agent & run endpoints" description: >- - Create and inspect cloud agent runs over HTTP, or use the Python and - TypeScript SDKs for typed requests, retries, and error handling. + Start, manage, and inspect cloud agent runs with the Agent and run endpoints + in the Warp Platform API. --- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -The {VARS.API_SDK_NAME} lets you create, monitor, and inspect cloud agent runs programmatically. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling. The SDKs are ideal for CI pipelines, internal tools, and custom integrations. +Agent & run endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to start standalone cloud agent runs and to monitor, continue, or cancel any run after it starts. To find a factory and send it new work, use [factory endpoints](/factories/factory-api/). :::note -Some examples in this reference and the [CLI reference](/reference/cli/) use `oz` commands (for example, `oz environment list`) from the {VARS.WARP_AGENT_CLI}. Those commands remain supported through the end of September 2026. The [Warp Agent CLI reference](/agents/cli/reference/) does not yet document a `warp` equivalent. +Some examples use `oz` commands, such as `oz environment list`, from the {VARS.WARP_AGENT_CLI}. Existing commands remain supported during the transition. ::: -### API overview +## Use Agent & run endpoints -The {VARS.API_SDK_NAME} lets you create and inspect [Cloud Agent](/platform/) runs over HTTP from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app. +Agent & run endpoints let you create and inspect [cloud agent](/platform/) runs over HTTP from CI, cron, backend services, and internal tools, without requiring the Warp desktop app. **With the API you can:** @@ -28,23 +29,23 @@ The {VARS.API_SDK_NAME} lets you create and inspect [Cloud Agent](/platform/) ru :::caution This page is a high-level overview.\ \ -For full API endpoint details, refer to the [**Agents API Reference**](/api). For schema definitions, see the SDK repos: [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript). +For endpoint details, use the [**Warp Platform API reference**](/api). For SDK schemas, use the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript) repositories. ::: -To send work to a [Warp factory](/factories/), use the [factory API](/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/run` with a foreman's `agent_identity_uid`. Everything on this page - follow-ups, cancellation, status - still applies once a factory run is dispatched. +To send work to a [Warp factory](/factories/), use [factory endpoints](/factories/factory-api/) to discover it and dispatch by UID instead of calling `POST /agent/run` with a foreman's `agent_identity_uid`. The follow-up, cancellation, and status endpoints still apply after a factory run is dispatched. -### SDK overview +## SDKs -Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs that wrap the {VARS.API_SDK_NAME} with: +Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs that wrap the {VARS.WARP_PLATFORM_API} with: * **Typed requests and responses** (editor autocomplete, fewer schema mistakes) * **Built-in retries and timeouts** (with per-request overrides) -* [**Consistent error types**](/reference/api-and-sdk/troubleshooting/errors/) that map to API status codes +* [**Consistent error types**](/factories/api-and-sdk/troubleshooting/errors/) that map to API status codes * **Helpers for raw responses** when you need headers/status or custom parsing If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. -<VideoEmbed url="https://www.youtube.com/watch?v=0cf7383MZSk" title={`${VARS.API_SDK_NAME} reference overview video`} /> +<VideoEmbed url="https://www.youtube.com/watch?v=0cf7383MZSk" title={`${VARS.WARP_PLATFORM_API} reference overview video`} /> **SDK vs raw REST** @@ -57,9 +58,7 @@ For the full SDK surface area and latest usage, refer to the GitHub repos: [**Py --- -## API reference - -### REST API base URL +## API base URL All endpoints are served over HTTPS: @@ -67,9 +66,7 @@ All endpoints are served over HTTPS: https://app.warp.dev/api/v1 ``` -### Core concepts - -#### **Agent runs** +### Agent runs An agent run represents a single execution of a cloud agent, created with a prompt and optional configuration. Each run has: @@ -81,9 +78,9 @@ An agent run represents a single execution of a cloud agent, created with a prom * Optional session information (`session_id`, `session_link`) * Optional resolved configuration (`agent_config`) -See the [**Agents API Reference**](/api) for details on how runs are created and listed. +See the [**Warp Platform API reference**](/api) for details on how runs are created and listed. -#### **Agent configuration** +### Agent configuration You can influence how an agent runs using AmbientAgentConfig, including: @@ -91,6 +88,7 @@ You can influence how an agent runs using AmbientAgentConfig, including: * `model_id` for LLM selection * `base_prompt` to shape behavior * `environment_id` to choose a `CloudEnvironment` +* `worker_host` to run a standalone cloud agent on a [self-hosted worker](/factories/self-hosting/) * `skill_spec` to use a [skill](/agents/capabilities/skills/) as the base prompt (format: `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md`) * `mcp_servers` to enable specific tools via MCP @@ -98,9 +96,24 @@ See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**Type --- -### Key endpoints +## Route a run to a self-hosted worker + +Set `worker_host` in the request configuration to select a connected self-hosted worker. Omit it, or set it to `warp`, to use Warp-hosted workers. + +```json +{ + "prompt": "Run the dependency audit", + "config": { + "worker_host": "WORKER_HOST" + } +} +``` + +Replace `WORKER_HOST` with the ID of a connected worker. For factory work, set `workerHost` in the [factory definition](/factories/factory-as-code/#agentdefaultsworkerhost) instead. + +## Key endpoints -**The Agents API exposes these primary endpoints:** +Agent & run endpoints include: * `POST /agent/run` @@ -118,11 +131,11 @@ See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**Type Cancel a run that is currently queued or in progress. Returns the ID of the cancelled run. -All endpoint semantics, query parameters, and [error codes](/reference/api-and-sdk/troubleshooting/errors/) are documented on the [Agents API Reference](/api). +All endpoint semantics, query parameters, and [error codes](/factories/api-and-sdk/troubleshooting/errors/) are documented in the [Warp Platform API reference](/api). --- -#### Models reference +## Models The API shares a set of reusable models across endpoints. Detailed JSON schemas, types, and enums are available in the SDK repos ([Python](https://github.com/warpdotdev/oz-sdk-python), [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript)). Key models include: diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/factories/api-and-sdk/quickstart.mdx similarity index 74% rename from src/content/docs/reference/api-and-sdk/quickstart.mdx rename to src/content/docs/factories/api-and-sdk/quickstart.mdx index 00107985e..89533d3fc 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/factories/api-and-sdk/quickstart.mdx @@ -1,7 +1,8 @@ --- -title: "API & SDK quickstart" +topic: factories +title: "Warp Platform API quickstart" description: >- - Create and monitor your first cloud agent run via the {{API_SDK_NAME}} in ~5 + Create and monitor your first cloud agent run via the {{WARP_PLATFORM_API}} in ~5 minutes. sidebar: label: "Quickstart" @@ -9,16 +10,18 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -The {VARS.API_SDK_NAME} lets you run and manage cloud agents from anywhere — CI/CD pipelines, backend services, scripts, or custom tooling — without the Warp desktop app. This quickstart walks you through creating your first run and checking its status. +The {VARS.WARP_PLATFORM_API} lets you run and manage cloud agents from CI/CD pipelines, backend services, scripts, or custom tooling without the Warp desktop app. This quickstart walks you through creating your first run and checking its status. + +To dispatch work through a factory's named agents and workflow, use [factory endpoints](/factories/factory-api/) after this quickstart. The run-management steps below also apply to the factory run those endpoints create. Watch this short demo of how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team: -<VideoEmbed url="https://youtu.be/N6qMe641K34" title={`${VARS.API_SDK_NAME} quickstart video`} /> +<VideoEmbed url="https://youtu.be/N6qMe641K34" title={`${VARS.WARP_PLATFORM_API} quickstart video`} /> --- ## Prerequisites -* **A Warp API key** - Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](/platform/agents/). See [API Keys](/reference/cli/api-keys/) for the full flow. +* **A Warp API key** - Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](/platform/agents/). See [API Keys](/agents/cli/oz-cli/api-keys/) for the full flow. * **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/platform/quickstart/) first. --- @@ -71,9 +74,9 @@ The `state` has the following possible values: * `QUEUED` - The run is waiting to start. * `INPROGRESS` - The agent is actively running. * `SUCCEEDED` - The run completed successfully. -* `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret the error code. +* `FAILED` - The run encountered an error. Check the `status_message` field in the response for details, then use the [API error reference](/factories/api-and-sdk/troubleshooting/errors/) to interpret the error code. -These are the most common states. See the [full API reference](/reference/api-and-sdk/) for all possible values. +These are the most common states. See the [Agent & run endpoints](/factories/api-and-sdk/) and [Warp Platform API reference](/api) for all possible values. To list all recent runs: @@ -92,7 +95,7 @@ You can also view and manage all runs in the <a href={`${VARS.WEB_APP_URL}/runs` ## Next steps -* **Read the full API reference** - [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) documents all endpoint parameters, query filters, and response schemas. +* **Read the endpoint guide** - [Agent & run endpoints](/factories/api-and-sdk/) documents the configuration and run lifecycle, while the [Warp Platform API reference](/api) lists all parameters, query filters, and response schemas. * **Explore the SDKs** - [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) include typed request/response models, retries, and error handling. -* **See a real-world example** - [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors. +* **See a real-world example** - [Demo: Sentry monitoring with SDK](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors. * **Schedule and automate** - See [Scheduled Agents Quickstart](/platform/triggers/scheduled-agents-quickstart/) to run agents on a cron, or [Integrations Quickstart](/platform/integrations/quickstart/) to trigger agents from Slack or Linear. diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx similarity index 88% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx index 41b8898b0..52a7740fa 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/agent-process-failed.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: agent_process_failed description: >- The agent process exited unexpectedly during task execution. Retry the task @@ -8,7 +9,7 @@ description: >- The `agent_process_failed` error occurs when the agent process exits unexpectedly after environment setup has completed, before the task reaches a normal terminal state. :::note -This is classified as a **platform error** (task state → ERROR) rather than a user error. It differs from [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/), which covers failures that happen while initializing the environment (cloning the repo, running setup commands, starting MCP servers). `agent_process_failed` covers failures that happen during the agent's active execution phase. +This is classified as a **platform error** (task state → ERROR) rather than a user error. It differs from [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/), which covers failures that happen while initializing the environment (cloning the repo, running setup commands, starting MCP servers). `agent_process_failed` covers failures that happen during the agent's active execution phase. ::: --- @@ -35,7 +36,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/", + "type": "/factories/api-and-sdk/troubleshooting/errors/agent-process-failed/", "title": "The agent process exited unexpectedly.", "status": 500, "instance": "/api/v1/agent/tasks", @@ -58,5 +59,5 @@ This error is returned when: ## Related * [Cloud Agents Overview](/platform/) — How cloud agent tasks work -* [environment_setup_failed](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Errors during environment setup -* [internal_error](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Catch-all for unexpected server-side errors +* [environment_setup_failed](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Errors during environment setup +* [internal_error](/factories/api-and-sdk/troubleshooting/errors/internal-error/) — Catch-all for unexpected server-side errors diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/authentication-required.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx similarity index 90% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/authentication-required.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx index 37e3adcd9..af1d74d29 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/authentication-required.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/authentication-required.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: authentication_required description: >- The API key in the request is invalid, expired, or missing. Generate a new @@ -36,7 +37,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/authentication-required/", + "type": "/factories/api-and-sdk/troubleshooting/errors/authentication-required/", "title": "Your API key is invalid or has expired. Please generate a new key and try again.", "status": 401, "instance": "/api/v1/agent/tasks", @@ -57,5 +58,5 @@ This error is returned when: ## Related -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API authentication +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API authentication * [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) — API key management diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx similarity index 94% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx index f483a50b5..cecf4fc26 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/budget-exceeded.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: budget_exceeded description: >- Your team's configured spending budget limit has been reached. Increase the @@ -32,7 +33,7 @@ The `title` field in the response will describe the specific budget constraint. ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/", + "type": "/factories/api-and-sdk/troubleshooting/errors/budget-exceeded/", "title": "Monthly spending budget of $50 has been reached.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/conflict.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx similarity index 88% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/conflict.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx index 489a0620a..344c0f5d1 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/conflict.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/conflict.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: "Error: conflict (409)" sidebar: label: "conflict" @@ -34,7 +35,7 @@ The operation can typically succeed once the resource transitions to the expecte ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/conflict/", + "type": "/factories/api-and-sdk/troubleshooting/errors/conflict/", "title": "Pending agent runs cannot be cancelled, retry after a moment.", "status": 409, "instance": "/api/v1/agent/tasks/abc123/cancel", @@ -57,4 +58,4 @@ For task cancellation specifically, wait until the task moves from **pending** t ## Related * [Managing Cloud Agents](/platform/managing-cloud-agents/) — Viewing and managing agent tasks -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API reference for managing agent tasks +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API reference for managing agent tasks diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx similarity index 95% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx index 3b6480de1..c27645de9 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/content-policy-violation.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: content_policy_violation description: >- The task prompt or environment setup commands were flagged by the platform's @@ -35,7 +36,7 @@ For security reasons, the error message is intentionally generic and does not de ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/content-policy-violation/", + "type": "/factories/api-and-sdk/troubleshooting/errors/content-policy-violation/", "title": "Unable to start cloud agent. Please try again or contact support if the issue persists.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx similarity index 91% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx index b356fc21e..598c0ea38 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: environment_setup_failed description: >- The cloud agent's environment failed to initialize. Check repo URLs, setup @@ -38,7 +39,7 @@ The `title` field in the response will describe the specific setup failure. ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/", + "type": "/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/", "title": "Failed to clone repository: branch 'main' not found in acme/backend", "status": 500, "instance": "/api/v1/agent/tasks", @@ -54,7 +55,7 @@ The `title` field in the response will describe the specific setup failure. 1. **Check repository configuration** — Verify the repository URL and branch name in your [environment settings](/platform/environments/). Ensure the repository exists and is accessible. 2. **Check setup commands** — Run the setup commands locally to confirm they work. Look for missing dependencies, incorrect paths, or syntax errors. 3. **Check working directory** — Ensure the working directory path exists relative to the cloned repository root. -4. **Check MCP server configuration** — Verify MCP server startup commands and that any required dependencies or credentials are available. See [MCP Servers for Agents](/reference/cli/mcp-servers/). +4. **Check MCP server configuration** — Verify MCP server startup commands and that any required dependencies or credentials are available. See [MCP Servers for Agents](/agents/cli/oz-cli/mcp-servers/). 5. **Check secrets** — If setup commands reference environment variables from [secrets](/platform/secrets/), verify the secrets are configured and in scope. --- @@ -63,4 +64,4 @@ The `title` field in the response will describe the specific setup failure. * [Environments](/platform/environments/) — Configuring cloud agent environments * [Secrets](/platform/secrets/) — Managing credentials for agent environments -* [MCP Servers for Agents](/reference/cli/mcp-servers/) — Configuring MCP servers +* [MCP Servers for Agents](/agents/cli/oz-cli/mcp-servers/) — Configuring MCP servers diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx similarity index 94% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx index 82872f987..ec71c7fca 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: external_authentication_required description: >- The task requires access to an external service (GitHub, Slack, Linear, @@ -43,7 +44,7 @@ This error includes extra fields beyond the standard response format: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", + "type": "/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/", "title": "User is not connected to GitHub", "status": 401, "instance": "/api/v1/agent/tasks", @@ -58,7 +59,7 @@ This error includes extra fields beyond the standard response format: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", + "type": "/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/", "title": "User does not have access to the following repositories in the environment: acme/backend", "status": 401, "detail": "inaccessible repos: acme/backend", @@ -75,7 +76,7 @@ This error includes extra fields beyond the standard response format: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", + "type": "/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/", "title": "Unable to locate your Warp account", "status": 401, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/feature-not-available.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx similarity index 95% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/feature-not-available.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx index 1d255c180..fb9013b2d 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/feature-not-available.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/feature-not-available.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: feature_not_available description: >- The requested feature is not included in your current plan. Upgrade your @@ -32,7 +33,7 @@ The `title` field in the response will describe the specific feature that is una ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/feature-not-available/", + "type": "/factories/api-and-sdk/troubleshooting/errors/feature-not-available/", "title": "Slack integration requires a Build plan or higher.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx similarity index 69% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx index af4046131..7dfbfd57f 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/index.mdx @@ -1,13 +1,14 @@ --- -title: Errors Overview +topic: factories +title: API errors description: >- - Reference for all error codes returned by the {{API_SDK_NAME}}. Each error + Reference for all error codes returned by the {{WARP_PLATFORM_API}}. Each error includes an HTTP status, machine-readable code, and actionable resolution steps. --- import { VARS } from '@data/vars'; -When the {VARS.API_SDK_NAME} encounters an error, it returns a structured JSON response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807). Every error response includes a machine-readable error code, a human-readable message, and metadata to help you diagnose and resolve the issue. +When the {VARS.WARP_PLATFORM_API} encounters an error, it returns a structured JSON response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807). Every error response includes a machine-readable error code, HTTP status, human-readable message, and resolution details. --- @@ -17,7 +18,7 @@ All error responses share this structure: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/invalid-request/", + "type": "/factories/api-and-sdk/troubleshooting/errors/invalid-request/", "title": "The request contains invalid or missing parameters.", "status": 400, "detail": "schedule_id is required", @@ -53,29 +54,29 @@ Errors are split into two categories based on what caused the failure: These indicate something the caller needs to fix. When a cloud agent task encounters a user error, the task transitions to the **FAILED** state. -* [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) — Team has no remaining add-on credits -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) — Feature not included in your current plan -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) — External service authorization needed -* [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/) — Insufficient permissions for the operation -* [`invalid_request`](/reference/api-and-sdk/troubleshooting/errors/invalid-request/) — Malformed request or invalid parameters -* [`resource_not_found`](/reference/api-and-sdk/troubleshooting/errors/resource-not-found/) — Referenced resource does not exist -* [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/) — Spending budget limit reached -* [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/) — Integration is disabled -* [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) — Integration setup is incomplete -* [`operation_not_supported`](/reference/api-and-sdk/troubleshooting/errors/operation-not-supported/) — Operation not supported for this resource or state -* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Cloud agent environment failed to initialize -* [`content_policy_violation`](/reference/api-and-sdk/troubleshooting/errors/content-policy-violation/) — Task flagged by content policy checks -* [`conflict`](/reference/api-and-sdk/troubleshooting/errors/conflict/) — Request conflicts with the current resource state (retryable) +* [`insufficient_credits`](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/) — Team has no remaining add-on credits +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) — Feature not included in your current plan +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) — External service authorization needed +* [`not_authorized`](/factories/api-and-sdk/troubleshooting/errors/not-authorized/) — Insufficient permissions for the operation +* [`invalid_request`](/factories/api-and-sdk/troubleshooting/errors/invalid-request/) — Malformed request or invalid parameters +* [`resource_not_found`](/factories/api-and-sdk/troubleshooting/errors/resource-not-found/) — Referenced resource does not exist +* [`budget_exceeded`](/factories/api-and-sdk/troubleshooting/errors/budget-exceeded/) — Spending budget limit reached +* [`integration_disabled`](/factories/api-and-sdk/troubleshooting/errors/integration-disabled/) — Integration is disabled +* [`integration_not_configured`](/factories/api-and-sdk/troubleshooting/errors/integration-not-configured/) — Integration setup is incomplete +* [`operation_not_supported`](/factories/api-and-sdk/troubleshooting/errors/operation-not-supported/) — Operation not supported for this resource or state +* [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Cloud agent environment failed to initialize +* [`content_policy_violation`](/factories/api-and-sdk/troubleshooting/errors/content-policy-violation/) — Task flagged by content policy checks +* [`conflict`](/factories/api-and-sdk/troubleshooting/errors/conflict/) — Request conflicts with the current resource state (retryable) ### Platform errors These indicate a Warp-side issue. When a cloud agent task encounters a platform error, the task transitions to the **ERROR** state. Retryable errors are automatically retried before the task is marked as failed. -* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) — Invalid or expired API key -* [`resource_unavailable`](/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/) — Transient infrastructure issue (retryable) -* [`internal_error`](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Unexpected server-side error (retryable) -* [`infrastructure_timeout`](/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/) — Task terminated after exceeding the maximum allowed runtime -* [`agent_process_failed`](/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/) — Agent process exited unexpectedly during task execution +* [`authentication_required`](/factories/api-and-sdk/troubleshooting/errors/authentication-required/) — Invalid or expired API key +* [`resource_unavailable`](/factories/api-and-sdk/troubleshooting/errors/resource-unavailable/) — Transient infrastructure issue (retryable) +* [`internal_error`](/factories/api-and-sdk/troubleshooting/errors/internal-error/) — Unexpected server-side error (retryable) +* [`infrastructure_timeout`](/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout/) — Task terminated after exceeding the maximum allowed runtime +* [`agent_process_failed`](/factories/api-and-sdk/troubleshooting/errors/agent-process-failed/) — Agent process exited unexpectedly during task execution --- @@ -87,6 +88,6 @@ When an error response includes a `trace_id`, you can include it when [contactin ## Related -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API reference for creating and managing agent tasks +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API reference for creating and managing agent tasks * [Cloud Agents Overview](/platform/) — How cloud agents work * [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Plan requirements and billing details diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx similarity index 93% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx index fff2a0222..7e213ad0c 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: infrastructure_timeout description: >- The task was forcibly terminated because it remained active past the maximum @@ -35,7 +36,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", + "type": "/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", "title": "The task exceeded the maximum allowed runtime and was terminated.", "status": 500, "instance": "/api/v1/agent/tasks", @@ -58,5 +59,5 @@ This error is returned when: ## Related * [Cloud Agents Overview](/platform/) — How cloud agent tasks work -* [internal_error](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Other platform-level errors +* [internal_error](/factories/api-and-sdk/troubleshooting/errors/internal-error/) — Other platform-level errors * [Cloud Agents FAQs](/platform/faqs/) — Common questions about cloud agents diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx similarity index 97% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx index 1a0f262fd..c8000af6d 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/insufficient-credits.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: insufficient_credits description: >- The principal billed for the run has no remaining credits. Top up the @@ -40,7 +41,7 @@ For the full waterfall, see [How are cloud agent runs on team plans billed when ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/", + "type": "/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/", "title": "The principal billed for this run has no remaining credits. Purchase add-on credits or raise the team-wide spend cap to continue.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-disabled.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx similarity index 94% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-disabled.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx index 91cdccec5..9f1a8a3a4 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-disabled.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-disabled.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: integration_disabled description: >- The integration (Slack, Linear, etc.) is currently disabled in the @@ -31,7 +32,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/integration-disabled/", + "type": "/factories/api-and-sdk/troubleshooting/errors/integration-disabled/", "title": "This integration is disabled. Please enable it in Oz.", "status": 403, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx similarity index 96% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx index 24b249f9f..e5da179e4 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: integration_not_configured description: >- The integration's setup is incomplete. Visit the setup URL to finish @@ -41,7 +42,7 @@ This error includes extra fields beyond the standard response format: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/", + "type": "/factories/api-and-sdk/troubleshooting/errors/integration-not-configured/", "title": "Slack integration is not configured", "status": 400, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/internal-error.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx similarity index 95% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/internal-error.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx index 2dd683a7d..02a121076 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/internal-error.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/internal-error.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: internal_error description: >- An unexpected server-side error occurred. The platform will automatically @@ -31,7 +32,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/internal-error/", + "type": "/factories/api-and-sdk/troubleshooting/errors/internal-error/", "title": "An unexpected error occurred. Please try again later. If the issue persists, contact support.", "status": 500, "instance": "/api/v1/agent/tasks", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx similarity index 87% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx index dc807a2fd..67bd7db3f 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/invalid-request.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: invalid_request description: >- The request body is malformed, missing required fields, or contains invalid @@ -36,7 +37,7 @@ The `detail` field in the response will describe the specific validation issue. ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/invalid-request/", + "type": "/factories/api-and-sdk/troubleshooting/errors/invalid-request/", "title": "The request contains invalid or missing parameters.", "status": 400, "detail": "schedule_id is required", @@ -51,11 +52,11 @@ The `detail` field in the response will describe the specific validation issue. ## How to resolve 1. Check the `detail` field for the specific validation issue. -2. Correct the request parameters according to the [API documentation](/reference/api-and-sdk/). +2. Correct the request parameters according to the [API documentation](/factories/api-and-sdk/). 3. Retry the request. --- ## Related -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API request format and parameters +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API request format and parameters diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/not-authorized.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx similarity index 89% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/not-authorized.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx index 964bbfc17..fd42806e3 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/not-authorized.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/not-authorized.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: not_authorized description: >- The authenticated user or API key does not have permission to perform the @@ -33,7 +34,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/not-authorized/", + "type": "/factories/api-and-sdk/troubleshooting/errors/not-authorized/", "title": "You do not have permission for this operation.", "status": 403, "detail": "user is not a member of the team", @@ -56,4 +57,4 @@ This error is returned when: ## Related * [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Permission model and identity -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API authentication and authorization +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API authentication and authorization diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx similarity index 86% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx index eaabaa540..d2ee357e0 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: operation_not_supported description: >- The requested operation is not supported for this resource or its current @@ -32,7 +33,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/operation-not-supported/", + "type": "/factories/api-and-sdk/troubleshooting/errors/operation-not-supported/", "title": "Self-hosted agent runs cannot be cancelled with the API.", "status": 422, "instance": "/api/v1/agent/tasks/abc123/cancel", @@ -56,5 +57,5 @@ This error is returned when: ## Related * [Cloud Agents Overview](/platform/) — How cloud agent tasks work -* [Self-hosting](/platform/self-hosting/) — Self-hosted agent configuration -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API reference for managing agent tasks +* [Self-hosting](/factories/self-hosting/) — Self-hosted agent configuration +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — API reference for managing agent tasks diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-not-found.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx similarity index 95% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-not-found.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx index e3f7f36f3..a75992bd0 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-not-found.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-not-found.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: resource_not_found description: >- The requested resource (task, environment, schedule, agent, etc.) does not @@ -34,7 +35,7 @@ The `detail` field in the response will describe which resource was not found. ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/resource-not-found/", + "type": "/factories/api-and-sdk/troubleshooting/errors/resource-not-found/", "title": "The requested resource was not found.", "status": 404, "detail": "environment abc123 not found", diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx similarity index 89% rename from src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx rename to src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx index 69f5b63c3..d0feae9af 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx +++ b/src/content/docs/factories/api-and-sdk/troubleshooting/errors/resource-unavailable.mdx @@ -1,4 +1,5 @@ --- +topic: factories title: resource_unavailable description: >- A transient infrastructure issue prevented the task from running. The @@ -32,7 +33,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/", + "type": "/factories/api-and-sdk/troubleshooting/errors/resource-unavailable/", "title": "Agent capacity is temporarily full. Your task will be retried automatically, or you can try again later.", "status": 429, "instance": "/api/v1/agent/tasks", @@ -46,7 +47,7 @@ This error is returned when: ```json { - "type": "/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/", + "type": "/factories/api-and-sdk/troubleshooting/errors/resource-unavailable/", "title": "Failed to create a sandbox instance for your agent. This is typically a transient issue — your task will be retried automatically.", "status": 500, "instance": "/api/v1/agent/tasks", @@ -72,4 +73,4 @@ If the error persists after retries: ## Related * [Cloud Agents Overview](/platform/) — How cloud agent execution works -* [Deployment Patterns](/platform/deployment-patterns/) — Execution models and infrastructure +* [Deployment Patterns](/factories/deployment-patterns/) — Execution models and infrastructure diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index 78cea5336..7b9dca2fa 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -25,7 +25,7 @@ Once a source is connected, here's the concrete action that hands it work — ea | [Linear](/factories/integrations/linear/) | Planned issues | [Assigning the issue to the factory, or mentioning the Warp app in a comment](/factories/integrations/linear/#route-agent-sessions) | The Linear issue and its agent session | | [Jira](/factories/integrations/jira/) | Work items assigned to Warp | [Assigning or mentioning **Warp** on a work item](/factories/integrations/jira/#connect-jira-and-add-an-automation) | The Jira agent session | | [Custom webhooks](/factories/webhooks/) | Any system that can POST JSON: CI, monitoring, alerting, and internal tools | [Posting JSON to the webhook's URL from the external system](/factories/webhooks/#configure-the-sender) | The factory work item | -| [Factory API](/factories/factory-api/) | Custom integrations and scripts that dispatch by factory UID | [Calling `POST /factory/{uid}/runs` with a prompt](/factories/factory-api/#dispatch-a-run-to-a-factory) | The factory work item | +| [factory endpoints](/factories/factory-api/) | Custom integrations and scripts that dispatch by factory UID | [Calling `POST /factory/{uid}/runs` with a prompt](/factories/factory-api/#dispatch-a-run-to-a-factory) | The factory work item | | [Factory MCP](/factories/factory-mcp/) | Exchanging work with a local coding agent, in both directions | [Calling `send_task` from a connected coding agent](/factories/factory-mcp/#send-new-work-to-a-factory) | The factory work item | | Direct runs and schedules | One-off or recurring work | [Clicking **New** on the factory's Runs page, or adding a schedule trigger](#direct-runs-and-schedules) | The factory work item | @@ -69,9 +69,9 @@ These defaults are starting points. Review each automation's filters, agent, and A [custom webhook](/factories/webhooks/) gives the factory an authenticated URL that any system can POST JSON to, and an automation decides which deliveries start work by filtering on the payload. Use it for tools Warp doesn't connect to directly, such as your CI system, PagerDuty, Sentry, or Stripe, without writing any code on your side. -## Factory API +## factory endpoints -The [factory API](/factories/factory-api/) lets your own code discover a factory and dispatch a task to it by UID, without knowing which agent handles the work. Use it to build a custom integration for a tool Warp doesn't connect to directly - see [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) for a worked example. +[factory endpoints](/factories/factory-api/) let your own code discover a factory and dispatch a task to it by UID, without knowing which agent handles the work. Use them to build a custom integration for a tool Warp doesn't connect to directly - see [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) for a worked example. ## Factory MCP diff --git a/src/content/docs/factories/deployment-patterns.mdx b/src/content/docs/factories/deployment-patterns.mdx new file mode 100644 index 000000000..03a47882f --- /dev/null +++ b/src/content/docs/factories/deployment-patterns.mdx @@ -0,0 +1,107 @@ +--- +title: Deployment patterns for Warp Factories +description: >- + Choose Warp-hosted or managed self-hosted execution for Warp Factories based + on your network, compliance, and operational requirements. +sidebar: + label: "Deployment patterns" +--- +import { VARS } from '@data/vars'; + +Choose an execution model for your factory based on where its code must run and who operates the compute. Warp-hosted execution is the default. Managed self-hosting keeps checkout and command execution in your network while Warp coordinates the work. + +![Deployment models diagram comparing Warp-hosted, managed self-hosted, and unmanaged self-hosted patterns by what runs on Warp versus customer infrastructure](../../../assets/agent-platform/deployment-models.png) + +## Choose an execution model + +| If your factory needs to... | Choose | +| --- | --- | +| Run public repositories and services without operating workers | [Warp-hosted execution](#warp-hosted-execution) | +| Reach private repositories or services behind your network boundary | [Managed self-hosting](#managed-self-hosting) | +| Run standalone agents from CI or developer infrastructure, without a factory | [Unmanaged execution](/platform/unmanaged-execution/) | + +Both factory options use the same [factory definition](/factories/factory-as-code/), [runners](/factories/runners/), and [factory dashboard](/factories/factory-dashboard/). The execution host changes the location of checkout, command execution, and the sandbox filesystem. + + +## Warp-hosted execution + +Use this when your factory can reach its repositories and services over the public internet. The {VARS.WARP_AUTOMATION_PLATFORM} runs the work on Warp-managed infrastructure while your factory definition selects the agents, runner, workspace, and credentials. + +![Warp-hosted execution architecture showing customer infrastructure, triggers and integrations, isolated tenant sandboxes, the Warp control plane, and LLM providers](../../../assets/agent-platform/cloud-agents-infra.png) + +See the [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-lifecycle) reference for a description of each component in the architecture. + +### What it looks like + +* **Trigger**: first-party integrations, cron schedules, API/SDK calls, or on-demand commands +* **Orchestration**: {VARS.WARP_AUTOMATION_PLATFORM} orchestrator +* **Execution**: {VARS.WARP_AUTOMATION_PLATFORM}-hosted environments (Docker-based) +* **Visibility**: {VARS.DASHBOARD} + session sharing + APIs/SDKs + +### Why teams choose it + +* You want the simplest path to reproducible, scalable cloud execution. +* You want to run many tasks in parallel without building your own sandboxing and scaling layer. +* You want a consistent "production" setup with standardized environments and centralized configuration. + +### Common ways to trigger + +* **First-party integrations (Slack, Linear, etc.)** that create tasks automatically from external events. +* **[Scheduled agents](/platform/triggers/scheduled-agents/)** for recurring work (cron-like automation). +* **Custom triggers** from your own systems using Warp's API/SDK. +* **On-demand cloud jobs** using CLI commands like `oz agent run-cloud`. + +### Example recipe: daily dead-code cleanup + +1. Define a Warp [Environment](/platform/environments/) with the repo + toolchain. +2. Create a [schedule](/platform/triggers/scheduled-agents/) with a fixed prompt for cleanup. +3. The {VARS.WARP_AUTOMATION_PLATFORM} runs the agent on the cadence. +4. Your team monitors runs in the [{VARS.WEB_APP}](/platform/oz-web-app/) and [viewing cloud agent runs](/platform/viewing-cloud-agent-runs/), reviews artifacts (PRs, plans), and intervenes when needed. + +### Example recipe: crash triage via Sentry webhook + +1. Define a Warp Environment with the target repo. +2. Register a Sentry webhook to your handler (server, cloud function, Zapier/n8n). +3. Handler extracts crash details, constructs a prompt, and calls the {VARS.WARP_AUTOMATION_PLATFORM} orchestrator API/SDK to start a task. +4. Warp spins up the run in the environment and you monitor progress via UI/API. + +### Example recipe: fan-out parallel work (sharding) + +When a task is naturally divisible, use [multi-agent orchestration](/platform/orchestration/) to spawn one child agent per shard from a single parent run. The parent owns coordination and result aggregation; the children execute in parallel, each with their own repo subset, prompt, and (optionally) model. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) for slash command, CLI, web app, and API examples. + +### Example recipe: same task across multiple models + +* Launch N runs with the same prompt, but different profiles that map to different models. +* Compare results and choose the best output (or merge). + +--- + +## Managed self-hosting + +Use this when a factory must run checkout and execution on your infrastructure while the {VARS.WARP_AUTOMATION_PLATFORM} coordinates the work and records its results. Repositories are cloned and stored only on your infrastructure. Orchestration metadata and session transcripts route through Warp's backend; cloud conversations require Warp to store conversation data according to Warp's retention terms. LLM inference requests and responses route through Warp to contracted model providers under [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), except for provider-specific models that are not covered by ZDR and follow the provider's retention requirements. + +Think of managed self-hosting as **customer-hosted execution with Warp-hosted orchestration**, not as a fully offline agent stack. Code repositories, build artifacts, runtime secrets, and execution workspaces stay on your infrastructure. Code context can still appear in session transcripts and LLM prompts as the agent works. + +:::note +**Enterprise feature**: Self-hosted execution is available exclusively to teams on an Enterprise plan. +::: + +Self-hosting has two architectures that differ on **who orchestrates agent runs** (both keep code and execution on your infrastructure): + +* **[Managed](/factories/self-hosting/#managed-architecture)** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates. You run the `oz-agent-worker` daemon; the {VARS.WARP_AUTOMATION_PLATFORM} routes runs to it from Slack, Linear, schedules, the API, or `oz agent run-cloud`. Tasks execute in Docker containers, Kubernetes Jobs, or directly on the host. +* **[Unmanaged](/platform/unmanaged-execution/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment for standalone-agent work. To route factory work to a worker instead, use the managed architecture above. + +Why teams choose self-hosted execution: + +* Code and execution must stay within your network boundary for compliance or security requirements. +* Agents need to access services behind a VPN or self-hosted SCMs like GitLab or Bitbucket. Warp-hosted agents can also access GitLab and Bitbucket over the public internet — see the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides. +* Your environments (multi-service stacks, heavy resource requirements) don't fit in a single Docker container. + +For factory worker setup and a quickstart, start with [Managed self-hosting](/factories/self-hosting/). For security and network boundaries that apply to both managed and unmanaged execution, see [Execution security](/platform/execution-security/). + +## Related pages + +* [Infrastructure and security](/factories/infrastructure-and-security/) - Choose execution, inference, storage, and credential boundaries for a factory. +* [Warp-hosted execution](/factories/warp-hosting/) - Review hosted execution capacity, networking, and supported environments. +* [Managed self-hosting](/factories/self-hosting/) - Install and operate a factory worker on your infrastructure. +* [Unmanaged execution](/platform/unmanaged-execution/) - Run standalone agents outside a factory. diff --git a/src/content/docs/factories/developer-tools.mdx b/src/content/docs/factories/developer-tools.mdx new file mode 100644 index 000000000..d6dfa9ecf --- /dev/null +++ b/src/content/docs/factories/developer-tools.mdx @@ -0,0 +1,32 @@ +--- +title: "{{WARP_PLATFORM_API}} & SDKs" +description: >- + Use the {{WARP_PLATFORM_API}}, SDKs, Factory MCP, and webhooks to integrate + factories and cloud agent runs with your tools and services. +sidebar: + label: "Overview" +--- +import { VARS } from '@data/vars'; + +The {VARS.WARP_PLATFORM_API} serves both factories and standalone cloud agent runs. The factory endpoints send work to a factory; agent and run endpoints start and manage standalone runs. Both endpoint families use the same API key, API reference, SDKs, and error model. + +## Choose an API surface + +* **[Factory endpoints](/factories/factory-api/)** - Find a factory and send work to it by UID from your application or service. +* **[Agent & run endpoints](/factories/api-and-sdk/)** - Start, monitor, continue, and cancel cloud agent runs from scripts, CI, and backend services. +* **[Warp Platform API reference](/api)** - Look up the full HTTP schema, parameters, and responses. +* **[Python SDK](https://github.com/warpdotdev/oz-sdk-python)** - Make typed requests from Python. The current package retains its `oz-sdk-python` name. +* **[TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript)** - Make typed requests from TypeScript. The current package retains its `oz-sdk-typescript` name. +* **[API errors](/factories/api-and-sdk/troubleshooting/errors/)** - Resolve error responses by HTTP status and machine-readable code. +* **[Factory MCP](/factories/factory-mcp/)** - Exchange work between a factory and a connected coding agent or MCP client. +* **[Webhooks](/factories/webhooks/)** - Receive events from systems that can send JSON and route matching deliveries into factory automations. + +## Get started + +Start with the [API & SDK quickstart](/factories/api-and-sdk/quickstart/) to create and inspect a run. For a production event source, use the [Sentry monitoring example](/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/) to connect a webhook handler. + +## Related pages + +* [Connect your factory](/factories/connect-your-factory/) - Choose an integration or direct intake path. +* [Factory automations](/factories/automations/) - Route events and schedules to factory agents. +* [Factory dashboard](/factories/factory-dashboard/) - Inspect work items, runs, and factory settings. diff --git a/src/content/docs/factories/factory-api.mdx b/src/content/docs/factories/factory-api.mdx index 141f3b200..a713b479c 100644 --- a/src/content/docs/factories/factory-api.mdx +++ b/src/content/docs/factories/factory-api.mdx @@ -1,14 +1,14 @@ --- -title: Use the factory API +title: Factory endpoints description: >- - Discover factories and dispatch tasks by UID with the public factory API, + Discover factories and dispatch tasks by UID with factory endpoints, without learning the foreman agent's internals. sidebar: - label: "Factory API" + label: "Factory endpoints" --- import { VARS } from '@data/vars'; -Use the factory API to find a factory and start work from a custom integration without managing agent details. Build it into a chat bot, script, or service for any tool Warp doesn't connect to directly. +The factory endpoints are part of the {VARS.WARP_PLATFORM_API}. Use them to find a factory and start work from a custom integration without managing agent details. Build them into a chat bot, script, or service for any tool Warp doesn't connect to directly. :::note Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. @@ -20,21 +20,21 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [ * `GET /factory/{uid}` - get one factory by UID. * `POST /factory/{uid}/runs` - dispatch a run to the factory's foreman agent. Pass a `prompt`; the server resolves the foreman for you. -A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [Agent API](/reference/api-and-sdk/) you'd use for any run. +A dispatched run is an ordinary [cloud agent run](/platform/): retrieve it, send it follow-ups, or cancel it through the same [agent and run endpoints](/factories/api-and-sdk/) used for any run. -## When to use the factory API vs the Agent API +## Choosing an endpoint family -Use the factory API to find or start work on a factory. Use the Agent API for everything else - a standalone cloud agent, run management, or orchestration. +Use factory endpoints to find or start work on a factory. Use Agent & run endpoints for everything else: a standalone cloud agent, run management, or orchestration. | Task | Recommended API | | --- | --- | -| Find a factory by name before dispatching to it | factory API - `GET /factory?search=` | -| Start a new task on a factory | factory API - `POST /factory/{uid}/runs` | -| Continue, monitor, or cancel a run (factory or standalone) | Agent API - `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` | -| Run a standalone cloud agent with no factory involved | Agent API - `POST /agent/run` | -| Build a multi-agent orchestration | Agent API - see [multi-agent orchestration](/platform/orchestration/) | +| Find a factory by name before dispatching to it | factory endpoints - `GET /factory?search=` | +| Start a new task on a factory | factory endpoints - `POST /factory/{uid}/runs` | +| Continue, monitor, or cancel a run (factory or standalone) | Agent & run endpoints - `GET /agent/runs/{runId}`, `POST /agent/runs/{runId}/followups`, `POST /agent/runs/{runId}/cancel` | +| Run a standalone cloud agent with no factory involved | Agent & run endpoints - `POST /agent/run` | +| Build a multi-agent orchestration | Agent & run endpoints - see [multi-agent orchestration](/platform/orchestration/) | -The Agent API isn't deprecated: every factory run is still an ordinary run, so the same endpoints handle status, follow-ups, and cancellation no matter which API started it. +Every factory run is still an ordinary run, so Agent & run endpoints handle status, follow-ups, and cancellation no matter which endpoint family started it. ## Discover a factory @@ -119,12 +119,12 @@ Content-Type: application/json } ``` -See [key endpoints](/reference/api-and-sdk/#key-endpoints) for the full set of run-management operations, including cancellation. +See [key endpoints](/factories/api-and-sdk/#key-endpoints) for the full set of run-management operations, including cancellation. ## Related pages -* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the factory API alongside Slack, GitHub, and Factory MCP. +* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including factory endpoints alongside Slack, GitHub, and Factory MCP. * [Build a Mattermost bot for Warp Factories](/guides/external-tools/build-a-mattermost-bot-for-warp-factories/) - A worked example that discovers a factory and dispatches and continues a task from a custom chat integration. * [Factory MCP](/factories/factory-mcp/) - Connect a local coding agent to a factory instead of calling the REST API directly. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying Agent API. +* [Agent & run endpoints](/factories/api-and-sdk/) - Full endpoint reference, SDKs, and error codes for the underlying Warp Platform API. * [How Warp Factories work](/factories/how-factories-work/) - The stages a dispatched task moves through after the foreman picks it up. diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index b0eb0f94e..f0aa1d243 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -257,7 +257,7 @@ harness: ### `agentDefaults.harness` -The harness and model that runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude`, `codex`, or `gemini` — the values the definition schema validates. `claude-code` is also accepted as an alias for `claude`; prefer `claude`, the canonical [harness identifier](/platform/harnesses/#harness-identifiers) that the CLI and the Agent API use for the same harness. For what each harness does and which ones your team can run, see [supported harnesses](/platform/harnesses/). +The harness and model that runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude`, `codex`, or `gemini` — the values the definition schema validates. `claude-code` is also accepted as an alias for `claude`; prefer `claude`, the canonical [harness identifier](/platform/harnesses/#harness-identifiers) that the CLI and the Warp Platform API use for the same harness. For what each harness does and which ones your team can run, see [supported harnesses](/platform/harnesses/). ```yaml harness: @@ -291,7 +291,7 @@ MCP servers for agents that don't declare their own, in the same form as [`mcpSe ### `agentDefaults.workerHost` -Where runs execute: `warp` for Warp-hosted compute, or the ID of a connected worker in the [managed self-hosting architecture](/platform/self-hosting/#managed-architecture). Configure the worker's Docker, Kubernetes, or Direct backend on the worker itself; the factory definition selects the worker and a compatible runner. +Where runs execute: `warp` for Warp-hosted compute, or the ID of a connected [self-hosted worker](/factories/self-hosting/). Configure the worker's Docker, Kubernetes, or Direct backend on the worker itself; the factory definition selects the worker and a compatible runner. ### `agentDefaults.computerUseModel` @@ -443,7 +443,7 @@ An automation may also declare `model` or `harness`, `runner`, `environmentId`, ## `runners/<name>.yaml` -Optional. Each file defines a runner: the compute a run executes on. The runner's name comes from the file name, and agents and automations select it by that name. See [cloud agent runners](/platform/runners/) for how runners behave. For three runners selected per agent, including a macOS runner, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr). +Optional. Each file defines a runner: the compute a run executes on. The runner's name comes from the file name, and agents and automations select it by that name. See [cloud agent runners](/factories/runners/) for how runners behave. For three runners selected per agent, including a macOS runner, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr). ```yaml title="runners/linux-build.yaml" description: Linux runner for payments builds and tests @@ -725,7 +725,7 @@ agentDefaults: workerHost: SELF_HOSTED_WORKER_ID ``` -Pair `workerHost` with a runner whose `platform` matches the worker's operating system and architecture. Follow the [Self-hosting quickstart](/platform/self-hosting/quickstart/) to deploy and connect a managed worker, then see [choose an execution host](/factories/infrastructure-and-security/#choose-an-execution-host) for the factory-specific setup. For a working definition, see [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker). +Pair `workerHost` with a runner whose `platform` matches the worker's operating system and architecture. Follow the [Self-hosting quickstart](/factories/self-hosting/quickstart/) to deploy and connect a managed worker, then see [choose an execution host](/factories/infrastructure-and-security/#choose-an-execution-host) for the factory-specific setup. For a working definition, see [`07-self-hosted-worker`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/07-self-hosted-worker). ## Related pages diff --git a/src/content/docs/factories/factory-dashboard.mdx b/src/content/docs/factories/factory-dashboard.mdx index 4c1310399..9d6ea3d48 100644 --- a/src/content/docs/factories/factory-dashboard.mdx +++ b/src/content/docs/factories/factory-dashboard.mdx @@ -81,13 +81,13 @@ When an agent proposes a change to a Warp-managed definition, a spec review for * **Repositories** - The repos the factory works in. * **Pull request authorship** - Whether pull requests are authored by the agent or the run creator (the definition's [`credentialStrategy`](/factories/factory-as-code/#credentialstrategy)). * **Analysis model** - The model [Self-improvement](/factories/measure-and-improve/self-improvement/) uses to analyze failed runs. -* **Runners** - The compute the factory's runs execute on. +* **Runners** - The compute the factory's runs execute on. See [factory runners](/factories/runners/) to choose runner configuration or [managed self-hosting](/factories/self-hosting/) to run factory work on your infrastructure. * **Integrations** - The integrations this factory can access. * **Deletion** - Deletes the factory. This cannot be undone. For a file-managed factory, `runners/*.yaml` in the repository is the source of truth. Anything managed in an external repository is read-only in Settings. -## Next steps +## Related pages * [Factory inbox](/factories/factory-inbox/) - See and resolve the questions, spec approvals, and PR reviews waiting on you. * [How Warp Factories work](/factories/how-factories-work/) - The stages work moves through and where humans stay in the loop. diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx index 73d922586..96338c571 100644 --- a/src/content/docs/factories/factory-mcp.mdx +++ b/src/content/docs/factories/factory-mcp.mdx @@ -74,7 +74,7 @@ In clients that use the `mcpServers` JSON format, such as Cursor: For Codex and other clients, follow the [client's own remote-server instructions](https://developers.openai.com/codex/mcp/#connect-codex-to-an-mcp-server) with the same URL. -Automation that runs without a person present, such as a CI pipeline or a headless server, can't complete the browser sign-in. For those cases, authenticate with an [agent API key](/reference/cli/api-keys/) instead, passed as a bearer token: +Automation that runs without a person present, such as a CI pipeline or a headless server, can't complete the browser sign-in. For those cases, authenticate with an [agent API key](/agents/cli/oz-cli/api-keys/) instead, passed as a bearer token: ```json { diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index d481c0181..435685dcb 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -11,7 +11,7 @@ sidebar: Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: -A factory is a team of cloud agents that ships software the way your team does: a request comes in, moves through the stages it needs, and comes back as a pull request ready for review. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle. +A factory is a fleet of agents wired to your software development lifecycle. It connects your repositories and tools to move requests through triage, specification, implementation, review, and verification, while people stay in control of key decisions. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle. Deciding which repositories belong in this factory is a separate question. See [sizing a factory](/factories/#sizing-a-factory) for that guidance. @@ -21,12 +21,12 @@ A **work item** is a single request the factory acts on, such as an issue, suppo The diagram's components, from intake to improvement: -* **Work sources** - Work items arrive from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), from [custom webhooks](/factories/webhooks/) and the [factory API](/factories/factory-api/), from local coding agents through the [Factory MCP](/factories/factory-mcp/), or from direct runs and schedules. +* **Work sources** - Work items arrive from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), from [custom webhooks](/factories/webhooks/) and [factory endpoints](/factories/factory-api/), from local coding agents through the [Factory MCP](/factories/factory-mcp/), or from direct runs and schedules. * **Automations** - [Automations](/factories/automations/) filter provider events and decide which agent handles them. Schedules fire them on a timer; direct requests go straight to the foreman. * **Foreman and stage agents** - The foreman holds one conversation per work item and dispatches the Triage, Spec, Implement, and Review agents as the work needs them. See [factory agents](/factories/factory-agents/) and the stages below. * **Human handoff** - The factory opens a pull request with evidence, updates the original work item, and you review and merge. * **Factory definition** - Version-controlled agents, automations, runners, scorers, skills, and webhooks define the factory, either Warp-managed or in a GitHub repository your team owns. See [definitions as code](/factories/factory-as-code/). -* **Execution** - Every stage runs as a cloud agent run on Warp-hosted or [self-hosted](/platform/self-hosting/) compute, with the workspace from the factory's repositories and each stage's configured model and [harness](/platform/harnesses/). +* **Execution** - Every stage runs as a cloud agent run on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, with the workspace from the factory's repositories and each stage's configured model and [harness](/platform/harnesses/). * **Factory dashboard** - Metrics, work items by stage, and runs and costs. See the [factory dashboard](/factories/factory-dashboard/). * **Measure and improve** - [Scorers](/factories/measure-and-improve/) classify completed runs, benchmarks compare configurations, and self-improvement turns repeat failures into follow-up pull requests for your review. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 06fb556ff..afb0a702d 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -13,7 +13,7 @@ import VideoEmbed from '@components/VideoEmbed.astro'; Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. If your team already has access, sign in to the <a href={VARS.FACTORY_WEB_APP_URL}>{VARS.FACTORY_WEB_APP}</a>. ::: -A software factory takes in requests (bug reports, feature specs, support escalations), and a coordinated fleet of agents works them into a stream of mergeable pull requests instead of a growing backlog. Warp Factories gives you the building blocks, so your team stays in the loop where it matters, approving specs when needed and merging every pull request. +A factory is a cloud automation loop around your software development lifecycle. It combines repositories, tools, agents, and execution infrastructure to move requests through triage, specification, implementation, review, and verification, while people stay in control of key decisions. <VideoEmbed url="https://www.youtube.com/watch?v=0WBk4ai8y1A" title="Introducing Warp Factories" /> @@ -21,7 +21,7 @@ A software factory takes in requests (bug reports, feature specs, support escala In practice, that means tracking each request as a work item, such as an issue, ticket, or triggered task, and moving it through specialized agents that triage it, write a specification when one is needed, implement the change, and review the result. -A factory is one deployed instance of that pattern, connecting your repositories and engineering tools to a team of agents, execution infrastructure, and a measurable workflow. Each factory applies a single policy across all of its work sources, so deploy separate factories for repository groups that need different policies. +Each factory applies a single policy across its work sources, so deploy separate factories for repository groups that need different policies. ### Sizing a factory @@ -53,35 +53,23 @@ Warp Factories is designed for engineering teams with repeatable work that exten * **Integrations and the Factory MCP** - Work flows in from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/), plus [custom webhooks](/factories/webhooks/), direct runs, and schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients. * **Model and harness choice** - Each agent can use a different model and [supported harness](/platform/harnesses/), including the Warp Agent, Claude Code, and Codex. * **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs, [Benchmarks](/factories/benchmarks/) compare fixed tasks across configurations, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into follow-up work the factory proposes for review. -* **Infrastructure control** - Run on Warp-hosted infrastructure, or self-host execution on an eligible Enterprise plan. Teams can also connect supported inference providers and scope secrets. See [infrastructure and security](/factories/infrastructure-and-security/) for the available controls. +* **Infrastructure control** - Choose Warp-hosted or managed self-hosted execution on an eligible Enterprise plan. The [infrastructure and security](/factories/infrastructure-and-security/) page compares execution models and links to the self-hosting setup path, as well as available inference and credential controls. -## How Warp Factories relates to other Warp products +## How Warp Factories fits into Warp -| Product | How it relates | -| --- | --- | -| **Warp** | The interactive terminal where you develop locally with agents and code review. A factory runs independently in the cloud. | -| **Warp Agent** | Warp's built-in agent harness. A factory's agents can run on it or on another supported harness. | -| **{VARS.WARP_CLI}** | Runs the Warp Agent in any terminal and exchanges work with a factory through the Factory MCP. | -| **{VARS.WARP_AUTOMATION_PLATFORM}** | Provides the cloud runs, runners, integrations, secrets, [multi-agent orchestration](/platform/orchestration/), and APIs that a factory assembles into one workflow. | - -## The platform behind a factory - -Warp Factories is built on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/), Warp's programmable system for running and coordinating agents at scale. A factory doesn't replace the platform; it assembles the platform's primitives into one standing workflow, so what you already know about cloud agents carries over: +Warp Factories builds on the same agent infrastructure used across Warp. Every factory agent produces a standard [cloud agent run](/platform/), so the same APIs, runners, models, security controls, and observability apply. -* **Runs** - Every factory agent executes as a [cloud agent run](/platform/), with the same run records and [session sharing](/platform/viewing-cloud-agent-runs/) as any other cloud agent. -* **Execution** - [Runners](/platform/runners/) provide the compute each agent works on, and eligible Enterprise teams can route execution to [managed self-hosted workers](/platform/self-hosting/). -* **Agent configuration** - Each agent runs on a supported [harness](/platform/harnesses/) and model, with [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/) scoping what it can reach. -* **Billing** - A factory's runs consume [platform credits](/support-and-community/plans-and-billing/platform-credits/) the same way as any other cloud agent run. - -The factory layer adds the workflow on top: the foreman and its agents, work items that carry each request across runs, definitions as code, default automations for connected tools, and the Scorer and Self-improvement loop. - -Use a standalone [cloud agent](/platform/) for a single task or one-trigger automation. Any agent can spawn children with [multi-agent orchestration](/platform/orchestration/) without a factory. Use a factory for standing, multi-stage work that needs named agents with separate configuration and one place to route, measure, and improve the process. +| Product | Role | +| --- | --- | +| **Warp** | The interactive development experience for local work with agents and code review. | +| **Warp Agent** | The built-in agent harness that can power an individual factory agent. | +| **Warp Factories** | Multi-agent workflows for software development. | ## Key terms Setup gives a factory and its foreman the same name by default, so it's easy to mistake one for the other. Here's how the terms differ: -* **factory** - An individual deployed software factory, built on Warp Factories infrastructure and connecting your repositories and tools to a team of agents. Distinct from Warp Factories, the product, and from the foreman, its coordinating agent. +* **factory** - A cloud automation loop around your software development lifecycle. It combines repositories, tools, agents, and execution infrastructure to move requests through the factory workflow. Distinct from Warp Factories, the product, and from the foreman, its coordinating agent. * **foreman** - The coordinating agent inside a factory, and the only one you talk to. It dispatches the other [factory agents](/factories/factory-agents/) and reports back. Every factory has exactly one. * **Foreman name** - The handle your team @-mentions in Slack and Linear to reach the foreman. Setup copies it from the factory's name, so the two usually match even though they're different things. See [Foreman name](/factories/factory-agents/#foreman-name). @@ -93,7 +81,7 @@ flowchart LR Slack["Slack or Linear"] -->|"@handle"| Foreman ``` -## Next steps +## Related pages * [**Set up a factory**](/factories/quickstart/) - Create a factory and send its first work item. * [**Understand the execution model**](/factories/how-factories-work/) - See how the foreman coordinates stages, runs, and human decisions. diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index 049ce2780..a75d50504 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -27,7 +27,7 @@ flowchart LR C --> D["Warp-managed storage"] ``` -Self-hosting moves only the execution plane: with a managed self-hosted worker, repository checkouts, command execution, and the sandbox filesystem stay on machines you control, but content that enters prompts, results, transcripts, attachments, artifacts, or telemetry still flows through Warp and the providers you configure. See [deployment patterns](/platform/deployment-patterns/) and [self-hosting security and networking](/platform/self-hosting/security-and-networking/) for the broader data model. +Self-hosting moves only the execution plane: with a managed self-hosted worker, repository checkouts, command execution, and the sandbox filesystem stay on machines you control, but content that enters prompts, results, transcripts, attachments, artifacts, or telemetry still flows through Warp and the providers you configure. See [deployment patterns](/factories/deployment-patterns/) and [execution security](/platform/execution-security/) for the broader data model. The diagram below maps those boundaries for self-hosted execution; factory runs follow the same data model. See the [data security and boundaries](/platform/architecture/#data-security-and-boundaries) reference for a description of each data class. @@ -35,15 +35,15 @@ The diagram below maps those boundaries for self-hosted execution; factory runs ## Runners -A runner defines the operating system, architecture, sandbox image, and instance shape (vCPUs and memory) for a factory agent. The factory's [definition](/factories/factory-as-code/) supplies its repositories, setup commands, and secrets; the execution host determines whether that runner uses Warp-hosted or self-hosted compute. +A runner defines the compute a factory's agents work on: the operating system and architecture, the sandbox image, and the instance shape (vCPUs and memory). The workspace itself — repositories, setup commands, and secrets — comes from the factory's [definition](/factories/factory-as-code/). See the [runner reference](/factories/runners/) for the available compute options. Declare runners as `runners/*.yaml` files. Every agent inherits `agentDefaults.runner`, and an agent or automation can override it. A self-hosted runner must match the worker's operating system and architecture. Warp provisions hosted runners within your plan limits; your team provisions and operates self-hosted compute. -See [cloud agent runner compute options](/platform/runners/) and [factory runner syntax](/factories/factory-as-code/#runnersnameyaml). +See [cloud agent runner compute options](/factories/runners/) and [factory runner syntax](/factories/factory-as-code/#runnersnameyaml). ## Choose an execution host -A factory runs its work on one of two execution hosts: Warp-hosted compute or a worker in the [managed self-hosting architecture](/platform/self-hosting/#managed-architecture). +A factory runs its work on one of two execution hosts: Warp-hosted compute or a worker in the [managed self-hosting architecture](/factories/self-hosting/#managed-architecture). | Decision area | Warp-hosted | Managed self-hosted | | --- | --- | --- | @@ -56,7 +56,7 @@ A factory runs its work on one of two execution hosts: Warp-hosted compute or a To route factory work to a managed self-hosted worker (an Enterprise feature): -1. **Deploy a worker** - Use the [self-hosting overview](/platform/self-hosting/) to choose a managed backend and review its requirements, then connect a worker that authenticates to Warp with an agent API key. Workers run on `linux/amd64` and `linux/arm64`, and the worker's platform determines which workloads it can run. +1. **Deploy a worker** - Review the [self-hosting requirements](/factories/self-hosting/), then connect a worker that authenticates to Warp with an agent API key. Workers run on `linux/amd64` and `linux/arm64`, and the worker's platform determines which workloads it can run. 2. **Pair it with a compatible runner** - Choose a runner that matches the worker's platform. 3. **Select the worker in the factory definition** - Set [`workerHost`](/factories/factory-as-code/) so the factory routes work to it. @@ -70,9 +70,9 @@ Factories use managed self-hosting, so Warp still orchestrates their runs. The w | Structure | How factory runs execute | What your team operates | Use it when | | --- | --- | --- | --- | -| **[Docker](/platform/self-hosting/managed-docker/)** (default) | In a separate Docker container on the worker host | The worker daemon, host, Docker daemon, images, capacity, and container policy | Docker is available and you want per-run container isolation without Kubernetes | -| **[Kubernetes](/platform/self-hosting/managed-kubernetes/)** | As a Kubernetes Job in the worker's namespace | The worker deployment, cluster, namespace RBAC, scheduling, admission policy, and capacity | Your team already operates Kubernetes or needs cluster-native policy and scheduling | -| **[Direct](/platform/self-hosting/managed-direct/)** | In a separate workspace directly on the worker host, sharing its OS and kernel | The worker daemon, host security, dependencies, capacity, and cleanup | A container runtime isn't available or runs need direct access to host resources | +| **[Docker](/factories/self-hosting/managed-docker/)** (default) | In a separate Docker container on the worker host | The worker daemon, host, Docker daemon, images, capacity, and container policy | Docker is available and you want per-run container isolation without Kubernetes | +| **[Kubernetes](/factories/self-hosting/managed-kubernetes/)** | As a Kubernetes Job in the worker's namespace | The worker deployment, cluster, namespace RBAC, scheduling, admission policy, and capacity | Your team already operates Kubernetes or needs cluster-native policy and scheduling | +| **[Direct](/factories/self-hosting/managed-direct/)** | In a separate workspace directly on the worker host, sharing its OS and kernel | The worker daemon, host security, dependencies, capacity, and cleanup | A container runtime isn't available or runs need direct access to host resources | All three structures keep execution on your infrastructure while Warp operates the control plane. @@ -124,8 +124,9 @@ Warp meters hosted compute, Warp-provided inference, and platform services. Mana ## Related pages -* [**Deployment patterns**](/platform/deployment-patterns/) - Compare Warp-hosted, managed self-hosted, and CLI-only execution. -* [**Self-hosting overview**](/platform/self-hosting/) - Choose a managed worker backend and follow its setup guide. -* [**Self-hosting security and networking**](/platform/self-hosting/security-and-networking/) - Review data boundaries, network egress, and backend-specific controls. +* [**Deployment patterns**](/factories/deployment-patterns/) - Compare Warp-hosted, managed self-hosted, and CLI-only execution. +* [**Managed self-hosting**](/factories/self-hosting/) - Choose a worker backend and follow its setup guide. +* [**Execution security**](/platform/execution-security/) - Review data boundaries, network egress, and backend-specific controls. * [**Bring Your Own LLM**](/enterprise/enterprise-features/bring-your-own-llm/) - Compare customer-owned inference options and provider support. * [**Enterprise security overview**](/enterprise/security-and-compliance/security-overview/) - Review data handling, ZDR, compliance, and access controls across Warp. +* [Team-managed model keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) - Configure customer-supplied inference credentials. diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index b27d2a317..412390ea0 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -12,26 +12,19 @@ import { VARS } from '@data/vars'; Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team. ::: -A factory is a group of cloud agents that turns incoming requests into pull requests. You talk to one agent, the **foreman**. It picks up the request from wherever it starts, such as Slack, an issue tracker, or a code host, then dispatches the factory's other agents, each owning one part of the software development lifecycle. People stay in the loop at the points that matter: approving specs when needed and merging pull requests. +A factory is a fleet of agents wired to your software development lifecycle. It connects your repositories and tools to move requests through triage, specification, implementation, review, and verification, while people stay in control of key decisions. You talk to one agent, the **foreman**. It picks up the request from wherever it starts, such as Slack, an issue tracker, or a code host, then dispatches the factory's other agents, each owning one part of the software development lifecycle. In this quickstart, you will create a factory and take one small work item from prompt to pull request in less than 10 minutes. ## What you'll decide -Warp walks you through factory setup. Along the way, you decide: - -* The code host and repositories the factory works on. -* The factory's name and its foreman's @-mention alias. -* Which default agents the foreman can dispatch. -* Whether to connect a chat tool and an issue tracker, or add them later. - -You can change any of these after setup, so a best guess is fine for now. +Setup connects your code host, selects repositories, names the factory and its foreman, and chooses default agents. You can also connect Slack and an issue tracker now or add them later. Every choice can be changed after setup. ## Prerequisites -* **Warp Factories access** - Warp Factories is in Early Access. [Request access](https://www.warp.dev/factories/request-access) for your team. -* **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/). Factory agents consume the team's [credits](/support-and-community/plans-and-billing/platform-credits/). -* **Repository access** - You authorize a code host during setup and choose which repositories the factory can reach. If your organization restricts app installations, ask an owner to approve the connection. See the [GitHub](/factories/integrations/github/) and [GitLab](/factories/integrations/gitlab/) integration guides. +* **Warp Factories access** - [Request Early Access](https://www.warp.dev/factories/request-access) for your team. +* **A Warp team with credits** - The team's [credits](/support-and-community/plans-and-billing/platform-credits/) are consumed by factory agents. +* **Repository access** - Authorize GitHub or GitLab during setup. If your organization restricts app installations, ask an owner to approve the connection. ## Set up your factory @@ -50,40 +43,35 @@ Warp walks you through a setup wizard: <figcaption>Click + next to Factories to open the setup wizard.</figcaption> </figure> -2. Click **I want to use repos from GitHub** or **I want to use repos from GitLab**, then choose the organization or group you want to connect. +2. Click **I want to use repos from GitHub** or **I want to use repos from GitLab**, then choose the organization or group to connect. <figure style={{ maxWidth: "563px" }}> ![The Connect a GitHub organization screen, with an already-connected organization shown as an option.](../../../assets/factories/quickstart-connect-organization.png) <figcaption>Choose the organization or group whose repositories the factory will use. GitLab shows an equivalent screen for groups.</figcaption> </figure> -3. On **Select your repos**, search for and select the repositories the factory works in, then click **Add repos**. Start with one or two. Every agent in the factory shares this repo set, so a focused set keeps their context tight, and you can add more later. - - :::note - Group repositories by product surface, not by team or task. For example, group all the repos behind one application. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. - ::: +3. On **Select your repos**, select the repositories the factory works in, then click **Add repos**. Start with one or two repositories that ship together, and add more later. See [sizing a factory](/factories/#sizing-a-factory) before adding a repository another factory already covers. <figure style={{ maxWidth: "563px" }}> ![The Select your repos screen, searching for repositories by name.](../../../assets/factories/quickstart-select-repos.png) <figcaption>Search for and select the repositories the factory works in.</figcaption> </figure> -4. Name the factory. This also sets its [**Foreman name**](/factories/factory-agents/#foreman-name), the handle your team @-mentions in Slack and Linear. Keep it short and recognizable, or set your own. The two match by default, but they name different things: the handle reaches the factory's foreman, the agent that coordinates its work. +4. Name the factory. This also sets its [**Foreman name**](/factories/factory-agents/#foreman-name), the handle your team @-mentions in Slack and Linear. The factory and foreman names match by default, but the foreman is the agent that coordinates its work. <figure style={{ maxWidth: "563px" }}> ![The Give your factory some personality screen, with Factory name and Foreman name fields filled in.](../../../assets/factories/quickstart-name-factory.png) <figcaption>Name the factory and, optionally, add a description and avatar.</figcaption> </figure> -5. Optionally, connect a chat tool so teammates can hand work to the factory from Slack. You can also skip this step and connect Slack later. See [connect your factory](/factories/connect-your-factory/). -6. Toggle the agents the foreman can dispatch: **Triage**, **Spec**, **Implement**, and **Review**. All four start enabled, and at least one is required. Leave **Implement** on so this quickstart can end in a pull request. See [factory agents](/factories/factory-agents/) for what each does. +5. Toggle the agents the foreman can dispatch: **Triage**, **Spec**, **Implement**, and **Review**. All four start enabled. Leave **Implement** on so this quickstart can end in a pull request. See [factory agents](/factories/factory-agents/) for details. <figure style={{ maxWidth: "563px" }}> ![The Pick your factory agents screen, with the Foreman and all four default agents shown as enabled.](../../../assets/factories/quickstart-pick-agents.png) <figcaption>Toggle which default agents the foreman can dispatch.</figcaption> </figure> -7. Optionally, connect an issue tracker so teammates can hand work to the factory from Linear or Jira. You can also skip this step and connect one later. See [connect your factory](/factories/connect-your-factory/). +6. Optionally connect Slack and an issue tracker so teammates can hand work to the factory from the tools they already use. You can add either later from [connect your factory](/factories/connect-your-factory/). Warp creates the factory and opens its [dashboard](/factories/factory-dashboard/). @@ -91,7 +79,7 @@ Warp creates the factory and opens its [dashboard](/factories/factory-dashboard/ _~5 minutes_ -You can request work from the tools your team already uses. Mention the factory in a Slack channel, or assign it an issue in your tracker, and it replies right there. If you skipped the integrations, start a run from the **Runs** page of the factory's [dashboard](/factories/factory-dashboard/) instead. +Send work from Slack or an issue tracker. If you skipped integrations, start a run from the **Runs** page of the factory's [dashboard](/factories/factory-dashboard/). 1. Describe one small, verifiable change and send it: @@ -101,9 +89,9 @@ You can request work from the tools your team already uses. Mention the factory repo's lint check, and open a pull request. ``` - Adapt the pattern to your repository: name the file, the change you expect, and the command that verifies it. A narrow, explicit request makes the first run easy to judge. + Name the file, expected change, and verification command. -2. The foreman picks up the request, dispatches the factory's agents as child runs, and posts progress and questions back where the request started. Follow the foreman's run and the child runs it dispatches on the factory's [Runs page](/factories/factory-dashboard/#inspect-runs). If anything needs your input, such as a spec approval or a finished pull request to review, it also appears in your [inbox](/factories/factory-inbox/). +2. The foreman dispatches the agents needed for the request and posts progress where it started. Follow the foreman and child runs on the factory's [Runs page](/factories/factory-dashboard/#inspect-runs). Requests for input also appear in your [inbox](/factories/factory-inbox/). If you connected Slack, you can follow along there instead: @@ -112,12 +100,12 @@ You can request work from the tools your team already uses. Mention the factory <figcaption>The factory's Slack app posting progress updates back in the thread where you sent the request.</figcaption> </figure> -3. When the Implement agent finishes, the work item links to the pull request. Review and merge it the way you would any other: a factory hands off at the pull request and never merges for you. +3. When the Implement agent finishes, review and merge the linked pull request as you would any other. ## Next steps -* [**Connect your factory**](/factories/connect-your-factory/) - Route work in from Slack threads, Linear issues, and other intake paths. -* [**Factory MCP**](/factories/factory-mcp/) - Send work to the factory from a coding agent or MCP client. -* [**How Warp Factories work**](/factories/how-factories-work/) - The work-item lifecycle and where people stay in the loop. +* [**Connect your factory**](/factories/connect-your-factory/) - Configure intake sources. +* [**Factory MCP**](/factories/factory-mcp/) - Send work from a coding agent or MCP client. +* [**How Warp Factories work**](/factories/how-factories-work/) - Understand the work-item lifecycle. * [**warp-factory-examples**](https://github.com/warpdotdev/warp-factory-examples) - Complete working definitions to copy, from a single-repo quickstart to the full issue-to-PR lifecycle. -* [**Troubleshooting Warp Factories**](/factories/troubleshooting/) - Fixes for common issues during setup and your first runs. +* [**Troubleshooting Warp Factories**](/factories/troubleshooting/) - Fix common setup and run issues. diff --git a/src/content/docs/platform/runners.mdx b/src/content/docs/factories/runners.mdx similarity index 84% rename from src/content/docs/platform/runners.mdx rename to src/content/docs/factories/runners.mdx index 6692e4a06..7e9fe8da9 100644 --- a/src/content/docs/platform/runners.mdx +++ b/src/content/docs/factories/runners.mdx @@ -1,17 +1,21 @@ --- -title: Cloud agent runners +title: Runners for Warp Factories sidebar: label: "Runners" description: >- - Runners define the OS, architecture, instance size, and sandbox image cloud - agents run on, managed with the {{WARP_AGENT_CLI}}. + Runners define the OS, architecture, instance size, and sandbox image for + cloud agent runs, including work from Warp Factories. --- import { VARS } from '@data/vars'; import { Tabs, TabItem } from '@astrojs/starlight/components'; -Runners define the compute a [cloud agent](/platform/) runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. +Runners define the compute a [cloud agent](/platform/) runs on: the operating system, CPU architecture, instance size, and sandbox image used to execute a run. Factory agents select runners through the [factory definition](/factories/factory-as-code/) or the [factory dashboard](/factories/factory-dashboard/). -A runner is a reusable compute configuration. Where an [environment](/platform/environments/) defines _what_ an agent works on (the repos, setup commands, and toolchain), a runner defines _where and on what hardware_ that work executes. Separating the two lets you reuse the same environment across different machine shapes—for example, a small Linux box for routine tasks and a larger instance for heavier builds. +A runner is a reusable compute configuration. Where an [environment](/platform/environments/) defines _what_ an agent works on (the repos, setup commands, and toolchain), a runner defines _where and on what hardware_ that work executes. This lets any cloud-agent workflow use different machine shapes for different workloads. + +## Configure runners for a factory + +Set a factory's default runner in `agentDefaults.runner`, then override it per agent or automation when the work needs different compute. For file-managed factories, edit `runners/*.yaml` in the factory definition. For Warp-managed factories, edit runner files in the factory dashboard. :::note Most runs don't need a custom runner. Every environment has a default runner, and Warp picks a sensible default shape when you don't specify one. Create a runner when you need a specific OS, architecture, instance size, or sandbox image. @@ -32,7 +36,7 @@ A runner is the compute layer for a cloud agent run. When a run starts, Warp pro * **Environment** – Defines the workspace: Docker image, repositories, and setup commands. See [Environments](/platform/environments/). * **Runner** – Defines the compute: OS, architecture, instance shape (vCPUs and memory), and sandbox image. -* **Host** – Determines where execution happens (Warp-hosted or [self-hosted](/platform/self-hosting/) infrastructure). +* **Host** – Determines where execution happens (Warp-hosted or [self-hosted](/factories/self-hosting/) infrastructure). Each environment has a default runner. Specifying a runner for a run overrides that default for that run only. @@ -62,9 +66,9 @@ Each environment has a default runner. Specifying a runner for a run overrides t </TabItem> </Tabs> -## Managing runners with the CLI +## Managing runners with the legacy CLI -Use the [{VARS.WARP_AGENT_CLI}](/reference/cli/) to create, list, update, and delete runners. Runner commands require an authenticated CLI—see the [CLI quickstart](/reference/cli/quickstart/) to get set up. +The legacy [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) also supports creating, listing, updating, and deleting reusable runners for standalone cloud-agent workflows. ### Create a runner @@ -145,4 +149,4 @@ You can also select a runner when [running orchestrated agents](/platform/orches * [Environments](/platform/environments/) – Define the repos, image, and setup commands an agent works with. * [Managing cloud agents](/platform/managing-cloud-agents/) – Start, monitor, and manage cloud agent runs. -* [{VARS.WARP_AGENT_CLI} reference](/reference/cli/) – Full command-line reference for runners and every other cloud agent command. +* [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/) – Full command-line reference for runners and every other cloud agent command. diff --git a/src/content/docs/factories/self-hosting/index.mdx b/src/content/docs/factories/self-hosting/index.mdx new file mode 100644 index 000000000..8dec2503a --- /dev/null +++ b/src/content/docs/factories/self-hosting/index.mdx @@ -0,0 +1,57 @@ +--- +title: Managed self-hosting for Warp Factories +description: >- + Run Warp Factories on your own infrastructure with a managed worker for + Docker, Kubernetes, or direct-host execution. +sidebar: + label: "Managed self-hosting" +--- +import { VARS } from '@data/vars'; + +Managed self-hosting runs factory work on infrastructure you control. A worker connects to Warp, receives work from your factory, and executes it in Docker containers, Kubernetes Jobs, or directly on the worker host. Repository clones, build artifacts, and execution workspaces stay on your infrastructure. + +:::note +Managed self-hosting is available to Enterprise teams. [Contact sales](https://www.warp.dev/contact-sales) to enable it for your team. +::: + +Managed workers run only on Linux `amd64` or `arm64` hosts. To run agents on macOS or Windows, use [unmanaged execution](/platform/unmanaged-execution/). + +<a id="managed-architecture"></a> + +## How managed self-hosting works + +Run the `oz-agent-worker` daemon on infrastructure that can reach your repositories and internal services. The worker connects outbound to the {VARS.WARP_AUTOMATION_PLATFORM}, waits for factory work, and runs each task using the backend you configure. + +A managed worker is the self-hosted execution option for a factory. [Unmanaged execution](/platform/unmanaged-execution/) runs standalone agents directly from your own CI or infrastructure. Route factory work to a managed worker through the [factory definition](/factories/factory-as-code/#agentdefaultsworkerhost). + +<a id="choosing-a-managed-backend"></a> + +## Choose a backend + +* **Docker** - Run each factory task in an isolated container. Start with the [Docker quickstart](/factories/self-hosting/quickstart/) or see the [Docker backend](/factories/self-hosting/managed-docker/) for registries, volumes, and runtime configuration. +* **Kubernetes** - Run each task as a Kubernetes Job in your cluster. See the [Kubernetes backend](/factories/self-hosting/managed-kubernetes/) for Helm installation, RBAC, and pod configuration. +* **Direct** - Run tasks directly on the worker host when a container runtime is not available. See the [Direct backend](/factories/self-hosting/managed-direct/) for isolation and workspace requirements. + +## Data and network boundaries + +Managed self-hosting moves execution to your infrastructure. Warp still provides the service that coordinates runs, stores session data, and routes inference requests. Review [execution security](/platform/execution-security/) before connecting a worker to internal repositories or services. + +The worker requires outbound HTTPS access to Warp and any repositories, registries, and services that its tasks use. It does not require inbound firewall access. + +<a id="routing-runs-to-self-hosted-workers"></a> + +## Configure a factory to use a worker + +Define the worker host and a compatible runner in your [factory definition](/factories/factory-as-code/). The factory dashboard shows each configured runner and the worker that executes its work. Use the [worker reference](/factories/self-hosting/reference/) to configure the worker process and the [factory dashboard](/factories/factory-dashboard/) to inspect its runs. + +## Monitor and troubleshoot workers + +[Worker monitoring](/factories/self-hosting/monitoring/) exports OpenTelemetry metrics for worker health, capacity, and task throughput. If a worker cannot connect or tasks remain queued, use [self-hosting troubleshooting](/factories/self-hosting/troubleshooting/). + +## Related pages + +* [Docker quickstart](/factories/self-hosting/quickstart/) - Start a managed worker with Docker. +* [Factory runners](/factories/runners/) - Choose the compute configuration for factory work. +* [Infrastructure and security](/factories/infrastructure-and-security/) - Configure execution, inference, storage, and credentials. +* [Worker reference](/factories/self-hosting/reference/) - Look up worker flags and configuration fields. +* [Execution security](/platform/execution-security/) - Review data boundaries and network requirements. diff --git a/src/content/docs/platform/self-hosting/managed-direct.mdx b/src/content/docs/factories/self-hosting/managed-direct.mdx similarity index 77% rename from src/content/docs/platform/self-hosting/managed-direct.mdx rename to src/content/docs/factories/self-hosting/managed-direct.mdx index 555c668c0..f14722f2c 100644 --- a/src/content/docs/platform/self-hosting/managed-direct.mdx +++ b/src/content/docs/factories/self-hosting/managed-direct.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Run the `oz-agent-worker` daemon with the **Direct backend** — tasks execute directly on the worker host without Docker or Kubernetes. The {VARS.WARP_AUTOMATION_PLATFORM} still orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); the worker just runs the agent in a per-task workspace on its own filesystem. :::note -This page covers the [managed architecture](/platform/self-hosting/#managed-architecture) with the Direct backend. For container-based task isolation, see [Managed: Docker](/platform/self-hosting/managed-docker/) or [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/). For invocation-driven use cases, see [Unmanaged](/platform/self-hosting/unmanaged/). +The Direct backend uses the [managed architecture](/factories/self-hosting/#managed-architecture). For container-based task isolation, see [Managed: Docker](/factories/self-hosting/managed-docker/) or [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/). For invocation-driven use cases, see [Unmanaged](/platform/unmanaged-execution/). ::: ## When to use the Direct backend @@ -39,9 +39,9 @@ The Direct backend does not provide per-task container isolation. Each task runs * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). -* **The `oz-agent-worker` binary** installed on the worker host. The Direct backend runs the worker itself on the host rather than in a container, so install it via [Homebrew or a prebuilt binary](/platform/self-hosting/managed-docker/#install-and-run-the-worker). -* **The {VARS.WARP_AGENT_CLI}** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). -* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **The `oz-agent-worker` binary** installed on the worker host. The Direct backend runs the worker itself on the host rather than in a container, so install it via [Homebrew or a prebuilt binary](/factories/self-hosting/managed-docker/#install-and-run-the-worker). +* **The {VARS.WARP_AGENT_CLI}** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli). +* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. --- @@ -63,7 +63,7 @@ Pass `--backend direct`: oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" --backend direct ``` -Or with a [config file](/platform/self-hosting/reference/#config-file): +Or with a [config file](/factories/self-hosting/reference/#config-file): ```yaml worker_id: "my-worker" @@ -125,8 +125,9 @@ backend: ## Related pages -* [Self-hosted worker reference](/platform/self-hosting/reference/#direct-backend-config) — Full config schema for the Direct backend. -* [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and the backend decision guide. -* [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries and security considerations for the Direct backend. -* [Troubleshooting](/platform/self-hosting/troubleshooting/#direct-backend) — Common Direct-backend issues. +* [Self-hosted worker reference](/factories/self-hosting/reference/#direct-backend-config) — Full config schema for the Direct backend. +* [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and the backend decision guide. +* [Factory definition](/factories/factory-as-code/#agentdefaultsworkerhost) — Route factory work to a compatible worker and runner. +* [CLI reference](/agents/cli/oz-cli/) — Route standalone cloud agents to the worker with `--host`. +* [Security and networking](/platform/execution-security/) — Data boundaries and security considerations for the Direct backend. +* [Troubleshooting](/factories/self-hosting/troubleshooting/#direct-backend) — Common Direct-backend issues. diff --git a/src/content/docs/platform/self-hosting/managed-docker.mdx b/src/content/docs/factories/self-hosting/managed-docker.mdx similarity index 83% rename from src/content/docs/platform/self-hosting/managed-docker.mdx rename to src/content/docs/factories/self-hosting/managed-docker.mdx index 2ee278a35..ed42a2625 100644 --- a/src/content/docs/platform/self-hosting/managed-docker.mdx +++ b/src/content/docs/factories/self-hosting/managed-docker.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Run the `oz-agent-worker` daemon with the **Docker backend** — the default managed path. Each agent task runs in an isolated Docker container spawned from the worker, with full orchestration by the {VARS.WARP_AUTOMATION_PLATFORM} (Slack, Linear, schedules, API, `oz agent run-cloud`). :::note -This page covers the [managed architecture](/platform/self-hosting/#managed-architecture) with the Docker backend. For the Kubernetes backend, see [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/). For host execution without a container runtime, see [Managed: Direct](/platform/self-hosting/managed-direct/). If you'd rather invoke agents yourself, see [Unmanaged](/platform/self-hosting/unmanaged/). +The Docker backend uses the [managed architecture](/factories/self-hosting/#managed-architecture). For the Kubernetes backend, see [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/). For host execution without a container runtime, see [Managed: Direct](/factories/self-hosting/managed-direct/). If you'd rather invoke agents yourself, see [Unmanaged](/platform/unmanaged-execution/). ::: ## When to use the Docker backend @@ -27,7 +27,7 @@ This page covers the [managed architecture](/platform/self-hosting/#managed-arch * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. -* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. :::caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. @@ -59,7 +59,7 @@ The `oz-agent-worker` is open source. See the [oz-agent-worker repository](https There are three ways to install and run the worker: as a Docker container, via Homebrew, or as a prebuilt binary from GitHub Releases. Docker is the recommended default. -The worker can be configured entirely via CLI flags, or via a YAML [config file](/platform/self-hosting/reference/#config-file) for more complex setups. +The worker can be configured entirely via CLI flags, or via a YAML [config file](/factories/self-hosting/reference/#config-file) for more complex setups. ### Option 1: Docker (recommended) @@ -104,7 +104,7 @@ You can run multiple workers with the same `--worker-id` for redundancy — the ## Docker backend configuration -The worker can take configuration either via CLI flags or via a YAML [config file](/platform/self-hosting/reference/#config-file). CLI flags take precedence over config file values. +The worker can take configuration either via CLI flags or via a YAML [config file](/factories/self-hosting/reference/#config-file). CLI flags take precedence over config file values. **Common CLI flags:** @@ -152,7 +152,7 @@ backend: - name: GITHUB_TOKEN # inherits from host environment ``` -Pass it with `--config-file config.yaml`. See the [self-hosted worker reference](/platform/self-hosting/reference/) for the full flag and config schema. +Pass it with `--config-file config.yaml`. See the [self-hosted worker reference](/factories/self-hosting/reference/) for the full flag and config schema. --- @@ -212,14 +212,14 @@ Sidecar images (the `oz` binary and dependencies) are pulled from public registr ## Routing runs to this worker -Once your Docker worker is connected, route tasks to it with `--host "<your-worker-id>"`. Routing is the same across all managed backends — see [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) for CLI, scheduled, integration, API, and web UI examples. +Once your Docker worker is connected, route factory work to it with `workerHost` in the [factory definition](/factories/factory-as-code/#agentdefaultsworkerhost). To route a standalone cloud agent with `--host "<your-worker-id>"`, see the [CLI reference](/agents/cli/oz-cli/). --- ## Related pages -* [Self-hosting quickstart](/platform/self-hosting/quickstart/) — ~10-minute path to a running Docker worker. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — Full CLI flag and config file schema. +* [Self-hosting quickstart](/factories/self-hosting/quickstart/) — ~10-minute path to a running Docker worker. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — Full CLI flag and config file schema. * [Environments](/platform/environments/) — Define the Docker image, repos, and setup commands for tasks. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries, egress, and Docker socket considerations. -* [Troubleshooting](/platform/self-hosting/troubleshooting/) — Common issues with the Docker backend. +* [Security and networking](/platform/execution-security/) — Data boundaries, egress, and Docker socket considerations. +* [Troubleshooting](/factories/self-hosting/troubleshooting/) — Common issues with the Docker backend. diff --git a/src/content/docs/platform/self-hosting/managed-kubernetes.mdx b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx similarity index 86% rename from src/content/docs/platform/self-hosting/managed-kubernetes.mdx rename to src/content/docs/factories/self-hosting/managed-kubernetes.mdx index f13bb13b3..44673a3c6 100644 --- a/src/content/docs/platform/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/factories/self-hosting/managed-kubernetes.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Deploy the `oz-agent-worker` daemon into a Kubernetes cluster using the included Helm chart. Each agent task runs as a **Kubernetes Job** in your cluster. The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); your cluster provides the compute, scheduling, and policy enforcement. :::note -This page covers the [managed architecture](/platform/self-hosting/#managed-architecture) with the Kubernetes backend. For the default Docker backend, see [Managed: Docker](/platform/self-hosting/managed-docker/). For host execution without a container runtime, see [Managed: Direct](/platform/self-hosting/managed-direct/). To route runs to a connected worker, see [Routing runs to this worker](/platform/self-hosting/managed-docker/#routing-runs-to-this-worker). +The Kubernetes backend uses the [managed architecture](/factories/self-hosting/#managed-architecture). For the default Docker backend, see [Managed: Docker](/factories/self-hosting/managed-docker/). For host execution without a container runtime, see [Managed: Direct](/factories/self-hosting/managed-direct/). To route runs to a connected worker, see [Routing runs to this worker](/factories/self-hosting/managed-docker/#routing-runs-to-this-worker). ::: ## When to use the Kubernetes backend @@ -39,7 +39,7 @@ This page covers the [managed architecture](/platform/self-hosting/#managed-arch * Allow the worker's namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. -* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. --- @@ -134,7 +134,7 @@ To scale horizontally, deploy multiple Helm releases with distinct worker IDs ra * `kubernetesBackend.extraAnnotations` — Additional annotations for task Jobs and Pods. * `kubernetesBackend.activeDeadlineSeconds` — Maximum task Job lifetime. * `kubernetesBackend.workspaceSizeLimit` — Size limit for workspace `emptyDir` volume. -* `kubernetesBackend.podTemplate` — Raw PodSpec YAML for task Jobs (same as `backend.kubernetes.pod_template` in the [config file](/platform/self-hosting/reference/#config-file)). +* `kubernetesBackend.podTemplate` — Raw PodSpec YAML for task Jobs (same as `backend.kubernetes.pod_template` in the [config file](/factories/self-hosting/reference/#config-file)). **API key Secret:** @@ -143,7 +143,7 @@ To scale horizontally, deploy multiple Helm releases with distinct worker IDs ra * `warp.apiKeySecret.name` — Name of the Secret containing `WARP_API_KEY`. Defaults to `oz-agent-worker`. * `warp.apiKeySecret.key` — Key within the Secret. Defaults to `WARP_API_KEY`. -See the [self-hosted worker reference](/platform/self-hosting/reference/#kubernetes-backend-config) for the full config file schema. +See the [self-hosted worker reference](/factories/self-hosting/reference/#kubernetes-backend-config) for the full config file schema. --- @@ -230,7 +230,7 @@ If your organization uses an external secrets manager (HashiCorp Vault, AWS Secr ## Setup and teardown commands -Use `kubernetesBackend.setupCommand` (Helm value) or `backend.kubernetes.setup_command` ([config file](/platform/self-hosting/reference/#kubernetes-backend-config)) to run a shell command before each task. Use `teardownCommand` / `teardown_command` for cleanup after the task finishes. These run inside the task Pod and are useful for workspace bootstrapping or post-run reporting. +Use `kubernetesBackend.setupCommand` (Helm value) or `backend.kubernetes.setup_command` ([config file](/factories/self-hosting/reference/#kubernetes-backend-config)) to run a shell command before each task. Use `teardownCommand` / `teardown_command` for cleanup after the task finishes. These run inside the task Pod and are useful for workspace bootstrapping or post-run reporting. --- @@ -250,7 +250,7 @@ With the default `metrics.exporter=prometheus`, the chart creates a `Service` wi To push metrics to an OTLP collector instead, set `metrics.exporter=otlp` and configure the endpoint via `metrics.extraEnv`. -See [Monitoring](/platform/self-hosting/monitoring/) for the full list of Helm values, the metric catalog, and sample PromQL queries. +See [Monitoring](/factories/self-hosting/monitoring/) for the full list of Helm values, the metric catalog, and sample PromQL queries. --- @@ -266,10 +266,11 @@ See [Monitoring](/platform/self-hosting/monitoring/) for the full list of Helm v ## Related pages -* [Self-hosted worker reference](/platform/self-hosting/reference/) — Full CLI flag and config file schema, including every Kubernetes backend field. -* [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and the backend decision guide. -* [Routing runs to this worker](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — Full CLI flag and config file schema, including every Kubernetes backend field. +* [Self-hosting overview](/factories/self-hosting/) — Managed vs unmanaged and the backend decision guide. +* [Factory definition](/factories/factory-as-code/#agentdefaultsworkerhost) — Route factory work to a compatible worker and runner. +* [CLI reference](/agents/cli/oz-cli/) — Route standalone cloud agents to the worker with `--host`. * [Environments](/platform/environments/) — Define the task image, repos, and setup commands. -* [Monitoring](/platform/self-hosting/monitoring/) — OpenTelemetry metrics, including Helm chart metrics values. -* [Security and networking](/platform/self-hosting/security-and-networking/) — RBAC, admission policies, and data boundaries. -* [Troubleshooting](/platform/self-hosting/troubleshooting/#kubernetes-backend) — Common Kubernetes-backend issues. +* [Monitoring](/factories/self-hosting/monitoring/) — OpenTelemetry metrics, including Helm chart metrics values. +* [Security and networking](/platform/execution-security/) — RBAC, admission policies, and data boundaries. +* [Troubleshooting](/factories/self-hosting/troubleshooting/#kubernetes-backend) — Common Kubernetes-backend issues. diff --git a/src/content/docs/platform/self-hosting/monitoring.mdx b/src/content/docs/factories/self-hosting/monitoring.mdx similarity index 92% rename from src/content/docs/platform/self-hosting/monitoring.mdx rename to src/content/docs/factories/self-hosting/monitoring.mdx index d9263e2bf..b479e1e28 100644 --- a/src/content/docs/platform/self-hosting/monitoring.mdx +++ b/src/content/docs/factories/self-hosting/monitoring.mdx @@ -78,7 +78,7 @@ The worker pushes metrics at the SDK's default interval. Configure the collector ## Helm chart configuration -The [Helm chart](/platform/self-hosting/managed-kubernetes/) includes built-in support for metrics. Enable metrics with `metrics.enabled=true`: +The [Helm chart](/factories/self-hosting/managed-kubernetes/) includes built-in support for metrics. Enable metrics with `metrics.enabled=true`: ```bash helm install oz-agent-worker ./charts/oz-agent-worker \ @@ -219,8 +219,8 @@ metrics: ## Related pages -* [Self-hosting overview](/platform/self-hosting/) — Architecture, decision guide, and Enterprise requirements. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags, config file schema, and metrics environment variables. -* [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Helm chart deployment, including metrics values. -* [Troubleshooting](/platform/self-hosting/troubleshooting/) — Diagnostics for metrics issues and other common problems. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Network egress and data boundaries. +* [Self-hosting overview](/factories/self-hosting/) — Architecture, decision guide, and Enterprise requirements. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags, config file schema, and metrics environment variables. +* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Helm chart deployment, including metrics values. +* [Troubleshooting](/factories/self-hosting/troubleshooting/) — Diagnostics for metrics issues and other common problems. +* [Security and networking](/platform/execution-security/) — Network egress and data boundaries. diff --git a/src/content/docs/platform/self-hosting/quickstart.mdx b/src/content/docs/factories/self-hosting/quickstart.mdx similarity index 58% rename from src/content/docs/platform/self-hosting/quickstart.mdx rename to src/content/docs/factories/self-hosting/quickstart.mdx index 67deebce4..34a8bcab5 100644 --- a/src/content/docs/platform/self-hosting/quickstart.mdx +++ b/src/content/docs/factories/self-hosting/quickstart.mdx @@ -8,10 +8,10 @@ sidebar: --- import { VARS } from '@data/vars'; -Run your first cloud agent on your own infrastructure in ~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting. +Run your first managed worker on your own infrastructure in ~10 minutes using the Docker backend. After you verify the worker, configure a factory to route its work to that worker. :::note -This quickstart sets up the [managed architecture](/platform/self-hosting/#managed-architecture), where the {VARS.WARP_AUTOMATION_PLATFORM} orchestrates the agent and your worker provides the compute. **Prefer a CLI-only path with no Docker requirement?** Jump to the [Unmanaged quickstart](/platform/self-hosting/unmanaged/#unmanaged-quickstart) to run `oz agent run` directly on any host. +This quickstart sets up the [managed architecture](/factories/self-hosting/#managed-architecture), where the {VARS.WARP_AUTOMATION_PLATFORM} orchestrates the agent and your worker provides the compute. **Prefer a CLI-only path with no Docker requirement?** Jump to the [Unmanaged quickstart](/platform/unmanaged-execution/#unmanaged-quickstart) to run `oz agent run` directly on any host. ::: --- @@ -20,8 +20,8 @@ This quickstart sets up the [managed architecture](/platform/self-hosting/#manag * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. -* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow. -* **The {VARS.WARP_AGENT_CLI}** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). +* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. +* **The {VARS.WARP_AGENT_CLI}** (for routing a test run) — See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli). --- @@ -63,6 +63,8 @@ oz agent run-cloud --prompt "List the files in the current directory" --host "my **Expected outcome:** The {VARS.WARP_AUTOMATION_PLATFORM} accepts the task, routes it to your worker, and the worker spawns a Docker container to execute the agent. You'll see the run appear in the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a> with status moving from `QUEUED` → `INPROGRESS` → `SUCCEEDED`. +This test verifies that the worker is connected. To route factory work to it, set `workerHost` and a platform-matched runner in the [factory definition](/factories/factory-as-code/#routing-to-a-self-hosted-worker). + ### 4. Verify the run Open the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>, find the new task, and confirm the session transcript shows the agent running against your worker. You can attach to the session at any time via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer it. @@ -71,22 +73,10 @@ Open the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>, find the new task, and ## Next steps -* [Unmanaged quickstart](/platform/self-hosting/unmanaged/#unmanaged-quickstart) — ~5-minute CLI-only path: run `oz agent run` in your CI, Kubernetes pod, or dev box with no worker daemon and no Docker requirement. -* [Managed: Docker](/platform/self-hosting/managed-docker/) — Full Docker backend setup, including private registries, volume mounts, and runtime configuration. +* [Unmanaged quickstart](/platform/unmanaged-execution/#unmanaged-quickstart) — ~5-minute CLI-only path: run `oz agent run` in your CI, Kubernetes pod, or dev box with no worker daemon and no Docker requirement. +* [Managed: Docker](/factories/self-hosting/managed-docker/) — Full Docker backend setup, including private registries, volume mounts, and runtime configuration. * [Environments](/platform/environments/) — Define a repository, Docker image, and setup commands so agents have a reproducible workspace for every run. -* [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to route tasks from schedules, integrations (Slack, Linear), the API, and the {VARS.WEB_APP}. -* [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Deploy workers into a Kubernetes cluster with Helm. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — All CLI flags and config file options. - -## Troubleshooting - -**Worker won't start**\ -Verify Docker is running (`docker info`) and that the daemon platform is `linux/amd64` or `linux/arm64`. Musl-based (Alpine) worker hosts are not supported. - -**Worker won't connect**\ -Verify your API key has team scope. Ensure the machine has outbound internet access to `oz.warp.dev:443`. Increase log verbosity with `--log-level debug` to see connection details. - -**Task stays queued and never runs**\ -Confirm the `--host` value you passed to `oz agent run-cloud` matches your `--worker-id` exactly (case-sensitive). Check that the worker's team matches the team creating the task. - -For more, see [Troubleshooting](/platform/self-hosting/troubleshooting/). +* [Factory definition](/factories/factory-as-code/#agentdefaultsworkerhost) — Route factory work to a compatible worker and runner. +* [CLI reference](/agents/cli/oz-cli/) — Route standalone cloud agents to the worker with `--host`. +* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Deploy workers into a Kubernetes cluster with Helm. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — All CLI flags and config file options. diff --git a/src/content/docs/platform/self-hosting/reference.mdx b/src/content/docs/factories/self-hosting/reference.mdx similarity index 82% rename from src/content/docs/platform/self-hosting/reference.mdx rename to src/content/docs/factories/self-hosting/reference.mdx index c5ced7a2d..075ecf499 100644 --- a/src/content/docs/platform/self-hosting/reference.mdx +++ b/src/content/docs/factories/self-hosting/reference.mdx @@ -5,10 +5,10 @@ description: >- file schema for the Docker, Kubernetes, and Direct backends. --- -Reference for the `oz-agent-worker` daemon: CLI flags and the full YAML config-file schema for all three [managed backends](/platform/self-hosting/#managed-architecture) — Docker, Kubernetes, and Direct. For installation instructions, see [Install and run the worker](/platform/self-hosting/managed-docker/#install-and-run-the-worker). +Reference for the `oz-agent-worker` daemon: CLI flags and the full YAML config-file schema for all three [managed backends](/factories/self-hosting/#managed-architecture) — Docker, Kubernetes, and Direct. For installation instructions, see [Install and run the worker](/factories/self-hosting/managed-docker/#install-and-run-the-worker). :::note -This page documents every flag and config option. For installation and backend-specific setup walkthroughs, see [Managed: Docker](/platform/self-hosting/managed-docker/), [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/), or [Managed: Direct](/platform/self-hosting/managed-direct/). This reference applies to the managed architecture only; the [unmanaged architecture](/platform/self-hosting/unmanaged/) uses `oz agent run` instead. +This page documents every flag and config option. For installation and backend-specific setup walkthroughs, see [Managed: Docker](/factories/self-hosting/managed-docker/), [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/), or [Managed: Direct](/factories/self-hosting/managed-direct/). This reference applies to the managed architecture only; the [unmanaged architecture](/platform/unmanaged-execution/) uses `oz agent run` instead. ::: --- @@ -25,7 +25,7 @@ The following flags are available when starting the worker. ### Optional * `--config-file` — Path to a YAML [config file](#config-file). CLI flags take precedence over config file values. -* `--backend` — Backend type: `docker` (default), `kubernetes`, or `direct`. See [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) and [Managed: Direct](/platform/self-hosting/managed-direct/) for backend-specific setup. +* `--backend` — Backend type: `docker` (default), `kubernetes`, or `direct`. See [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) and [Managed: Direct](/factories/self-hosting/managed-direct/) for backend-specific setup. * `--log-level` — Log verbosity. One of `debug`, `info`, `warn`, `error`. Defaults to `info`. * `--no-cleanup` — Keep task containers, Kubernetes Jobs, or workspace directories after execution instead of removing them. Useful for debugging failed tasks. * `-v` / `--volumes` — Mount host directories into task containers (Docker backend only). Format: `HOST_PATH:CONTAINER_PATH` or `HOST_PATH:CONTAINER_PATH:MODE` (where MODE is `ro` or `rw`). Can be specified multiple times. @@ -185,22 +185,22 @@ The worker exports metrics over OpenTelemetry when configured. Exporter selectio * `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP collector endpoint (e.g., `http://otel-collector.observability.svc:4318`). * `OTEL_EXPORTER_OTLP_PROTOCOL` — OTLP protocol: `http/protobuf` (default) or `grpc`. -When deploying with the Helm chart, use the `metrics.*` values instead of setting these variables manually. See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide, metric catalog, Helm values, and sample PromQL queries. +When deploying with the Helm chart, use the `metrics.*` values instead of setting these variables manually. See [Monitoring](/factories/self-hosting/monitoring/) for the full setup guide, metric catalog, Helm values, and sample PromQL queries. --- -## Routing runs to self-hosted workers +## Routing work to self-hosted workers -Once a worker is running, route cloud agent runs to it with the `--host` flag or its equivalents. See [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) for examples across the CLI, schedules, integrations, the API, and the web UI. +To route factory work to a worker, set `workerHost` and a compatible runner in the [factory definition](/factories/factory-as-code/#agentdefaultsworkerhost). To route a standalone cloud agent to the worker with `--host`, see the [CLI reference](/agents/cli/oz-cli/). --- ## Related pages -* [Managed: Docker](/platform/self-hosting/managed-docker/) — Docker backend setup, connectivity, and private registries. -* [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Kubernetes backend setup, Helm chart, pod template, and operational notes. -* [Managed: Direct](/platform/self-hosting/managed-direct/) — Direct backend setup and workspace model. -* [Self-hosting overview](/platform/self-hosting/) — Architecture, decision guide, and Enterprise requirements. +* [Managed: Docker](/factories/self-hosting/managed-docker/) — Docker backend setup, connectivity, and private registries. +* [Managed: Kubernetes](/factories/self-hosting/managed-kubernetes/) — Kubernetes backend setup, Helm chart, pod template, and operational notes. +* [Managed: Direct](/factories/self-hosting/managed-direct/) — Direct backend setup and workspace model. +* [Self-hosting overview](/factories/self-hosting/) — Architecture, decision guide, and Enterprise requirements. * [Environments](/platform/environments/) — Define the Docker image, repos, and setup commands used by task containers. -* [Monitoring](/platform/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. -* [Troubleshooting](/platform/self-hosting/troubleshooting/) — Worker and task failure diagnostics. +* [Monitoring](/factories/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. +* [Troubleshooting](/factories/self-hosting/troubleshooting/) — Worker and task failure diagnostics. diff --git a/src/content/docs/platform/self-hosting/troubleshooting.mdx b/src/content/docs/factories/self-hosting/troubleshooting.mdx similarity index 86% rename from src/content/docs/platform/self-hosting/troubleshooting.mdx rename to src/content/docs/factories/self-hosting/troubleshooting.mdx index 2a53f2b64..e19638b85 100644 --- a/src/content/docs/platform/self-hosting/troubleshooting.mdx +++ b/src/content/docs/factories/self-hosting/troubleshooting.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Diagnostic guides for the `oz-agent-worker` daemon and its task execution. Use this page when a worker won't start, won't connect, tasks stay queued, or tasks fail. :::note -The steps below apply to the [managed architecture](/platform/self-hosting/#managed-architecture) (`oz-agent-worker` daemon). For [unmanaged](/platform/self-hosting/unmanaged/) deployments, refer to the documentation for the environment running `oz agent run` (e.g., GitHub Actions, Kubernetes). +The steps below apply to the [managed architecture](/factories/self-hosting/#managed-architecture) (`oz-agent-worker` daemon). For [unmanaged](/platform/unmanaged-execution/) deployments, refer to the documentation for the environment running `oz agent run` (e.g., GitHub Actions, Kubernetes). ::: --- @@ -46,7 +46,7 @@ The steps below apply to the [managed architecture](/platform/self-hosting/#mana **Fix:** -1. Install the {VARS.WARP_AGENT_CLI} on the worker host. See [Installing the CLI](/reference/cli/#installing-the-cli). +1. Install the {VARS.WARP_AGENT_CLI} on the worker host. See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli). 2. If the CLI isn't on `PATH`, set `oz_path` in the config file to the absolute path of the `oz` binary. --- @@ -63,7 +63,7 @@ The steps below apply to the [managed architecture](/platform/self-hosting/#mana 4. Check that no firewall rules are blocking WebSocket connections to `wss://oz.warp.dev`. 5. Increase log verbosity with `--log-level debug` to see connection details. -See [Security and networking](/platform/self-hosting/security-and-networking/#network-requirements) for the full list of outbound endpoints the worker needs. +See [Security and networking](/platform/execution-security/#network-requirements) for the full list of outbound endpoints the worker needs. --- @@ -93,7 +93,7 @@ See [Security and networking](/platform/self-hosting/security-and-networking/#ne 6. If using `metrics.podMonitor.create=true`, verify the `monitoring.coreos.com` CRDs are installed in the cluster. The `PodMonitor` resource requires the Prometheus Operator. 7. Restart the worker with `--log-level debug` and look for metrics-related error messages at startup. -See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide. +See [Monitoring](/factories/self-hosting/monitoring/) for the full setup guide. --- @@ -133,7 +133,7 @@ See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide. ### Docker backend (image pull) -1. If using a private registry, ensure Docker credentials are available to the worker. See [Private Docker registries](/platform/self-hosting/managed-docker/#private-docker-registries). +1. If using a private registry, ensure Docker credentials are available to the worker. See [Private Docker registries](/factories/self-hosting/managed-docker/#private-docker-registries). 2. Try pulling the image manually on the worker host: `docker pull <image>`. ### Kubernetes backend (image pull) @@ -150,7 +150,7 @@ See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide. ## Related pages -* [Self-hosting overview](/platform/self-hosting/) — Architecture and decision guide. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config schema, including every flag mentioned here. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Outbound endpoints the worker needs. +* [Self-hosting overview](/factories/self-hosting/) — Architecture and decision guide. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags and config schema, including every flag mentioned here. +* [Security and networking](/platform/execution-security/) — Outbound endpoints the worker needs. * [Agent Session Sharing](/agents/local-agents/session-sharing/) — Attach to running tasks to debug interactively. diff --git a/src/content/docs/platform/warp-hosting.mdx b/src/content/docs/factories/warp-hosting.mdx similarity index 51% rename from src/content/docs/platform/warp-hosting.mdx rename to src/content/docs/factories/warp-hosting.mdx index 3b7ee8010..29d3b3dfe 100644 --- a/src/content/docs/platform/warp-hosting.mdx +++ b/src/content/docs/factories/warp-hosting.mdx @@ -1,15 +1,16 @@ --- -title: Warp-hosted agents +title: Warp-hosted execution for Warp Factories description: >- - Run cloud agents on Warp's infrastructure. Warp handles scaling, isolation, and performance for agent execution. + Run factory work on Warp-hosted infrastructure, with managed compute, + isolation, networking, and capacity. sidebar: - label: "Warp-hosted agents" + label: "Warp-hosted execution" --- import { VARS } from '@data/vars'; -Warp's managed infrastructure lets your team run cloud agent workloads in fast, secure sandboxes. +Warp-hosted execution runs factory work in managed sandboxes. Warp provisions the compute while your factory definition selects each agent's runner, repositories, setup, and credentials. -Use Warp-hosted agents to quickly get started with the {VARS.WARP_AUTOMATION_PLATFORM}, without needing to configure compute resources or maintain services. +Use it when your factory's repositories and services are reachable from the public internet and your team does not need to manage worker capacity or host maintenance. For private services or a network boundary that must contain checkout and execution, use [managed self-hosting](/factories/self-hosting/). ## Sandbox environment @@ -17,7 +18,7 @@ All Warp-hosted agents run in fully-isolated sandboxes. Warp uses a mix of infra ### OS and architecture -Warp-hosted agents use the container image specified in your [environment](/platform/environments/). +Warp-hosted factory agents use the runner and workspace configuration in your [factory definition](/factories/factory-as-code/). A factory can also use an existing [environment](/platform/environments/) when its definition specifies one. They are compatible with any Linux x86-64 image that includes a `bash` shell and core utilities like `ls` and `mkdir`. ### Resources @@ -51,5 +52,6 @@ Warp's hosted agents have network egress enabled by default. Outgoing requests m ## Related pages -* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) - Learn how Warp-hosted agents fit into the {VARS.WARP_AUTOMATION_PLATFORM}. -* [Self-hosting](/platform/self-hosting/) - Run agents on infrastructure you manage when execution must stay inside your network. +* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) - Configure the shared cloud-agent primitives behind a factory. +* [Factory runners](/factories/runners/) - Choose the operating system, architecture, and instance shape for factory work. +* [Managed self-hosting](/factories/self-hosting/) - Run factory work on infrastructure you manage when execution must stay inside your network. diff --git a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx index 6287a6f7d..af83db49c 100644 --- a/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-triage-agent.mdx @@ -18,7 +18,7 @@ Learn how to use the {VARS.WARP_AUTOMATION_PLATFORM} to build a triage agent tha * A Warp account ([sign up at warp.dev](https://www.warp.dev)) * A GitHub repository with Issues enabled * A cloud environment with access to your repository ([create one](/platform/environments/configuring-environments/#create-an-environment-with-guided-setup)) -* A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/reference/cli/api-keys/#from-the-web-app-recommended)) +* A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/agents/cli/oz-cli/api-keys/#from-the-web-app-recommended)) ## 1. Define your triage criteria @@ -71,7 +71,7 @@ oz agent run \ The `--share` flag generates a session link your team can use to inspect what the agent did. Review the session output to confirm that the labels and comments are what you expect. If something is wrong, refine the skill file and run again. -For the full reference of `oz agent run` flags, see the [{VARS.WARP_AGENT_CLI} reference](/reference/cli/). +For the full reference of `oz agent run` flags, see the [{VARS.WARP_AGENT_CLI} reference](/agents/cli/oz-cli/). ## 4. Deploy with GitHub Actions diff --git a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx index a7a3ff042..0a70e0ddf 100644 --- a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx @@ -17,7 +17,7 @@ Use multiple coding agents, including Warp Agent, Claude Code, Codex, and other * **Local parallel sessions** - run Warp Agent, Claude Code, Codex, OpenCode, or another CLI agent in separate tabs or panes. * **Isolated worktrees** - give each agent its own Git worktree and branch so parallel edits do not collide. -* **{VARS.WARP_AUTOMATION_PLATFORM} cloud orchestration** - use `/orchestrate`, `/plan`, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.API_SDK_NAME} to fan work out to child agents in cloud environments. +* **{VARS.WARP_AUTOMATION_PLATFORM} cloud orchestration** - use `/orchestrate`, `/plan`, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.WARP_PLATFORM_API} to fan work out to child agents in cloud environments. The best multi-agent workflows have one thing in common: each agent owns a clear slice of work, reports back with validation results, and hands off a branch, diff, PR, or concise finding you can review. @@ -217,7 +217,7 @@ Use cloud agents when the work is long-running, resource-intensive, easy to shar ``` 2. Use `/plan` for larger changes where you want to review the plan, orchestration config, child ownership, and merge strategy before agents launch. -3. For repeatable or unattended workflows, start the parent from the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.API_SDK_NAME}. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) for launch options. +3. For repeatable or unattended workflows, start the parent from the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.WARP_PLATFORM_API}. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) for launch options. 4. Inspect parent and child runs from the [{VARS.WEB_APP}](/platform/oz-web-app/) or the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app. Cloud orchestration is the best fit when you need: @@ -255,7 +255,7 @@ Explore related guides and features: * [How to review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/) — review and refine the code your agents produced * [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) — give reviewers the agent context behind a PR * [Multi-agent orchestration](/platform/orchestration/) — coordinate parent and child agents across local and cloud runs -* [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) — start orchestrated runs from Warp, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.API_SDK_NAME} +* [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) — start orchestrated runs from Warp, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.WARP_PLATFORM_API} * [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) — install both agents if you haven't already * [Claude Code in Warp](https://www.warp.dev/agents/claude-code) — overview of Claude Code support in Warp * [Codex in Warp](https://www.warp.dev/agents/codex) — overview of Codex support in Warp diff --git a/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx index 55234b5f7..3cddbfada 100644 --- a/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx @@ -28,8 +28,8 @@ Use this table to decide where an unattended agent should start. | Linear | An issue, comment, or assignment should start the agent. | [Linear integration](/platform/integrations/linear/) | Linear issue updates, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and the shared run session | | GitHub | Someone should delegate work by mentioning `@warp-agent` on an issue, pull request, or review comment. | [GitHub integration](/platform/integrations/github/) | GitHub thread comments, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and the shared run session | | GitHub Actions | A repository event, PR workflow, issue workflow, or CI failure should start the agent. | [GitHub Actions](/platform/integrations/github-actions/) | GitHub Actions logs, PR or issue comments, {VARS.WEB_APP}, and cloud agent runs | -| {VARS.WARP_AGENT_CLI} | You want to start a named cloud run from a terminal, script, or local automation. | [{VARS.WARP_AGENT_CLI}](/reference/cli/#running-agents-remotely-oz-agent-run-cloud) | CLI output, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and cloud agent session links | -| {VARS.API_SDK_NAME} | Your internal system should create, query, or monitor runs programmatically. | [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) | Your system, API results, {VARS.WEB_APP}, and run sessions | +| {VARS.WARP_AGENT_CLI} | You want to start a named cloud run from a terminal, script, or local automation. | [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/#running-agents-remotely-oz-agent-run-cloud) | CLI output, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and cloud agent session links | +| {VARS.WARP_PLATFORM_API} | Your internal system should create, query, or monitor runs programmatically. | [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) | Your system, API results, {VARS.WEB_APP}, and run sessions | ## Choose a workflow pattern @@ -82,7 +82,7 @@ The GitHub Action can pass event data, prior step output, and repository context ### Start runs from scripts or internal systems -Use the [{VARS.WARP_AGENT_CLI}](/reference/cli/#running-agents-remotely-oz-agent-run-cloud) for scripts and terminal workflows. Use the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) when another service should create or monitor runs. This is useful for: +Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/#running-agents-remotely-oz-agent-run-cloud) for scripts and terminal workflows. Use the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) when another service should create or monitor runs. This is useful for: * internal dashboards * custom webhooks @@ -112,7 +112,7 @@ Unattended does not mean invisible. Use these surfaces to review what happened: * [{VARS.WEB_APP}](/platform/oz-web-app/) - View runs, schedules, run metadata, and session transcripts from a browser or mobile device. * [Managing cloud agents](/platform/managing-cloud-agents/) - Filter runs by source, status, day, creator, or trigger. * [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) - Inspect the prompt, plan, commands, logs, output, and follow-up messages where available. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - Query runs and build internal monitoring around status, runtime, or outcomes. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - Query runs and build internal monitoring around status, runtime, or outcomes. When a run creates a PR, include the cloud run link in the PR description or a comment. See [Attach agent session context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs/) for a template. diff --git a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx index 6167264f4..28cbe86a2 100644 --- a/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx +++ b/src/content/docs/guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx @@ -31,7 +31,7 @@ The practical difference: * **Team visibility** — Any teammate can open a run in the {VARS.WEB_APP} to inspect the session transcript, steer a stuck agent, or pick up where the agent left off. * **Scale without contention** — Multiple triage runs can execute in parallel without fighting over a shared dev box, local git checkouts, or CPU. -See [Deployment patterns](/platform/deployment-patterns) for a full comparison of {VARS.WARP_AUTOMATION_PLATFORM}-hosted, CLI-based, and self-hosted execution patterns. +See [Deployment patterns](/factories/deployment-patterns) for a full comparison of {VARS.WARP_AUTOMATION_PLATFORM}-hosted, CLI-based, and self-hosted execution patterns. ## 1. Set up a cloud environment @@ -67,7 +67,7 @@ With GitHub Actions, your factory already has event-based triggers. The {VARS.WA * **Slack** — Teammates can kick off a run by mentioning `@warp` in a Slack thread. Useful for one-off requests that don't need the full label workflow. See [Slack integration](/platform/integrations/slack). * **Linear** — When an issue in Linear reaches a specific status, a cloud agent run starts automatically. Useful for teams that track work in Linear rather than GitHub Issues. See [Linear integration](/platform/integrations/linear). * **Scheduled agents** — For the outer improvement loop (which runs on a cadence rather than an event), use a scheduled cloud agent. See [Scheduled agents](/platform/triggers/scheduled-agents). -* **{VARS.API_SDK_NAME}** — For custom triggers — webhooks, internal dashboards, other events — use the [{VARS.API_SDK_NAME}](/reference/api-and-sdk) to start runs programmatically. +* **{VARS.WARP_PLATFORM_API}** — For custom triggers — webhooks, internal dashboards, other events — use the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk) to start runs programmatically. ## 4. Monitor factory runs @@ -100,5 +100,5 @@ See [Multi-agent orchestration](/platform/orchestration) for fan-out, sharding, * [Infrastructure and security](/factories/infrastructure-and-security/) — The environment, runner, and credential model behind the concerns you configured by hand here. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop on a schedule. * [Environments](/platform/environments) — Full reference for cloud agent environments. -* [Deployment patterns](/platform/deployment-patterns) — Choose the right architecture for your team. -* [Self-hosting](/platform/self-hosting) — Run cloud agent workers on your own infrastructure when code must stay on-premises. +* [Deployment patterns](/factories/deployment-patterns) — Choose the right architecture for your team. +* [Self-hosting](/factories/self-hosting) — Run cloud agent workers on your own infrastructure when code must stay on-premises. diff --git a/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx b/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx index b2eaa33d0..c54df95a2 100644 --- a/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx +++ b/src/content/docs/guides/external-tools/build-a-mattermost-bot-for-warp-factories.mdx @@ -8,14 +8,14 @@ sidebar: --- import { VARS } from '@data/vars'; -Build a Mattermost bot that sends work to a [Warp factory](/factories/) and posts progress back into the thread where it started, the same experience Warp's own [Slack integration](/factories/integrations/slack/) gives teams that use Slack. Warp doesn't ship a Mattermost integration directly, so this guide uses the [factory API](/factories/factory-api/) to build the equivalent yourself. It takes about 20 minutes if you already have a Mattermost bot account and a factory set up. +Build a Mattermost bot that sends work to a [Warp factory](/factories/) and posts progress back into the thread where it started, the same experience Warp's own [Slack integration](/factories/integrations/slack/) gives teams that use Slack. Warp doesn't ship a Mattermost integration directly, so this guide uses [factory endpoints](/factories/factory-api/) to build the equivalent yourself. It takes about 20 minutes if you already have a Mattermost bot account and a factory set up. ## Prerequisites * **A Warp Factories factory** - [Set up a factory](/factories/quickstart/) before starting; this guide dispatches work to an existing factory rather than creating one. -* **A Warp API key** - Create an [agent API key](/reference/cli/api-keys/#personal-vs-agent-keys) rather than a personal key, so the bot's requests aren't tied to your individual account. +* **A Warp API key** - Create an [agent API key](/agents/cli/oz-cli/api-keys/#personal-vs-agent-keys) rather than a personal key, so the bot's requests aren't tied to your individual account. * **A Mattermost bot account and access token** - Create one from your Mattermost System Console under **Integrations** > **Bot Accounts**, and generate a personal access token for it. Mattermost's own [bot accounts documentation](https://developers.mattermost.com/integrate/reference/bot-accounts/) covers the exact steps, since they vary by Mattermost version and hosting setup. -* **The {VARS.API_SDK_NAME} Python SDK** - Install it with `pip install oz-agent-sdk`. If you're working in another language, the [factory API page](/factories/factory-api/) shows the equivalent REST calls. +* **The {VARS.WARP_PLATFORM_API} Python SDK** - Install it with `pip install oz-agent-sdk`. If you're working in another language, [factory endpoints](/factories/factory-api/) show the equivalent REST calls. ## 1. Store your credentials @@ -28,7 +28,7 @@ export MATTERMOST_WEBHOOK_TOKEN=YOUR_MATTERMOST_WEBHOOK_TOKEN export MATTERMOST_URL=https://YOUR_MATTERMOST_SERVER ``` -The bot uses the Warp API key to call the factory API, the bot token to post replies back into the channel, and the webhook token to confirm each inbound request actually came from Mattermost. +The bot uses the Warp API key to call factory endpoints, the bot token to post replies back into the channel, and the webhook token to confirm each inbound request actually came from Mattermost. ## 2. Create an outgoing webhook in Mattermost @@ -167,6 +167,6 @@ Call `check_and_report` from a scheduled job (a cron-triggered script, or a ligh You've built a Mattermost bot that discovers a factory by name, dispatches tasks with source context attached, and routes replies to the run that's already in progress. From here: -* [Use the factory API](/factories/factory-api/) - The full discover-and-dispatch reference this guide builds on. +* [Use factory endpoints](/factories/factory-api/) - The full discover-and-dispatch reference this guide builds on. * [Connect your factory](/factories/connect-your-factory/) - Compare this custom integration against Warp's built-in intake sources. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - Full endpoint reference for run status, follow-ups, and cancellation. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - Full endpoint reference for run status, follow-ups, and cancellation. diff --git a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx index 44546dac6..818a9132a 100644 --- a/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx +++ b/src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx @@ -30,7 +30,7 @@ Use this guide to choose the right setup path, then jump to the source docs for | Local Warp agent | You are working interactively in Warp and want the agent to use tools from your machine or desktop-authenticated services. | Warp MCP settings, Warp Drive MCP servers, `.warp/.mcp.json`, or provider config files. | [Model Context Protocol (MCP)](/agents/capabilities/mcp/) | | Third-party CLI agent in Warp | You run Claude Code, Codex, OpenCode, or another CLI agent in Warp and want shared MCP config across tools. | File-based MCP config that Warp can detect and approve. | [File-based MCP servers](/agents/capabilities/mcp/#file-based-mcp-servers) | | Cloud agent run | The agent runs in a cloud environment from Slack, Linear, schedules, GitHub Actions, the CLI, or the API. | `--mcp`, an agent config file, or a Warp-shared MCP UUID. | [MCP Servers for cloud agents](/platform/mcp/) | -| Repeatable automation | You need the same MCP tools every time a scheduled agent, integration, or CI workflow runs. | Agent config files plus [Agent Secrets](/platform/secrets/) for credentials. | [MCP servers (CLI reference)](/reference/cli/mcp-servers/) | +| Repeatable automation | You need the same MCP tools every time a scheduled agent, integration, or CI workflow runs. | Agent config files plus [Agent Secrets](/platform/secrets/) for credentials. | [MCP servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) | ## Common MCP workflows @@ -80,7 +80,7 @@ Then pass the UUID to an agent run: oz agent run-cloud --mcp "<MCP_SERVER_UUID>" --prompt "Summarize the latest production incidents" ``` -See [MCP servers (CLI reference)](/reference/cli/mcp-servers/) for all `--mcp` formats. +See [MCP servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) for all `--mcp` formats. ## Local MCP setup paths @@ -136,5 +136,5 @@ Before giving an agent tool access through MCP: * [Model Context Protocol (MCP)](/agents/capabilities/mcp/) - Configure MCP servers for local agents in the Warp app. * [MCP Servers for cloud agents](/platform/mcp/) - Configure MCP servers for cloud runs and automation. -* [MCP servers (CLI reference)](/reference/cli/mcp-servers/) - Use `--mcp` with UUIDs, inline JSON, or files. +* [MCP servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) - Use `--mcp` with UUIDs, inline JSON, or files. * [Agent Secrets](/platform/secrets/) - Store credentials for cloud agent runs. \ No newline at end of file diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 8565714d8..877aeead4 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,129 +1,49 @@ --- -title: Getting started with Warp +title: Warp products description: >- - Get started with Warp, the Agentic Development Environment, and the - {{WARP_AUTOMATION_PLATFORM}}, which orchestrates cloud agents at scale. + Warp combines a modern terminal, coding agents, cloud automation, and + software factories for teams that build and ship software. sidebar: - label: Getting started with Warp + label: Warp products --- import { VARS } from '@data/vars'; -import VideoEmbed from '@components/VideoEmbed.astro'; -Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that combines a modern, high-performance terminal with powerful agents to help you build, test, deploy, and debug code. Agents in Warp are powered by the **{VARS.WARP_AUTOMATION_PLATFORM}**, which orchestrates agents locally or in the cloud at scale. - -<figure> -![Two panels side by side: Warp, a modern terminal built for coding with agents, and Warp Factories, open infrastructure for building cloud software factories](../../assets/terminal/warp-factories-welcome.png) -<figcaption>Warp and Warp Factories in the Agentic Development Environment.</figcaption> -</figure> - ---- +Warp is an [open-source](https://github.com/warpdotdev/warp) **Agentic Development Environment** that brings together terminal work, coding agents, and cloud automation. With Warp, you can work in a desktop terminal, use the Warp Agent in a local checkout or from any terminal, automate background work in the cloud, and run repeatable team workflows with Warp Factories. ## Warp -Warp is where you work — a fast, modern terminal built for coding with agents. - -**Key capabilities:** - -* [**Terminal and Agent modes**](/agents/local-agents/interacting-with-agents/terminal-and-agent-modes/): Switch between a clean terminal for commands and a dedicated conversation view for multi-turn agent workflows. -* [**Modern terminal UX**](/terminal/editor/): Cursor movement, block-based navigation, multi-line editing, syntax highlighting, and rich completions. Built with Rust for high performance. -* [**Code editor**](/code/overview/): File tree, code editor with LSP support, and interactive code review experience. -* [**Third-party CLI agents**](/agents/cli-agents/overview/): Run third-party CLI agents like Claude Code, Codex, and OpenCode with the agent toolbelt — rich input, code review, notifications, and more. - -<VideoEmbed url="https://www.youtube.com/watch?v=xhkoXsE9Wqc" title="Deep dive into Warp's core features" /> - ---- - -## Three ways to use the Warp Agent - -The **Warp Agent** writes and edits code, debugs issues, runs commands, and works through multi-step tasks. You reach the same agent three ways, and your account, rules, skills, and model access carry across all of them. - -### In the Warp app - -Real-time, interactive coding assistance alongside your terminal. - -* Write and refactor code across your codebase -* Debug issues and fix errors -* Run commands and interpret results -* Plan and execute multi-step tasks - -You stay in control. Review changes, steer the agent mid-task, and approve actions before they execute. - -→ [Get started with agents in Warp](/agents/) - -### In any terminal, with the Warp Agent CLI - -The Warp Agent CLI is a standalone terminal program that runs the same agent without the Warp app. Run the `warp` command to start a conversation in whichever terminal you already use, over SSH, or on a machine where Warp isn't installed. - -→ [Get started with the Warp Agent CLI](/agents/cli/quickstart/) - -### In the cloud, as a cloud agent - -Cloud agents run in the background on Warp's infrastructure (or your own) for automation at scale. - -* **Triggers**: React to events from Slack, Linear, GitHub, or custom webhooks -* **Schedules**: Run recurring tasks like dependency updates or dead code removal -* **Parallelism**: Run many agents concurrently across repos or tasks -* **Observability**: Every run is tracked, auditable, and shareable with your team +With the Warp desktop terminal, you can run commands, edit code, and work with agents in a local checkout. -Cloud agents are ideal for work that doesn't need your immediate attention, like PR reviews, issue triage, routine maintenance, and integration-driven workflows. +* [Modern terminal editing](/terminal/editor/) - Edit commands, navigate blocks, manage tabs, and customize your terminal. +* [Code](/code/overview/) - Review agent changes and edit files alongside your terminal. +* [Agents](/agents/) - Start and steer coding agents in the Warp app. -→ [Learn about cloud agents](/platform/) +## Warp Agent -### The platform behind them +The Warp Agent helps you investigate issues, edit code, run commands, and complete multi-step work. Use it in the Warp terminal or from the [Warp Agent CLI](/agents/cli/), which runs the same agent in any terminal. -The **{VARS.WARP_AUTOMATION_PLATFORM}** is Warp's programmable system for running and coordinating agents at scale. It provides the environments, triggers, integrations, orchestration, and observability that cloud agents run on, plus a CLI, API, and SDK. +## {VARS.WARP_AUTOMATION_PLATFORM} -→ [Learn about the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) +The {VARS.WARP_AUTOMATION_PLATFORM} runs cloud agents from triggers, schedules, integrations, and APIs. Use it for background work such as issue triage, pull request review, and recurring maintenance. ---- - -## Repeatable development workflows with Warp Factories - -A single cloud agent handles one task. **Warp Factories**, now in Early Access, lets your team run a software factory: a repeatable process where cloud agents triage, spec, implement, review, and verify work, and humans approve key decisions. - -→ [Learn about Warp Factories](/factories/) or [request access](https://www.warp.dev/factories/request-access) - ---- +* [Cloud agents](/platform/) - Run background agent work in the cloud. +* [The {VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) - Configure environments, integrations, orchestration, and shared agent settings. -## How they work together +## Warp Factories -Warp and the {VARS.WARP_AUTOMATION_PLATFORM} provide a unified experience across local and cloud development: +Warp Factories is available in Early Access. A factory turns incoming engineering work into a repeatable, multi-stage workflow with specialized agents, review points, and measurable outcomes. -* **Same agent, anywhere**: Whether you're working in the Warp app, in another terminal through the Warp Agent CLI, or running agents in the cloud, you're using the same underlying agent capabilities. -* **Seamless handoff**: Start a task in the cloud and take over locally in Warp when you want hands-on control, without losing progress or context. -* **Shared context**: [Warp Drive](/knowledge-and-collaboration/warp-drive/), [Rules](/agents/capabilities/rules/), and [MCP servers](/agents/capabilities/mcp/) work across both local and cloud agents, so your team's knowledge and tools are always available. -* **Team collaboration**: Share agent sessions, review agents' actions, and steer running tasks, regardless of who started them. +* [Warp Factories overview](/factories/) - Learn how a factory receives, routes, and tracks work. +* [Factory quickstart](/factories/quickstart/) - Create a factory and send it its first work item. ---- - -## Multi-model support - -The {VARS.WARP_AUTOMATION_PLATFORM} is multi-model by design. You can [choose your preferred LLM](/agents/inference/model-choice/) from a curated set of top models. - ---- +## How the products work together -## Open source - -Warp's client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE-AGPL). The source lives at [`warpdotdev/warp`](https://github.com/warpdotdev/warp), where you can read the code, file issues, and contribute alongside the Warp team. Development happens in the open with an agent-first workflow managed by the {VARS.WARP_AUTOMATION_PLATFORM}. - -→ [Contributing to Warp](/support-and-community/community/contributing/) explains how to file issues, claim work, and ship code or themes. - ---- - -## Privacy and security - -Warp is **SOC 2 compliant** and has **Zero Data Retention** policies with all contracted LLM providers. No customer AI data is retained, stored, or used for training. - -Warp's AI features can be globally disabled in **Settings** > **Agents** > **Warp Agent**. - -→ [Read more about data privacy](https://www.warp.dev/privacy) - ---- +Start and steer interactive work in the Warp terminal with the Warp Agent. For work that starts from a schedule, integration, or API, the {VARS.WARP_AUTOMATION_PLATFORM} runs agents in the cloud. Warp Factories builds on the {VARS.WARP_AUTOMATION_PLATFORM} to turn incoming team work into a repeatable workflow with specialized agents and review stages. -## Next steps +## Related pages -* [**Quickstart**](/quickstart/): Get Warp installed and start coding -* [**Agents overview**](/agents/): What the Warp Agent does, how to control it, and where to run it -* [**Warp Agent CLI**](/agents/cli/): Run the Warp Agent in any terminal -* [**Cloud Agents overview**](/platform/): Set up background automation -* [**{VARS.WARP_AUTOMATION_PLATFORM}**](/platform/overview/): Learn about the CLI, API, SDK, and infrastructure +* [Install Warp](/quickstart/) - Set up Warp and start coding. +* [Start an agent conversation](/agents/) - Work with the Warp Agent in a local checkout. +* [Run cloud agents](/platform/quickstart/) - Set up background automation. +* [Set up a factory](/factories/quickstart/) - Route engineering work through Warp Factories. +* [Privacy and security](/support-and-community/privacy-and-security/privacy/) - Review Warp's data handling, privacy, and security practices. diff --git a/src/content/docs/platform/agents.mdx b/src/content/docs/platform/agents.mdx index f0bd0cf38..a6ffb6406 100644 --- a/src/content/docs/platform/agents.mdx +++ b/src/content/docs/platform/agents.mdx @@ -14,22 +14,22 @@ Every team starts with a default cloud agent, which is what runs when an automat ## How cloud agents get triggered -A run executes as a cloud agent when it's authenticated with an [agent API key](/reference/cli/api-keys/) or when an agent is explicitly selected; otherwise it runs as the calling user. The triggers that can run as a cloud agent are: +A run executes as a cloud agent when it's authenticated with an [agent API key](/agents/cli/oz-cli/api-keys/) or when an agent is explicitly selected; otherwise it runs as the calling user. The triggers that can run as a cloud agent are: * **Schedules** — Cron-style recurring runs. See [Scheduled agents](/platform/triggers/scheduled-agents/). * **Integrations** — Slack mentions, Linear issue updates, GitHub Actions workflow steps. See [Integrations](/platform/integrations/). -* **API and SDK** — Programmatic runs from your own backend, scripts, or webhooks via the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). -* **CLI** — `oz agent run-cloud` from a developer machine, CI pipeline, or self-hosted worker. See the [{VARS.WARP_AGENT_CLI}](/reference/cli/). +* **API and SDK** — Programmatic runs from your own backend, scripts, or webhooks via the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/). +* **CLI** — `oz agent run-cloud` from a developer machine, CI pipeline, or self-hosted worker. See the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/). Each run is tracked in the <a href={`${VARS.WEB_APP_URL}/runs`}>{VARS.DASHBOARD}</a> with its trigger source, the environment it ran in, and the full transcript. ## Agent API keys -Most automation triggers authenticate using an **agent API key** — a credential that runs as a cloud agent on your team rather than as an individual user. See [API keys](/reference/cli/api-keys/) for how personal and agent keys differ, and how to create one. +Most automation triggers authenticate using an **agent API key** — a credential that runs as a cloud agent on your team rather than as an individual user. See [API keys](/agents/cli/oz-cli/api-keys/) for how personal and agent keys differ, and how to create one. ## Service accounts -In the CLI and REST API, a cloud agent is represented as a **service account**. `oz whoami` reports `service_account:<uid>` when the CLI is authenticated as a service account, and [`oz federate issue-token`](/reference/cli/federate/) emits the same form in OIDC token subjects. +In the CLI and REST API, a cloud agent is represented as a **service account**. `oz whoami` reports `service_account:<uid>` when the CLI is authenticated as a service account, and [`oz federate issue-token`](/agents/cli/oz-cli/federate/) emits the same form in OIDC token subjects. ## Managing cloud agents @@ -75,8 +75,8 @@ Cloud agents — and individual runs — can also be granted specific capabiliti * [Triggers](/platform/triggers/) - How schedules, integrations, and API calls invoke cloud agents. * [Environments](/platform/environments/) - The runtime context (Docker image, repos, setup commands) a cloud agent uses. * [Multi-agent orchestration](/platform/orchestration/) - Coordinate a parent cloud agent and its children across local and cloud runs. -* [API keys](/reference/cli/api-keys/) - Create personal and agent API keys. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - Programmatic access to the cloud agent endpoints. -* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run. +* [API keys](/agents/cli/oz-cli/api-keys/) - Create personal and agent API keys. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - Programmatic access to the cloud agent endpoints. +* [Federated identity tokens](/agents/cli/oz-cli/federate/) - Issue OIDC tokens from inside a run. * [{VARS.WEB_APP}](/platform/oz-web-app/) - Manage cloud agents and inspect their runs in the web UI. * [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls. diff --git a/src/content/docs/platform/architecture.mdx b/src/content/docs/platform/architecture.mdx index 579efcc4c..a14e8f706 100644 --- a/src/content/docs/platform/architecture.mdx +++ b/src/content/docs/platform/architecture.mdx @@ -6,7 +6,7 @@ description: >- --- import { VARS } from '@data/vars'; -The {VARS.WARP_AUTOMATION_PLATFORM} connects the tools that start agent work with the environments where that work runs. Warp operates the control plane, which coordinates runs and routes inference. Cloud agent runs execute in a Warp-hosted sandbox or on customer infrastructure. [Self-hosted](/platform/self-hosting/) execution and [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) change where specific work happens. +The {VARS.WARP_AUTOMATION_PLATFORM} connects the tools that start agent work with the environments where that work runs. Warp operates the control plane, which coordinates runs and routes inference. Cloud agent runs execute in a Warp-hosted sandbox or on customer infrastructure. [Managed self-hosting](/factories/self-hosting/) and [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) change where specific work happens. ## Stack overview @@ -15,11 +15,11 @@ The platform has five layers: clients, the Warp-operated control plane that coor ![Warp stack overview diagram showing clients, the Warp control plane, the data plane, Warp-hosted and customer-hosted execution planes, and external systems](../../../assets/agent-platform/warp-stack-overview.png) * **Clients** - The surfaces that start and observe work, like the Warp app, the {VARS.WARP_AGENT_CLI}, the web app, the [factory dashboard](/factories/factory-dashboard/), and clients connected through the [Factory MCP](/factories/factory-mcp/). All clients talk to the same control plane APIs. -* **APIs** - The control plane's entry points: the [Agent API and SDKs](/reference/api-and-sdk/), a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. +* **APIs** - The control plane's entry points: the [Warp Platform API and SDKs](/factories/developer-tools/), a webhook receiver for [integration](/platform/integrations/) events, and the hosted Factory MCP endpoint. * **Control plane** - Warp coordinates runs, manages shared configuration, routes model calls, and records run history. * **Data plane** - Run data (transcripts, artifacts, and attachments) lives in Warp-managed storage, independent of where runs execute. -* **Warp-hosted execution** - By default, each cloud agent run gets an isolated sandbox prepared from its environment. See [Warp-hosted execution](/platform/warp-hosting/). -* **Self-hosted execution** - On Enterprise, a managed worker runs tasks on your infrastructure. Unmanaged setups run the {VARS.WARP_AGENT_CLI} in your CI or orchestrator. See [Self-hosting](/platform/self-hosting/). +* **Warp-hosted execution** - By default, each cloud agent run gets an isolated sandbox prepared from its environment. See [Warp-hosted execution](/factories/warp-hosting/). +* **Self-hosted execution** - On Enterprise, a managed worker runs tasks on your infrastructure. Unmanaged setups run the {VARS.WARP_AGENT_CLI} in your CI or orchestrator. See [Managed self-hosting](/factories/self-hosting/) and [unmanaged execution](/platform/unmanaged-execution/). * **External systems** - The platform connects to identity providers, source control, integration providers, model providers, and a payment provider. ## Cloud agent run lifecycle @@ -28,9 +28,9 @@ Every cloud agent run follows the same lifecycle, no matter what started it or w ![Cloud agent run lifecycle diagram showing triggers, the Warp control plane, the execution sandbox with its agent loop, LLM providers, and output targets](../../../assets/agent-platform/cloud-agent-run-lifecycle.png) -1. **A trigger fires** - A [schedule](/platform/triggers/scheduled-agents/), an [integration](/platform/integrations/) event, an [API or SDK](/reference/api-and-sdk/) call, a CLI command, or a [Handoff](/platform/handoff/) from the Warp app starts the run. +1. **A trigger fires** - A [schedule](/platform/triggers/scheduled-agents/), an [integration](/platform/integrations/) event, an [API or SDK](/factories/api-and-sdk/) call, a CLI command, or a [Handoff](/platform/handoff/) from the Warp app starts the run. 2. **The task is created** - The control plane opens a run record that tracks the task's state, inputs, and provenance. -3. **Configuration is resolved** - The platform picks the run's [environment](/platform/environments/), [runner](/platform/runners/), execution host, and [model and harness](/platform/harnesses/). +3. **Configuration is resolved** - The platform picks the run's [environment](/platform/environments/), [runner](/factories/runners/), execution host, and [model and harness](/platform/harnesses/). 4. **The sandbox is provisioned** - The execution host clones the environment's repositories, runs setup commands, and injects only the [secrets](/platform/secrets/) the run is allowed to use. 5. **The agent loop runs** - The harness gathers context, calls the model, and runs tools until the task is done. Tools run in the sandbox. With the Warp Agent, model calls route through Warp to providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr); Claude Code and Codex call their provider directly. 6. **Outputs land at their targets** - The agent pushes branches, opens pull requests, and replies to the Slack thread, Linear issue, or Jira work item that started the task. @@ -54,10 +54,10 @@ Self-hosted execution keeps checkout, commands, and the workspace on your infras ![Self-hosted execution architecture diagram showing the managed worker on customer infrastructure connecting outbound to the Warp control plane, with numbered flow steps](../../../assets/agent-platform/self-hosted-execution-flow.png) -1. **The worker connects** - You run the managed worker (`oz-agent-worker`) on your infrastructure. It authenticates with an agent API key and holds an outbound-only connection, waiting for tasks routed to its [`--host`](/platform/self-hosting/#routing-runs-to-self-hosted-workers) ID. +1. **The worker connects** - You run the managed worker (`oz-agent-worker`) on your infrastructure. It authenticates with an agent API key and holds an outbound-only connection, waiting for tasks routed to its `--host` ID. 2. **Warp assigns the task** - When a trigger targets your worker, the control plane sends the task, its resolved configuration, and scoped runtime credentials over that connection. -3. **The agent runs on your backend** - The worker clones repositories, runs setup, injects allowed [secrets](/platform/secrets/), and executes in a Docker container, a Kubernetes Job, or directly on the host, depending on the [backend](/platform/self-hosting/#managed-architecture) you chose. Code, build artifacts, and workspaces stay on your machines. -4. **Run data returns to Warp** - Status, transcripts, artifacts, attachments, and telemetry flow back for the run record. Content the agent puts into prompts or results can include code context; see [security and networking](/platform/self-hosting/security-and-networking/). +3. **The agent runs on your backend** - The worker clones repositories, runs setup, injects allowed [secrets](/platform/secrets/), and executes in a Docker container, a Kubernetes Job, or directly on the host, depending on the [managed backend](/factories/self-hosting/#managed-architecture) you chose. Code, build artifacts, and workspaces stay on your machines. +4. **Run data returns to Warp** - Status, transcripts, artifacts, attachments, and telemetry flow back for the run record. Content the agent puts into prompts or results can include code context; see [execution security](/platform/execution-security/). 5. **Warp routes inference** - With the Warp Agent, model calls go from your worker through Warp to LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), or through your own provider account with [team-managed keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) or [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/). Claude Code and Codex call their provider directly from your infrastructure. 6. **Your team monitors the run** - Runs on self-hosted workers appear in the {VARS.DASHBOARD} and support [Agent Session Sharing](/agents/local-agents/session-sharing/), the same as Warp-hosted runs. @@ -91,7 +91,7 @@ Every run moves a few distinct classes of data, and each class has its own bound ![Warp-hosted data security and boundaries diagram showing repositories, clients, and integrations in customer infrastructure, the per-run sandbox and control plane on the Warp platform, model providers, and Warp-managed run-data storage](../../../assets/agent-platform/warp-hosted-data-boundaries.png) -* **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store repository clones or train on your code. For [self-hosted execution](/platform/self-hosting/), checkout and the workspace stay on your infrastructure. Either way, code context the agent puts into prompts, transcripts, or artifacts transits Warp and may persist as run data. +* **Source code** - For Warp-hosted runs, repositories are cloned into an isolated per-run sandbox and destroyed with it; Warp does not persistently store repository clones or train on your code. For [managed self-hosting](/factories/self-hosting/), checkout and the workspace stay on your infrastructure. Either way, code context the agent puts into prompts, transcripts, or artifacts transits Warp and may persist as run data. * **Prompts and context** - With the Warp Agent, model calls route through Warp to LLM providers under [Zero Data Retention](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements: providers don't retain or train on the traffic. [Team-managed keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) and [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) keep the same route but use your provider account. Claude Code and Codex call their provider directly from the execution environment, under your provider agreement rather than Warp's. * **Run data** - Transcripts, artifacts, and run attachments are stored in Warp-managed storage, encrypted at rest and access-controlled by your team's roles. * **Control-plane data** - Warp always retains what it needs to operate the platform: user and organization settings, agent and factory configuration, orchestration and lifecycle metadata, trigger and integration metadata, operational logs, and usage and billing. @@ -102,15 +102,15 @@ Every run moves a few distinct classes of data, and each class has its own bound ### With self-hosted execution -[Self-hosted execution](/platform/self-hosting/) moves the execution boundary: checkout, builds, and command execution stay on your infrastructure, and no Warp-hosted sandbox is involved. The control plane still coordinates runs, holds control-plane data, routes inference for the Warp Agent, and stores run data. +[Managed self-hosting](/factories/self-hosting/) moves the execution boundary: checkout, builds, and command execution stay on your infrastructure, and no Warp-hosted sandbox is involved. The control plane still coordinates runs, holds control-plane data, routes inference for the Warp Agent, and stores run data. ![Self-hosted data security and boundaries diagram showing what stays in customer infrastructure, what Warp retains, Warp-managed run-data storage, and what transits Warp to model providers](../../../assets/agent-platform/data-security-boundaries.png) ## Related pages -* [Deployment patterns](/platform/deployment-patterns/) - Choose between CLI-only, Warp-hosted, and self-hosted deployments. -* [Self-hosting overview](/platform/self-hosting/) - Managed vs unmanaged architectures and setup guides. -* [Self-hosting security and networking](/platform/self-hosting/security-and-networking/) - The data model and egress requirements for self-hosted workers. +* [Deployment patterns](/factories/deployment-patterns/) - Choose between CLI-only, Warp-hosted, and self-hosted deployments. +* [Managed self-hosting](/factories/self-hosting/) - Configure a managed worker for factory execution. +* [Execution security](/platform/execution-security/) - The data model and egress requirements for self-hosted workers. * [Security overview](/enterprise/security-and-compliance/security-overview/) - Warp's data handling, encryption, and compliance posture. * [How Warp Factories work](/factories/how-factories-work/) - The work-item lifecycle in depth. * [Warp Factories infrastructure and security](/factories/infrastructure-and-security/) - The same boundaries applied to factories. diff --git a/src/content/docs/platform/deployment-patterns.mdx b/src/content/docs/platform/deployment-patterns.mdx deleted file mode 100644 index 5f35d060a..000000000 --- a/src/content/docs/platform/deployment-patterns.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Deployment patterns -description: >- - Common architectures for deploying cloud agents, including CLI-only, - {{WARP_AUTOMATION_PLATFORM}}-hosted, and self-hosted execution patterns. -sidebar: - label: "Deployment patterns" ---- -import { VARS } from '@data/vars'; - -Teams adopt cloud agents in a few repeatable ways. This page outlines the most common architectures, what they're good for, and how they fit together. - -![Deployment models diagram comparing Warp-hosted, managed self-hosted, and unmanaged self-hosted patterns by what runs on Warp versus customer infrastructure](../../../assets/agent-platform/deployment-models.png) - -## Quick mental model - -Cloud agent setups usually have four moving parts: - -1. **Trigger**: something happens (CI step, webhook, cron, Slack mention). -2. **Orchestration**: something decides what to run and tracks it ({VARS.WARP_AUTOMATION_PLATFORM} orchestrator, GitHub Actions, your internal system). -3. **Execution**: where the agent actually runs (your runner, {VARS.WARP_AUTOMATION_PLATFORM}-hosted environment, or self-hosted workers). -4. **Visibility**: how the team monitors and intervenes ({VARS.DASHBOARD}, session sharing, APIs). - ---- - -## Pattern 1: CLI-only agents (bring your own orchestrator) - -Use this when you already have a system that schedules work (CI, dev boxes, internal orchestrators), and you need a reliable, cloud-connected agent runner. - -### What it looks like - -* **Trigger**: GitHub Actions / CI, a script, a dev box action, or an internal orchestrator -* **Orchestration**: your existing system -* **Execution**: wherever that system runs -* **Warp adds**: cloud connectivity, shared context, visibility, session sharing, and tracking - -### Why teams choose it - -* You want a **drop-in replacement** for other CLI/SDK-based agents (Claude Code, Codex CLI, Gemini CLI/SDK-style flows). -* You want to run agents anywhere without requiring Warp desktop. -* You still want **team-level observability** even when execution is “outside Warp.” - -### Common examples - -* **CI PR helper**: run formatting checks, generate review comments, suggest fixes, open PRs. -* **Remote dev box agent**: run refactors or debugging tasks inside a pre-provisioned box. -* **Internal orchestrator integration**: treat Warp as one agent option alongside other model providers. - -### What you still get even without Warp orchestration - -* Access to your shared Warp context (for example MCP config, Warp Drive context, rules/prompts). -* [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor/steer runs. -* Read-only APIs for tracking and reporting. -* A path to [Handoff](/platform/handoff/) workflows (where a run can be continued or inspected in richer surfaces). - -### Minimal setup checklist - -* A Warp team -* A [cloud agent](/platform/agents/) (recommended for automation) -* The {VARS.WARP_AGENT_CLI} installed on the runner / box -* Any needed credentials (often via secrets + environment variables) - ---- - -## Pattern 2: Warp-hosted agents and orchestration (managed cloud execution) - -Use this when you want the {VARS.WARP_AUTOMATION_PLATFORM} to run agent workloads on Warp-managed infrastructure, typically inside reproducible Docker environments, with built-in lifecycle management. - -![Warp-hosted execution architecture showing customer infrastructure, triggers and integrations, isolated tenant sandboxes, the Warp control plane, and LLM providers](../../../assets/agent-platform/cloud-agents-infra.png) - -See the [cloud agent run lifecycle](/platform/architecture/#cloud-agent-run-lifecycle) reference for a description of each component in the architecture. - -### What it looks like - -* **Trigger**: first-party integrations, cron schedules, API/SDK calls, or on-demand commands -* **Orchestration**: {VARS.WARP_AUTOMATION_PLATFORM} orchestrator -* **Execution**: {VARS.WARP_AUTOMATION_PLATFORM}-hosted environments (Docker-based) -* **Visibility**: {VARS.DASHBOARD} + session sharing + APIs/SDKs - -### Why teams choose it - -* You want the simplest path to reproducible, scalable cloud execution. -* You want to run many tasks in parallel without building your own sandboxing and scaling layer. -* You want a consistent “production” setup with standardized environments and centralized configuration. - -### Common ways to trigger - -* **First-party integrations (Slack, Linear, etc.)** that create tasks automatically from external events. -* **[Scheduled agents](/platform/triggers/scheduled-agents/)** for recurring work (cron-like automation). -* **Custom triggers** from your own systems using Warp’s API/SDK. -* **On-demand cloud jobs** using CLI commands like `oz agent run-cloud`. - -### Example recipe: daily dead-code cleanup - -1. Define a Warp [Environment](/platform/environments/) with the repo + toolchain. -2. Create a [schedule](/platform/triggers/scheduled-agents/) with a fixed prompt for cleanup. -3. The {VARS.WARP_AUTOMATION_PLATFORM} runs the agent on the cadence. -4. Your team monitors runs in the [{VARS.WEB_APP}](/platform/oz-web-app/) and [viewing cloud agent runs](/platform/viewing-cloud-agent-runs/), reviews artifacts (PRs, plans), and intervenes when needed. - -### Example recipe: crash triage via Sentry webhook - -1. Define a Warp Environment with the target repo. -2. Register a Sentry webhook to your handler (server, cloud function, Zapier/n8n). -3. Handler extracts crash details, constructs a prompt, and calls the {VARS.WARP_AUTOMATION_PLATFORM} orchestrator API/SDK to start a task. -4. Warp spins up the run in the environment and you monitor progress via UI/API. - -### Example recipe: fan-out parallel work (sharding) - -When a task is naturally divisible, use [multi-agent orchestration](/platform/orchestration/) to spawn one child agent per shard from a single parent run. The parent owns coordination and result aggregation; the children execute in parallel, each with their own repo subset, prompt, and (optionally) model. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) for slash command, CLI, web app, and API examples. - -### Example recipe: same task across multiple models - -* Launch N runs with the same prompt, but different profiles that map to different models. -* Compare results and choose the best output (or merge). - ---- - -## Pattern 3: Self-hosted execution - -Use this when you need to control where agent execution happens while still using {VARS.WARP_AUTOMATION_PLATFORM} orchestration and visibility. Repositories are cloned and stored only on your infrastructure. Orchestration metadata and session transcripts route through Warp's backend; cloud conversations require Warp to store conversation data according to Warp's retention terms. LLM inference requests and responses route through Warp to contracted model providers under [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr), except for provider-specific models that are not covered by ZDR and follow the provider's retention requirements. - -Think of self-hosted execution as **customer-hosted execution with Warp-hosted orchestration**, not as a fully offline agent stack. Code repositories, build artifacts, runtime secrets, and execution workspaces stay on your infrastructure. Code context can still appear in session transcripts and LLM prompts as the agent works. - -:::note -**Enterprise feature**: Self-hosted execution is available exclusively to teams on an Enterprise plan. -::: - -Self-hosting has two architectures that differ on **who orchestrates agent runs** (both keep code and execution on your infrastructure): - -* **[Managed](/platform/self-hosting/#managed-architecture)** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates. You run the `oz-agent-worker` daemon; the {VARS.WARP_AUTOMATION_PLATFORM} routes runs to it from Slack, Linear, schedules, the API, or `oz agent run-cloud`. Tasks execute in Docker containers, Kubernetes Jobs, or directly on the host. -* **[Unmanaged](/platform/self-hosting/unmanaged/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment. Warp provides session tracking and observability; it does not start or stop agents. - -Why teams choose self-hosted execution: - -* Code and execution must stay within your network boundary for compliance or security requirements. -* Agents need to access services behind a VPN or self-hosted SCMs like GitLab or Bitbucket. Warp-hosted agents can also access GitLab and Bitbucket over the public internet — see the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides. -* Your environments (multi-service stacks, heavy resource requirements) don't fit in a single Docker container. - -For setup, decision guides, and a quickstart, start with [Self-hosting](/platform/self-hosting/). diff --git a/src/content/docs/platform/environments.mdx b/src/content/docs/platform/environments.mdx index cf5f158c2..9a19483fc 100644 --- a/src/content/docs/platform/environments.mdx +++ b/src/content/docs/platform/environments.mdx @@ -9,11 +9,13 @@ import { VARS } from '@data/vars'; Environments describe _how_ an agent executes a task, not _what_ it does. They give cloud agents the same container, repositories, and setup every time they run. Use an environment for a cloud agent run that needs a repeatable toolchain. Interactive local runs use your current checkout and machine setup, so they don't need one. +Factories manage their own repositories and workspace by default. Set `agentDefaults.environmentId` in a [factory definition](/factories/factory-as-code/#agentdefaultsenvironmentid) when a factory agent must use an existing environment. + ## What an environment includes An environment groups the runtime configuration for a cloud agent run: -* **Docker image** - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a [`default_image`](/platform/self-hosting/managed-kubernetes/) can run without a separate environment. +* **Docker image** - The image that provides the toolchain and dependencies for your code. A self-hosted Kubernetes worker with a [`default_image`](/factories/self-hosting/managed-kubernetes/) can run without a separate environment. * **Repositories** - One or more repos that the agent clones into its workspace. * **Setup commands** - Commands that prepare the workspace, such as dependency installation, builds, or code generation. * **Environment variables** - Runtime values that you set in the Docker image or container configuration. @@ -25,7 +27,7 @@ Together, these settings create a fresh workspace for each run. Warp provides [p When the {VARS.WARP_AUTOMATION_PLATFORM} starts a cloud agent run, it combines the environment with a host, an agent profile, and task-specific context. Each part serves a distinct purpose: -* **Host** - Determines where the run executes. Choose [Warp-hosted](warp-hosting/) infrastructure or [self-hosted](/platform/self-hosting/) runners. +* **Host** - Determines where the run executes. Choose [Warp-hosted](/factories/warp-hosting/) infrastructure or [self-hosted](/factories/self-hosting/) runners. * **Agent Profiles** - Set the agent's permissions, model choice, and defaults. See [Agent Profiles](/agents/capabilities/agent-profiles-permissions/). * **Rules** - Provide instructions that guide agent responses and decisions. See [Rules](/agents/capabilities/rules/). * **MCP servers** - Connect agents to external tools and data. See [MCP servers](/platform/mcp/). @@ -52,5 +54,5 @@ Cloud agents run as a non-root user inside the container. See [configuring conta * [Configuring cloud agent environments](environments/configuring-environments/) to create, configure, and manage environments. * [Troubleshooting cloud agent environments](environments/troubleshooting-environments/) to fix setup, authorization, permissions, and image failures. -* [Runners](/platform/runners/) to configure the compute that hosts environments. -* [Deployment patterns](/platform/deployment-patterns/) to choose between Warp-hosted and self-hosted execution. +* [Runners](/factories/runners/) to configure the compute that hosts environments. +* [Deployment patterns](/factories/deployment-patterns/) to choose between Warp-hosted and self-hosted execution. diff --git a/src/content/docs/platform/environments/configuring-environments.mdx b/src/content/docs/platform/environments/configuring-environments.mdx index 1f20570ab..691e3686c 100644 --- a/src/content/docs/platform/environments/configuring-environments.mdx +++ b/src/content/docs/platform/environments/configuring-environments.mdx @@ -162,4 +162,4 @@ Add `--force` to skip confirmation checks for environments used by integrations. * [Cloud agent environments](/platform/environments/) for the conceptual overview. * [Troubleshooting cloud agent environments](troubleshooting-environments/) to resolve setup and runtime problems. -* [Integration setup](/reference/cli/integration-setup/) to configure end-to-end integration workflows. +* [Integration setup](/agents/cli/oz-cli/integration-setup/) to configure end-to-end integration workflows. diff --git a/src/content/docs/platform/environments/troubleshooting-environments.mdx b/src/content/docs/platform/environments/troubleshooting-environments.mdx index 2eab2ceea..fcf6e5f27 100644 --- a/src/content/docs/platform/environments/troubleshooting-environments.mdx +++ b/src/content/docs/platform/environments/troubleshooting-environments.mdx @@ -7,7 +7,7 @@ import { VARS } from '@data/vars'; ## Setup commands fail on a fresh container -Setup commands run in a new container on every cloud agent run. Commands that depend on existing directories, caches, or cloned repositories can fail with [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/). +Setup commands run in a new container on every cloud agent run. Commands that depend on existing directories, caches, or cloned repositories can fail with [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/). 1. Update the setup commands so they work in a fresh container. For example, use `mkdir -p .cache` instead of `mkdir .cache`. 2. Use lockfile-based dependency commands such as `npm ci` when your project supports them. @@ -27,7 +27,7 @@ Cloud agents need GitHub authorization to clone private repositories. This error 1. Authorize GitHub for the user who starts the run. 2. For an automated workflow with an agent API key, configure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). -3. Follow [GitHub authorization setup](/reference/cli/integration-setup/#how-github-authorization-works) for the full flow. +3. Follow [GitHub authorization setup](/agents/cli/oz-cli/integration-setup/#how-github-authorization-works) for the full flow. ## "VM failed before the agent could run" @@ -41,4 +41,4 @@ This error often means the Docker image is incompatible with the agent runtime. * [Cloud agent environments](/platform/environments/) for the environment model and when to use one. * [Configuring cloud agent environments](configuring-environments/) to create, update, and manage environments. -* [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the API error reference. +* [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the API error reference. diff --git a/src/content/docs/platform/self-hosting/security-and-networking.mdx b/src/content/docs/platform/execution-security.mdx similarity index 93% rename from src/content/docs/platform/self-hosting/security-and-networking.mdx rename to src/content/docs/platform/execution-security.mdx index 8935cab8d..a66f43a03 100644 --- a/src/content/docs/platform/self-hosting/security-and-networking.mdx +++ b/src/content/docs/platform/execution-security.mdx @@ -8,7 +8,7 @@ description: >- Self-hosting uses a split-plane architecture. Understanding which data stays on your infrastructure and which data routes through Warp is critical for security evaluation. This page summarizes the data model, network egress requirements, and backend-specific security considerations for self-hosted workers. :::note -This page applies to both the [managed](/platform/self-hosting/#managed-architecture) and [unmanaged](/platform/self-hosting/unmanaged/) architectures. Backend-specific notes call out Docker-, Kubernetes-, and Direct-only considerations. +This page applies to both the [managed](/factories/self-hosting/#managed-architecture) and [unmanaged](/platform/unmanaged-execution/) architectures. Backend-specific notes call out Docker-, Kubernetes-, and Direct-only considerations. ::: ## Data boundaries @@ -38,7 +38,7 @@ Repositories are cloned and stored only on your infrastructure, but code content Self-hosted agents **do not require any network ingress**. They require outbound (egress) access to the following services: -![Self-hosted worker network egress diagram showing outbound-only connections from customer infrastructure to Warp backend endpoints, Docker Hub, Google Cloud Storage, and GitHub](../../../../assets/agent-platform/self-hosted-network-egress.png) +![Self-hosted worker network egress diagram showing outbound-only connections from customer infrastructure to Warp backend endpoints, Docker Hub, Google Cloud Storage, and GitHub](../../../assets/agent-platform/self-hosted-network-egress.png) **Warp's backend (all architectures):** @@ -114,8 +114,8 @@ LLM inference routes through Warp's backend. With Warp-managed inference, reques ## Related pages -* [Self-hosting overview](/platform/self-hosting/) — Managed vs unmanaged and architecture decision guide. +* [Managed self-hosting](/factories/self-hosting/) — Install and operate a managed worker for a factory. * [Data security and boundaries](/platform/architecture/#data-security-and-boundaries) — Diagrams of where each class of data lives and travels. * [Security overview](/enterprise/security-and-compliance/security-overview/) — Warp's broader security model, including ZDR. * [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) — Route inference through your own cloud provider accounts. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config schema, including every security-relevant option. +* [Self-hosted worker reference](/factories/self-hosting/reference/) — CLI flags and config schema, including every security-relevant option. diff --git a/src/content/docs/platform/faqs.mdx b/src/content/docs/platform/faqs.mdx index ed1fe3d3e..1f3337094 100644 --- a/src/content/docs/platform/faqs.mdx +++ b/src/content/docs/platform/faqs.mdx @@ -61,7 +61,7 @@ No. By default, cloud agents run as a dedicated non-root `agent` user (UID/GID 1 The cloud agents platform supports self-hosting the **agent sandbox** (the execution environment) on your own infrastructure. The **control plane**—which handles orchestration, tracking, and auditability—remains Warp-managed and is not self-hosted. -Self-hosted execution is available on **Enterprise** plans. See [Self-hosting](/platform/self-hosting/) and [Deployment patterns](/platform/deployment-patterns/) for details. +Self-hosted execution is available on **Enterprise** plans. See [Self-hosting](/factories/self-hosting/) and [Deployment patterns](/factories/deployment-patterns/) for details. :::note Self-serve [Bring Your Own API Key (BYOK)](/agents/inference/bring-your-own-api-key/) does not apply to cloud agents. Keys you add yourself are stored locally on your device and can't be passed to cloud-hosted or self-hosted agent runs, so those runs consume [Warp credits](/support-and-community/plans-and-billing/credits/). @@ -209,11 +209,11 @@ With self-hosting, repositories are cloned and stored only on your infrastructur * **Execution plane (your infrastructure)** — Repository clones, build artifacts, runtime secrets, and container filesystem state stay on the machines you control. * **Control plane (Warp-hosted)** — Session transcripts (which include code context from agent interactions), orchestration metadata, and LLM inference route through Warp's backend under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or use it for model training. -See [Self-hosting](/platform/self-hosting/) for deployment options and [Security Overview](/enterprise/security-and-compliance/security-overview/) for full details. +See [Self-hosting](/factories/self-hosting/) for deployment options and [Security Overview](/enterprise/security-and-compliance/security-overview/) for full details. ### Can I use `oz agent run` in CI or existing runners? -Yes. The [unmanaged architecture](/platform/self-hosting/unmanaged/) is designed exactly for this. Run `oz agent run` in any environment where you can execute a CLI command — GitHub Actions, Jenkins, Buildkite, Kubernetes pods, or custom orchestrators. This is how the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) GitHub Action works. The agent runs locally on the runner and its session is tracked on Warp's backend for observability. +Yes. The [unmanaged architecture](/platform/unmanaged-execution/) is designed exactly for this. Run `oz agent run` in any environment where you can execute a CLI command — GitHub Actions, Jenkins, Buildkite, Kubernetes pods, or custom orchestrators. This is how the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) GitHub Action works. The agent runs locally on the runner and its session is tracked on Warp's backend for observability. ### Can self-hosted agents access services behind a VPN? @@ -221,7 +221,7 @@ Yes. Since self-hosted agents run on your infrastructure, they inherit your netw ### Does self-hosting work with GitLab or other non-GitHub SCMs? -Self-hosted agents can use any SCM accessible from your infrastructure. With the [unmanaged architecture](/platform/self-hosting/unmanaged/), agents run directly on your host and use whatever Git configuration and SCM access is already available. With the [managed architecture](/platform/self-hosting/#managed-architecture), automatic environment setup currently focuses on GitHub, but you can configure access to other SCMs via volume mounts, environment variables, setup commands, or Kubernetes Secrets (when using the [Kubernetes backend](/platform/self-hosting/managed-kubernetes/)). See the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides for step-by-step instructions. +Self-hosted agents can use any SCM accessible from your infrastructure. With the [unmanaged architecture](/platform/unmanaged-execution/), agents run directly on your host and use whatever Git configuration and SCM access is already available. With the [managed architecture](/factories/self-hosting/#managed-architecture), automatic environment setup currently focuses on GitHub, but you can configure access to other SCMs via volume mounts, environment variables, setup commands, or Kubernetes Secrets (when using the [Kubernetes backend](/factories/self-hosting/managed-kubernetes/)). See the [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrations/bitbucket/) setup guides for step-by-step instructions. ### Do LLM requests still go through Warp with self-hosting? @@ -229,10 +229,10 @@ Yes. LLM inference routes through Warp's backend, which has [Zero Data Retention ### What about large monorepos with long environment setup times? -The [unmanaged architecture](/platform/self-hosting/unmanaged/) is well-suited for large monorepos because agents run directly in your pre-provisioned environment — there is no Docker image build or repo cloning step. For the [managed architecture](/platform/self-hosting/#managed-architecture), the Docker backend supports volume mounts (`-v` flag) to mount a pre-existing repo checkout from the host into task containers. With the Kubernetes backend, use `pod_template` to configure persistent volume claims or pre-populated storage for the same purpose. +The [unmanaged architecture](/platform/unmanaged-execution/) is well-suited for large monorepos because agents run directly in your pre-provisioned environment — there is no Docker image build or repo cloning step. For the [managed architecture](/factories/self-hosting/#managed-architecture), the Docker backend supports volume mounts (`-v` flag) to mount a pre-existing repo checkout from the host into task containers. With the Kubernetes backend, use `pod_template` to configure persistent volume claims or pre-populated storage for the same purpose. :::note -The managed architecture supports three execution backends: **Docker** (default), **Kubernetes**, and **Direct** (no container runtime). The Kubernetes backend runs each task as a Kubernetes Job and includes a Helm chart for deployment. See [Self-hosting](/platform/self-hosting/#choosing-a-managed-backend) for details on choosing a backend. +The managed architecture supports three execution backends: **Docker** (default), **Kubernetes**, and **Direct** (no container runtime). The Kubernetes backend runs each task as a Kubernetes Job and includes a Helm chart for deployment. See [Self-hosting](/factories/self-hosting/#choose-a-backend) for details on choosing a backend. ::: ### Do Kubernetes pods provide enough sandboxing for self-hosted agents? diff --git a/src/content/docs/platform/handoff/snapshots.mdx b/src/content/docs/platform/handoff/snapshots.mdx index 5f6600006..a49bd96ab 100644 --- a/src/content/docs/platform/handoff/snapshots.mdx +++ b/src/content/docs/platform/handoff/snapshots.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; Workspace snapshots are how [handoff](/platform/handoff/) carries repository changes and other workspace state across cloud agent runs. At the end of every cloud agent run, Warp asks a small declarations script which repositories and files to snapshot, then uploads the resulting git diffs and file contents so the next cloud agent run can apply them. -Warp's bundled cloud agent image ships with a declarations script that snapshots every Git repository under the agent's workspace, so most cloud agent runs need no configuration. This page is for the cases where you need to customize what gets snapshotted — for example, when running cloud agents in a custom Docker image, on a self-hosted [Direct backend](/platform/self-hosting/managed-direct/), or as an [unmanaged](/platform/self-hosting/unmanaged/) `oz agent run` in CI. +Warp's bundled cloud agent image ships with a declarations script that snapshots every Git repository under the agent's workspace, so most cloud agent runs need no configuration. This page is for the cases where you need to customize what gets snapshotted — for example, when running cloud agents in a custom Docker image, on a self-hosted [Direct backend](/factories/self-hosting/managed-direct/), or as an [unmanaged](/platform/unmanaged-execution/) `oz agent run` in CI. ## When to customize snapshots @@ -113,7 +113,7 @@ Then point Warp at it by exporting `OZ_SNAPSHOT_DECLARATIONS_SCRIPT` in the envi export OZ_SNAPSHOT_DECLARATIONS_SCRIPT=/path/to/snapshot-declarations.sh ``` -For a managed [Direct backend](/platform/self-hosting/managed-direct/) worker, set it via the worker's `environment` config so it's present when the agent process starts. +For a managed [Direct backend](/factories/self-hosting/managed-direct/) worker, set it via the worker's `environment` config so it's present when the agent process starts. ### The full bundled script @@ -229,6 +229,6 @@ Snapshotting is also skipped automatically when cloud conversations are disabled * [Handoff from local to cloud](/platform/handoff/local-to-cloud/) - Promote a local conversation to a cloud run; the workspace snapshot is what carries your uncommitted changes across. * [Handoff from cloud to cloud](/platform/handoff/cloud-to-cloud/) - Continue a finished cloud run; the prior session's workspace snapshot is what gets restored. -* [Self-hosting overview](/platform/self-hosting/) - Architecture decision guide for self-hosted workers, where customizing snapshots is most often needed. -* [Unmanaged architecture](/platform/self-hosting/unmanaged/) - Run `oz agent run` in CI, Kubernetes, or your dev environment outside the bundled image. -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) - Full reference for `oz agent run` and `oz agent run-cloud`. +* [Self-hosting overview](/factories/self-hosting/) - Architecture decision guide for self-hosted workers, where customizing snapshots is most often needed. +* [Unmanaged architecture](/platform/unmanaged-execution/) - Run `oz agent run` in CI, Kubernetes, or your dev environment outside the bundled image. +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) - Full reference for `oz agent run` and `oz agent run-cloud`. diff --git a/src/content/docs/platform/harnesses/claude-code.mdx b/src/content/docs/platform/harnesses/claude-code.mdx index eb8c70c8e..d929ad89f 100644 --- a/src/content/docs/platform/harnesses/claude-code.mdx +++ b/src/content/docs/platform/harnesses/claude-code.mdx @@ -45,7 +45,7 @@ For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/au * **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Claude Code**. * **{VARS.WEB_APP}** - On the new run or new schedule pane, choose **Claude Code** in the **Harness** field. A **Claude Code auth secret** field appears below it; pick one of your stored Anthropic secrets. -* **API and SDK** - Set the agent config `harness` to `claude` — the [harness identifier](/platform/harnesses/#harness-identifiers) is `claude`, not `claude-code` — and the Anthropic secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/). +* **API and SDK** - Set the agent config `harness` to `claude` — the [harness identifier](/platform/harnesses/#harness-identifiers) is `claude`, not `claude-code` — and the Anthropic secret name on the matching auth-secret field. See the [API reference](/factories/api-and-sdk/). ## Related pages diff --git a/src/content/docs/platform/harnesses/codex.mdx b/src/content/docs/platform/harnesses/codex.mdx index dadc3df16..569c729e4 100644 --- a/src/content/docs/platform/harnesses/codex.mdx +++ b/src/content/docs/platform/harnesses/codex.mdx @@ -45,7 +45,7 @@ For setup steps, see [Connecting Codex credentials](/platform/harnesses/authenti * **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Codex**. * **{VARS.WEB_APP}** - On the new run or new schedule pane, choose **Codex** in the **Harness** field. A **Codex auth secret** field appears below it; pick the OpenAI secret your team has stored. -* **API and SDK** - Set the agent config `harness` to `codex` and the OpenAI secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/). +* **API and SDK** - Set the agent config `harness` to `codex` and the OpenAI secret name on the matching auth-secret field. See the [API reference](/factories/api-and-sdk/). ## Related pages diff --git a/src/content/docs/platform/harnesses/index.mdx b/src/content/docs/platform/harnesses/index.mdx index 98a629bbd..60b7d6d56 100644 --- a/src/content/docs/platform/harnesses/index.mdx +++ b/src/content/docs/platform/harnesses/index.mdx @@ -12,6 +12,8 @@ import { VARS } from '@data/vars'; The {VARS.WARP_AUTOMATION_PLATFORM} can run third-party agent harnesses as cloud agents alongside Warp Agent, including [Claude Code](/platform/harnesses/claude-code/) and [Codex](/platform/harnesses/codex/). You choose the harness (agent runtime) that fits the task; the platform around the run stays the same. +For a factory, set the default or per-agent harness in its [factory definition](/factories/factory-as-code/#agentdefaultsharness) or configure it for a [factory agent](/factories/factory-agents/). + Watch this walkthrough to see how to run Warp Agent, Claude Code, or Codex as a cloud agent. <VideoEmbed url="https://www.youtube.com/watch?v=ZUYyuA5i1VU" title={`Run any agent in the cloud with the ${VARS.WARP_AUTOMATION_PLATFORM} - Claude Code, Codex, or Warp Agent`} /> @@ -54,7 +56,7 @@ On the new run or new schedule pane, choose the harness in the **Harness** field ### API and SDK -Set the `harness` field on the agent config to one of the [harness identifiers](#harness-identifiers) below. See the [API reference](/reference/api-and-sdk/) for the exact field names. +Set the `harness` field on the agent config to one of the [harness identifiers](#harness-identifiers) below. See the [API reference](/factories/api-and-sdk/) for the exact field names. ## Harness identifiers diff --git a/src/content/docs/platform/harnesses/warp-agent.mdx b/src/content/docs/platform/harnesses/warp-agent.mdx index 79165c57c..d1071c9c2 100644 --- a/src/content/docs/platform/harnesses/warp-agent.mdx +++ b/src/content/docs/platform/harnesses/warp-agent.mdx @@ -56,7 +56,7 @@ Warp Agent is the default, so there's nothing extra to configure. * **Warp app** - Start a cloud agent run from the input. The **Agent harness** dropdown defaults to **Warp Agent**. * **{VARS.WEB_APP}** - On a new run or new schedule pane, leave the **Harness** field set to **Warp Agent**. * **{VARS.WARP_AGENT_CLI}** - Run `oz agent run-cloud --prompt "..."` with no `--harness` flag, or pass `--harness oz` explicitly. -* **API and SDK** - Omit the `harness` field on the agent config, or set it to `oz`. See the [API reference](/reference/api-and-sdk/). +* **API and SDK** - Omit the `harness` field on the agent config, or set it to `oz`. See the [API reference](/factories/api-and-sdk/). For a complete walkthrough, see the [Cloud agents quickstart](/platform/quickstart/). diff --git a/src/content/docs/platform/index.mdx b/src/content/docs/platform/index.mdx index 27e991797..ae7e6747d 100644 --- a/src/content/docs/platform/index.mdx +++ b/src/content/docs/platform/index.mdx @@ -9,16 +9,16 @@ sidebar: import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; -{/* Transition notice for the 2026-08-18 rename. Remove after 2026-10-06, when - the CLI and web app take their new names and the old one stops appearing. */} :::note -**Oz is now the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/).** Only the name changed. Your existing cloud agents, integrations, API keys, and schedules keep working exactly as before. The `oz` CLI and the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> keep the Oz name until October 6, 2026. +**The [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) is the current name.** Existing cloud agents, integrations, API keys, and schedules continue to work. The `oz` CLI and the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> retain their legacy names during the transition. See [Transitioning](/platform/transitioning-from-oz/) for the current guidance. ::: Cloud agents are autonomous, background agents that run on Warp's cloud infrastructure or your own, triggered by system events, schedules, or integrations like Slack and GitHub. They execute tasks with full observability — every run is tracked, inspectable, and shareable across your team. **New to cloud agents?** Start with the [Cloud agents quickstart](/platform/quickstart/) to run your first cloud agent in ~10 minutes. +For a standing, multi-stage workflow with named agents, automations, and measurement, use [Warp Factories](/factories/). The factory-specific setup and operations guidance complements this shared cloud-agent reference. + ### Monitor, inspect, and share cloud agent runs To understand what a cloud agent did, start from the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app or the [Runs page in the {VARS.WEB_APP}](/platform/oz-web-app/#runs). From there, you can find a run by source, status, trigger, or owner; open the run transcript; inspect the prompt, plan, commands, logs, and output; and share the session link with teammates for review. @@ -68,9 +68,9 @@ Cloud agents run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/), * The **orchestrator creates** and tracks the task. * The agent **executes** on a host, optionally inside an [environment](/platform/environments/), with whatever [secrets](/platform/secrets/) and credentials it needs. -The exact way tasks are triggered and executed depends on your deployment model (for example CLI-only, Warp-hosted orchestration, or self-hosted execution). Those options are covered in the [Deployment Patterns](/platform/deployment-patterns/) pages. +The exact way tasks are triggered and executed depends on your deployment model (for example CLI-only, Warp-hosted orchestration, or self-hosted execution). Those options are covered in the [Deployment Patterns](/factories/deployment-patterns/) pages. -For teams that need execution to stay within their network boundary, self-hosting supports two architectures: a **managed** worker daemon that lets the {VARS.WARP_AUTOMATION_PLATFORM} orchestrate agents in Docker containers on your machines, and an **unmanaged** mode where you run `oz agent run` directly in your CI, Kubernetes, or dev environment. See [Self-hosting](/platform/self-hosting/) for details. +For teams that need execution to stay within their network boundary, self-hosting supports two architectures: a **managed** worker daemon that lets the {VARS.WARP_AUTOMATION_PLATFORM} orchestrate agents in Docker containers on your machines, and an **unmanaged** mode where you run `oz agent run` directly in your CI, Kubernetes, or dev environment. See [Self-hosting](/factories/self-hosting/) for details. ### What you get by default @@ -98,7 +98,7 @@ For details on configuring MCP servers for cloud agents, see [MCP Servers](/plat #### API access to tasks -The {VARS.WARP_AUTOMATION_PLATFORM} exposes task visibility via the [**{VARS.API_SDK_NAME}**](/reference/api-and-sdk/), so teams can: +The {VARS.WARP_AUTOMATION_PLATFORM} exposes task visibility via the [**{VARS.WARP_PLATFORM_API}**](/factories/api-and-sdk/), so teams can: * Query which tasks are running or have run. * Fetch task metadata and outcomes. @@ -108,11 +108,11 @@ The {VARS.WARP_AUTOMATION_PLATFORM} exposes task visibility via the [**{VARS.API Cloud agents do not require the Warp app. Teams can deploy and operate them through the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) using: -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — run agents from scripts, CI, or the terminal +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — run agents from scripts, CI, or the terminal * [{VARS.WEB_APP}](/platform/oz-web-app/) — visual interface for managing runs, schedules, environments, and integrations (works on mobile) * [Agent Session Sharing](/agents/local-agents/session-sharing/) — attach to running tasks to monitor or steer * [Agent Management Panel](/platform/managing-cloud-agents/) — view agent activity and run history in the Warp app -* [APIs and SDKs](/reference/api-and-sdk/) — programmatic access for custom integrations +* [APIs and SDKs](/factories/api-and-sdk/) — programmatic access for custom integrations If your team also uses Warp's terminal, you get an additional workflow: tasks launched via the CLI can be handed off into an interactive session for review, edits, or continuation. @@ -155,16 +155,16 @@ If your credit balance reaches zero, cloud agent runs will not be able to execut ### Learn more * [Cloud agents quickstart](/platform/quickstart/) — run your first cloud agent with an environment in ~10 minutes. -* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) — CLI, {VARS.API_SDK_NAME}, orchestration, tasks, environments, hosts, integrations, and more. +* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) — CLI, {VARS.WARP_PLATFORM_API}, orchestration, tasks, environments, hosts, integrations, and more. * [Warp Factories](/factories/) — assemble cloud agents into a standing triage-to-merge workflow with named agents, automations, and measurement. * [Harnesses](/platform/harnesses/) — pick between Warp Agent, Claude Code, and Codex for any cloud agent run. * [Agents](/platform/agents/) — cloud agents that own and execute runs on your team. * [Multi-agent orchestration](/platform/orchestration/) — coordinate a parent agent and its child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows. * [Skills as Agents](/platform/skills-as-agents/) — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule. -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — shows how to run agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — shows how to run agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. * [Environments](/platform/environments/) — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. * [Agent Secrets](/platform/secrets/) — covers how to store, scope, and inject credentials into agent runs safely. * [MCP Servers](/platform/mcp/) — how to configure MCP servers for agent tool access and how MCP configuration is applied across runs. -* [Deployment Patterns](/platform/deployment-patterns/) (beta) — compares common ways to deploy cloud agents and when to use each. +* [Deployment Patterns](/factories/deployment-patterns/) (beta) — compares common ways to deploy cloud agents and when to use each. * [Access, Billing, and Identity Permissions](/platform/team-access-billing-and-identity/) — explains individual and team-level requirements, credit billing behavior, and the permission model for who can run, view, and steer cloud agent tasks. diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index 777101633..99c2d0f9b 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -22,7 +22,7 @@ This approach works for both Azure DevOps Services (dev.azure.com) and Azure Dev * A Warp account (<a href={VARS.WEB_APP_URL}>create an account at {VARS.WEB_APP_URL}</a>) * A repository hosted on Azure DevOps (cloud or self-hosted) -* The [{VARS.WARP_AGENT_CLI}](/reference/cli/) installed and authenticated +* The [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) installed and authenticated --- diff --git a/src/content/docs/platform/integrations/bitbucket.mdx b/src/content/docs/platform/integrations/bitbucket.mdx index b2b8baad5..fb67db47b 100644 --- a/src/content/docs/platform/integrations/bitbucket.mdx +++ b/src/content/docs/platform/integrations/bitbucket.mdx @@ -25,7 +25,7 @@ Follow the section that matches your setup. * A Warp account (<a href={VARS.WEB_APP_URL}>create an account at {VARS.WEB_APP_URL}</a>) * A repository hosted on Bitbucket (Cloud or Data Center/Server) -* The [{VARS.WARP_AGENT_CLI}](/reference/cli/) installed and authenticated +* The [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) installed and authenticated --- diff --git a/src/content/docs/platform/integrations/cloud-providers.mdx b/src/content/docs/platform/integrations/cloud-providers.mdx index 5a7ae511a..16320d869 100644 --- a/src/content/docs/platform/integrations/cloud-providers.mdx +++ b/src/content/docs/platform/integrations/cloud-providers.mdx @@ -300,7 +300,7 @@ Team ID: xyz789 Team Name: My Team ``` -You can also check the user IDs from past runs using the {VARS.API_SDK_NAME}: +You can also check the user IDs from past runs using the {VARS.WARP_PLATFORM_API}: ```bash curl https://app.warp.dev/api/v1/agent/runs -H "Authorization: Bearer $WARP_API_KEY" @@ -334,7 +334,7 @@ The following claims are derived from an agent run: * `environment`: the unique identifier for the agent's [Environment](/platform/environments/). * `agent_name`: the name of the [Skill](/platform/skills-as-agents/) that the agent was invoked with. * `skill_spec`: the canonical identifier for the skill, such as `github-org/github-repo:.warp/skills/skill-name/SKILL.md`. -* `host`: the execution host. This will either be `warp`, for Warp-hosted agents, or the worker ID if [self-hosting](/platform/self-hosting/). +* `host`: the execution host. This will either be `warp`, for Warp-hosted agents, or the worker ID if [self-hosting](/factories/self-hosting/). ### Example token diff --git a/src/content/docs/platform/integrations/github-actions.mdx b/src/content/docs/platform/integrations/github-actions.mdx index f519e47ad..adcffc9bd 100644 --- a/src/content/docs/platform/integrations/github-actions.mdx +++ b/src/content/docs/platform/integrations/github-actions.mdx @@ -48,7 +48,7 @@ The `oz-agent-action` is a GitHub Action that wraps the {VARS.WARP_AGENT_CLI} an To use agents in GitHub Actions, you need: -* A [**Warp API Key**](/reference/cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to run as a [cloud agent](/platform/agents/) on your team. See [API keys](/reference/cli/api-keys/) for when to pick each. +* A [**Warp API key**](/agents/cli/oz-cli/api-keys/) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp. Pick a personal key if you want commits attributed to you, or an agent key to run as a [cloud agent](/platform/agents/) on your team. See [API keys](/agents/cli/oz-cli/api-keys/) for when to pick each. * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) @@ -73,7 +73,7 @@ You can specify a skill using the `skill` input parameter, either instead of or :::tip If the action fails, use the returned error code to narrow the fix. Common errors include: -* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) (missing, invalid, or expired `warp_api_key` secret) +* [`authentication_required`](/factories/api-and-sdk/troubleshooting/errors/authentication-required/) (missing, invalid, or expired `warp_api_key` secret) ::: #### Skill format options diff --git a/src/content/docs/platform/integrations/github.mdx b/src/content/docs/platform/integrations/github.mdx index 6c0231acf..88ff904e0 100644 --- a/src/content/docs/platform/integrations/github.mdx +++ b/src/content/docs/platform/integrations/github.mdx @@ -192,9 +192,9 @@ Your GitHub account is connected, but your Warp account isn't in a team with acc Use the error code in the thread's status comment to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) - The team's plan doesn't support integrations. -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) - GitHub authorization is missing or expired. -* [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) - The billed account has no credits available. +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) - The team's plan doesn't support integrations. +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) - GitHub authorization is missing or expired. +* [`insufficient_credits`](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/) - The billed account has no credits available. ### The agent finished but opened no pull request diff --git a/src/content/docs/platform/integrations/index.mdx b/src/content/docs/platform/integrations/index.mdx index bd981d9e3..3bf7901c4 100644 --- a/src/content/docs/platform/integrations/index.mdx +++ b/src/content/docs/platform/integrations/index.mdx @@ -14,6 +14,8 @@ Warp integrations let your team trigger agents directly from the terminal, or fr * Run code inside your codebase in a remote environment * Open pull requests and perform other multi-step agent workflows on your behalf +For intake that routes work through a factory's named agents and automations, use the [Factory integrations](/factories/connect-your-factory/) documentation. + Integrations are one way to start a cloud agent. For the full set, including schedules, the {VARS.WARP_AGENT_CLI}, and the API, see [Triggers](/platform/triggers/). If you're deciding which one to use, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). :::note @@ -31,7 +33,7 @@ Use the setup walkthrough below for a quick look at how environments connect to <VideoEmbed url="https://www.youtube.com/watch?v=ahFfInVD0HQ" title="Cloud agents integrations overview video" /> * [Integrations quickstart](/platform/integrations/quickstart/) - Trigger your first agent from Slack and watch the run from start to finish. -* [Integration setup](/reference/cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail. +* [Integration setup](/agents/cli/oz-cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail. * [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), and [Jira](/platform/integrations/jira/) - Trigger agents from team conversations, issues, and comments. * [GitHub](/platform/integrations/github/) - Mention `@warp-agent` on issues, pull requests, and review comments to start agents that reply in the thread. * [GitHub Actions](/platform/integrations/github-actions/) - Run agents from CI workflows and repository events. diff --git a/src/content/docs/platform/integrations/jira.mdx b/src/content/docs/platform/integrations/jira.mdx index 6363debb7..ab45559cd 100644 --- a/src/content/docs/platform/integrations/jira.mdx +++ b/src/content/docs/platform/integrations/jira.mdx @@ -16,7 +16,7 @@ The Jira integration lets your team kick off cloud agent runs directly from Jira * **Jira Cloud** - Jira Server and Data Center are not supported. * **Team membership** - The Jira integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. -* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/platform/self-hosting/) on their own infrastructure. +* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/factories/self-hosting/) on their own infrastructure. * **Jira site admin** - Installing the Warp app on your Jira site requires site admin permissions. --- diff --git a/src/content/docs/platform/integrations/linear.mdx b/src/content/docs/platform/integrations/linear.mdx index 5e631c8dc..8240072aa 100644 --- a/src/content/docs/platform/integrations/linear.mdx +++ b/src/content/docs/platform/integrations/linear.mdx @@ -70,7 +70,7 @@ Because PRs are created as _you_, this makes code review, auditing, and team col * **Team membership** - The Linear integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must have cloud agents enabled and credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. -* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/platform/self-hosting/) on their own infrastructure. +* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/factories/self-hosting/) on their own infrastructure. * **Identity** - The first time you trigger an agent, Warp prompts you to connect your Linear identity to your Warp account. * **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. * The repositories involved must be included in your environment and accessible to the Warp GitHub app. @@ -80,7 +80,7 @@ Because PRs are created as _you_, this makes code review, auditing, and team col ### How to configure the integration -Setup involves two steps powered by the [{VARS.WARP_AGENT_CLI}](/reference/cli/). For more instructions, see [Integrations Overview](/platform/integrations/). +Setup involves two steps powered by the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/). For more instructions, see [Integrations Overview](/platform/integrations/). #### 1. Create an environment @@ -116,8 +116,8 @@ The CLI will open a browser window prompting you to install the Warp app into yo :::tip If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Linear authorization) +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Linear authorization) ::: --- @@ -134,7 +134,7 @@ To remove the Warp app from Linear: <VideoEmbed url="https://www.loom.com/share/2f1648586d8148dc80561c00a09ca334" title="Uninstalling the Warp Linear integration video" /> -After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). +After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. Events for a disabled integration can return [`integration_disabled`](/factories/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting diff --git a/src/content/docs/platform/integrations/quickstart-github-actions.mdx b/src/content/docs/platform/integrations/quickstart-github-actions.mdx index 54830ef12..dee39ef26 100644 --- a/src/content/docs/platform/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/platform/integrations/quickstart-github-actions.mdx @@ -14,7 +14,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git ## Prerequisites -* **Warp API key** - Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. Use a personal key if the agent should commit as you, or an agent key (which runs as a [cloud agent](/platform/agents/) on your team) with [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). See [API Keys](/reference/cli/api-keys/) for the full creation flow. +* **Warp API key** - Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. Use a personal key if the agent should commit as you, or an agent key (which runs as a [cloud agent](/platform/agents/) on your team) with [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). See [API Keys](/agents/cli/oz-cli/api-keys/) for the full creation flow. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. --- diff --git a/src/content/docs/platform/integrations/quickstart.mdx b/src/content/docs/platform/integrations/quickstart.mdx index 1db093854..7b1c1dc33 100644 --- a/src/content/docs/platform/integrations/quickstart.mdx +++ b/src/content/docs/platform/integrations/quickstart.mdx @@ -47,8 +47,8 @@ Replace `<ENV_ID>` with your environment ID (see [Environments](/platform/enviro :::tip If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) ::: To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag: @@ -85,5 +85,5 @@ When the task is complete, Warp posts a summary back to the original Slack threa ## Next steps * **Customize agent behavior** - Use a [skill](/platform/skills-as-agents/) as the base prompt for your integration to give agents consistent, reusable instructions across every run. -* **Trigger agents programmatically** - Use the [API & SDK](/reference/api-and-sdk/) to build custom automations and integrations on top of agents. +* **Trigger agents programmatically** - Use the [API & SDK](/factories/api-and-sdk/) to build custom automations and integrations on top of agents. * **Read the full Slack reference** - [Slack](/platform/integrations/slack/) covers identity mapping, team access, monitoring runs, troubleshooting, and uninstall instructions. diff --git a/src/content/docs/platform/integrations/slack.mdx b/src/content/docs/platform/integrations/slack.mdx index a89b0ea6f..275641de6 100644 --- a/src/content/docs/platform/integrations/slack.mdx +++ b/src/content/docs/platform/integrations/slack.mdx @@ -19,7 +19,7 @@ The Slack integration lets your team trigger cloud agents directly from Slack co 3. After installing, you're returned to the Integrations page to finish setup: choose the [environment](/platform/environments/) agents should use, which defines the repos, Docker image, and setup commands. 4. Start using Warp in Slack by mentioning **@Warp** with a task. -Alternatively, install via the [{VARS.WARP_AGENT_CLI}](/reference/cli/): +Alternatively, install via the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/): ``` oz integration create slack --environment <ENV_ID> @@ -31,7 +31,7 @@ The CLI opens a browser window to install the Warp app into your Slack workspace * **Team membership** - The Slack integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must have cloud agents enabled and credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details. -* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/platform/self-hosting/) on their own infrastructure. +* **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/factories/self-hosting/) on their own infrastructure. --- @@ -137,8 +137,8 @@ oz integration create slack \ :::tip If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Common errors include: -* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) -* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) +* [`feature_not_available`](/factories/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations) +* [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization) ::: ### Identity mapping and team access @@ -172,7 +172,7 @@ To remove the Warp app from your Slack workspace: ![Confirmation dialog to remove the Warp app from a Slack workspace.](../../../../assets/agent-platform/remove-slack-app.png) -Once removed, Slack will immediately disable the integration for all teammates. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/). +Once removed, Slack will immediately disable the integration for all teammates. Events for a disabled integration can return [`integration_disabled`](/factories/api-and-sdk/troubleshooting/errors/integration-disabled/). ### Troubleshooting diff --git a/src/content/docs/platform/managing-cloud-agents.mdx b/src/content/docs/platform/managing-cloud-agents.mdx index 46b1cdbc2..f4c606492 100644 --- a/src/content/docs/platform/managing-cloud-agents.mdx +++ b/src/content/docs/platform/managing-cloud-agents.mdx @@ -13,6 +13,8 @@ Warp provides two management surfaces for tracking and observing agent activity Use these surfaces as the starting point for real-time agent observability in Warp. They help you see which agents are active, which runs are blocked or failed, where each run started, and which session link opens the prompt, plan, commands, logs, outputs, and follow-up messages behind the work. +To inspect work from one factory, use that factory's [Runs page](/factories/factory-dashboard/#inspect-runs). This page remains the reference for interactive and standalone cloud-agent management. + The Agent Management Panel and {VARS.WEB_APP} Runs page are designed to answer, at a glance: * Which agents are active or have been running recently. @@ -82,8 +84,8 @@ Each row represents a single item in the agents list (either an interactive conv Where the agent was launched from. Common sources include: * **Interactive:** an [agent conversation](/agents/) started in the Warp app -* **CLI**: a local run triggered by the [{VARS.WARP_AGENT_CLI}](/reference/cli/) -* **API**: a run triggered by [Warp's API](/reference/api-and-sdk/) +* **CLI**: a local run triggered by the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) +* **API**: a run triggered by [Warp's API](/factories/api-and-sdk/) * **Slack / Linear**: runs triggered by [integrations](/platform/integrations/) * **Scheduled**: runs triggered on a [cron schedule](/platform/triggers/scheduled-agents/) @@ -91,7 +93,7 @@ Where the agent was launched from. Common sources include: Warp uses a small set of statuses to help you quickly identify what needs attention: -<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td><p><em>(interactive only)</em></p><p><br />the conversation is waiting on user input or a required step</p></td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><a href="/reference/api-and-sdk/troubleshooting/errors/"><code>Failed / Errored</code></a></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table> +<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td><p><em>(interactive only)</em></p><p><br />the conversation is waiting on user input or a required step</p></td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><a href="/factories/api-and-sdk/troubleshooting/errors/"><code>Failed / Errored</code></a></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table> **Duration (for cloud agent tasks)** diff --git a/src/content/docs/platform/mcp.mdx b/src/content/docs/platform/mcp.mdx index 1105a7ce2..6dbb95772 100644 --- a/src/content/docs/platform/mcp.mdx +++ b/src/content/docs/platform/mcp.mdx @@ -24,9 +24,11 @@ The agent calls MCP tools automatically based on what the task requires, without You can supply MCP configuration in two ways: -* **At run time** — pass `--mcp` when calling `oz agent run` or `oz agent run-cloud`. See [MCP Servers](/reference/cli/mcp-servers/) in the CLI reference for the full syntax. +* **At run time** — pass `--mcp` when calling `oz agent run` or `oz agent run-cloud`. See [MCP Servers](/agents/cli/oz-cli/mcp-servers/) in the CLI reference for the full syntax. * **In an agent config file** — define `mcp_servers` directly in a YAML or JSON agent config file (passed with `-f / --file`). This is the recommended approach for repeatable workflows. +For factory work, declare factory-wide or per-agent MCP servers in the [factory definition](/factories/factory-as-code/#mcpservers). Use [Factory MCP](/factories/factory-mcp/) to connect an external coding agent to a factory. + ## Configuration schema Each MCP server entry is keyed by a name you choose. A server config must have **exactly one** transport type: @@ -133,7 +135,7 @@ Token- or header-based authentication on a `url` server, `env`-based secrets on ## Learn more * [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/) — choose between local, cloud, and shared MCP setup paths -* [MCP Servers (CLI reference)](/reference/cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag +* [MCP Servers (CLI reference)](/agents/cli/oz-cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag * [Model Context Protocol (MCP)](/agents/capabilities/mcp/) — configuring MCP servers in Warp for local agents * [Environments](/platform/environments/) — set up the runtime context (repo, image, startup commands) for cloud agent tasks * [Secrets](/platform/secrets/) — store and inject credentials into agent runs safely diff --git a/src/content/docs/platform/orchestration/index.mdx b/src/content/docs/platform/orchestration/index.mdx index 753c2afd5..82b5b5b2a 100644 --- a/src/content/docs/platform/orchestration/index.mdx +++ b/src/content/docs/platform/orchestration/index.mdx @@ -7,7 +7,7 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent's output. The parent/child model works from the Warp app, the [{VARS.WARP_AGENT_CLI}](/reference/cli/), and the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), and supports local, cloud, and mixed execution. +Multi-agent orchestration lets one agent spawn and coordinate other agents to parallelize work, delegate specialized tasks, or verify another agent's output. The parent/child model works from the Warp app, the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), and the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), and supports local, cloud, and mixed execution. Watch this walkthrough to see how a cloud agent can coordinate a team of agents in the cloud. @@ -15,7 +15,7 @@ Watch this walkthrough to see how a cloud agent can coordinate a team of agents To start an orchestrated run, see [Running orchestrated agents](/platform/orchestration/multi-agent-runs/). -To orchestrate work inside a [Warp factory](/factories/), dispatch through the [factory API](/factories/factory-api/) instead of calling `POST /agent/runs` with the foreman's `agent_identity_uid` directly. The server resolves the foreman for you, and everything on this page still applies to the run it starts. +To orchestrate work inside a [Warp factory](/factories/), dispatch through [factory endpoints](/factories/factory-api/) instead of calling `POST /agent/runs` with the foreman's `agent_identity_uid` directly. The server resolves the foreman for you, and everything on this page still applies to the run it starts. ## The parent/child model @@ -24,7 +24,7 @@ An orchestrated workflow always has one **parent agent** and one or more **child * **Parent agent** - the agent that decides what work needs to be done, spawns child agents, and (optionally) merges their results. Any agent can become a parent the first time it spawns a child. * **Child agent** - an agent spawned by a parent with its own prompt, environment, and (optionally) a different model or agent runtime. A child runs its own work and reports back; it does not spawn its own children. -Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [{VARS.WEB_APP}](/platform/oz-web-app/), and the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. +Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [{VARS.WEB_APP}](/platform/oz-web-app/), and the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. ### Where parent and child agents can run @@ -63,7 +63,7 @@ Track run state transitions in these places: * **The parent's transcript** - the parent agent receives child state transitions as it runs and reflects them in its own conversation. * **The orchestration pill bar** - in the Warp app, while you're viewing the parent agent, a horizontal pill bar above the agent view header shows the parent on the left and one pill per child. Each pill displays the child's name and a status badge that updates live. Click a pill to switch the pane to that child's conversation in place; click the parent pill to switch back. * **The {VARS.WEB_APP}** - cloud children appear under the parent on the <a href={`${VARS.WEB_APP_URL}/runs`}>Runs page</a> and in the parent's **Sub-agents** tab, with their status updating live. -* **The {VARS.API_SDK_NAME}** - `GET /agent/runs/{runId}` returns the latest state of any run, and `GET /agent/runs?ancestor_run_id=PARENT_RUN_ID` lists every descendant in one call. +* **The {VARS.WARP_PLATFORM_API}** - `GET /agent/runs/{runId}` returns the latest state of any run, and `GET /agent/runs?ancestor_run_id=PARENT_RUN_ID` lists every descendant in one call. ## Messaging between agents @@ -124,13 +124,13 @@ Because every parent and child is tracked as its own conversation or run, the ex * **[Managing cloud agents](/platform/managing-cloud-agents/)** - in the Warp app, the orchestration pill bar above the agent view header lets you switch between the parent and each child while you're viewing the parent. Cloud children also appear as their own rows in the Agent Management Panel list. * **[{VARS.WEB_APP}](/platform/oz-web-app/)** - the Runs page groups cloud children under the parent's row, and the parent's detail pane adds a **Sub-agents** tab. -* **[{VARS.API_SDK_NAME}](/reference/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts). +* **[{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/)** - list every descendant of a parent in one call and fetch any run with its conversation, transcript, and artifacts. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/#retrieving-conversations-and-artifacts). * **[Agent notifications](/agents/capabilities/agent-notifications/)** - in-app notifications fire on the parent agent's conversation only. Use the pill bar or the **Sub-agents** tab to drill into a specific child. ## Related pages * [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) - how to start an orchestrated run from the CLI, slash command, web app, or API. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical guidance for splitting tasks, assigning worktrees, validating child output, and handing work off for review. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - REST endpoints for runs, conversations, and artifacts. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - REST endpoints for runs, conversations, and artifacts. * [Cloud agents overview](/platform/) - what a cloud agent run is and how it fits into the {VARS.WARP_AUTOMATION_PLATFORM}. -* [Deployment patterns](/platform/deployment-patterns/) - higher-level deployment models that orchestration composes with. +* [Deployment patterns](/factories/deployment-patterns/) - higher-level deployment models that orchestration composes with. diff --git a/src/content/docs/platform/orchestration/multi-agent-runs.mdx b/src/content/docs/platform/orchestration/multi-agent-runs.mdx index 1b231cda8..9878a7f2f 100644 --- a/src/content/docs/platform/orchestration/multi-agent-runs.mdx +++ b/src/content/docs/platform/orchestration/multi-agent-runs.mdx @@ -1,13 +1,13 @@ --- title: Running orchestrated agents -description: Start multi-agent orchestrations from the Warp app, the {{WARP_AGENT_CLI}}, the {{WEB_APP}}, or the {{API_SDK_NAME}}, and inspect parent and child conversations and artifacts. +description: Start multi-agent orchestrations from the Warp app, the {{WARP_AGENT_CLI}}, the {{WEB_APP}}, or the {{WARP_PLATFORM_API}}, and inspect parent and child conversations and artifacts. sidebar: label: "Running orchestrated agents" --- import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -An orchestrated run starts with a parent agent that spawns one or more child agents. You can start a parent from the Warp app, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.API_SDK_NAME}. Use orchestrated runs to review a plan before fan-out, execute children locally or in the cloud, and inspect parent and child conversations as they work. +An orchestrated run starts with a parent agent that spawns one or more child agents. You can start a parent from the Warp app, the {VARS.WARP_AGENT_CLI}, the {VARS.WEB_APP}, or the {VARS.WARP_PLATFORM_API}. Use orchestrated runs to review a plan before fan-out, execute children locally or in the cloud, and inspect parent and child conversations as they work. Watch this walkthrough to see how to start and inspect an orchestrated agent run from Warp. @@ -18,9 +18,9 @@ Watch this walkthrough to see how to start and inspect an orchestrated agent run Pick where the parent will run. Every orchestration starts with a single parent that spawns children: * **Parent in the Warp app** - use the `/orchestrate` or `/plan` slash command. This is the fastest way to try orchestration. -* **Parent in the cloud** - trigger the parent through the {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), any [integration](/platform/integrations/) such as [Slack](/platform/integrations/slack/) or [Linear](/platform/integrations/linear/), or a [schedule](/platform/triggers/scheduled-agents/). The parent runs in an environment and spawns children from there. +* **Parent in the cloud** - trigger the parent through the {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), any [integration](/platform/integrations/) such as [Slack](/platform/integrations/slack/) or [Linear](/platform/integrations/linear/), or a [schedule](/platform/triggers/scheduled-agents/). The parent runs in an environment and spawns children from there. -Cloud parents that spawn cloud children need access to one or more [environments](/platform/environments/) the children can run in. To keep child execution on your own infrastructure, route those children to a [self-hosted worker](/platform/self-hosting/). +Cloud parents that spawn cloud children need access to one or more [environments](/platform/environments/) the children can run in. To keep child execution on your own infrastructure, route those children to a [self-hosted worker](/factories/self-hosting/). ## Starting an orchestrated run from Warp @@ -79,7 +79,7 @@ The parent run starts and children appear in the Runs list as the parent spawns Spawn the parent with `POST /agent/runs`. Children can either be spawned by the parent agent at runtime, or you can spawn each child explicitly from your code and link it to the parent with `parent_run_id`. Once they're running, coordination between the parent and its children flows through Warp's durable agent-to-agent messaging - see [Messaging between agents](/platform/orchestration/#messaging-between-agents) for the model. -This section spawns a standalone parent run. If the parent you want to start is a [Warp factory](/factories/)'s foreman, use the [factory API](/factories/factory-api/) to dispatch by factory UID instead of looking up the foreman's `agent_identity_uid` and calling `POST /agent/run` directly. +This section spawns a standalone parent run. If the parent you want to start is a [Warp factory](/factories/)'s foreman, use [factory endpoints](/factories/factory-api/) to dispatch by factory UID instead of looking up the foreman's `agent_identity_uid` and calling `POST /agent/run` directly. ### Agent-driven orchestration @@ -151,7 +151,7 @@ done ## Retrieving conversations and artifacts -Every parent and child started through the {VARS.API_SDK_NAME} is tracked as a {VARS.PLATFORM_RUN}. Run responses include the run's `state`, `parent_run_id` (set on children only), `conversation_id`, `session_link`, and an `artifacts` array of any pull requests, plans, screenshots, or files the run produced. Use the same endpoints you'd use for any other run: +Every parent and child started through the {VARS.WARP_PLATFORM_API} is tracked as a {VARS.PLATFORM_RUN}. Run responses include the run's `state`, `parent_run_id` (set on children only), `conversation_id`, `session_link`, and an `artifacts` array of any pull requests, plans, screenshots, or files the run produced. Use the same endpoints you'd use for any other run: * **List every descendant of a parent** - `GET /api/v1/agent/runs?ancestor_run_id=YOUR_PARENT_RUN_ID`. From the CLI: `oz run list --ancestor-run YOUR_PARENT_RUN_ID`. * **Get one run's details and artifacts** - `GET /api/v1/agent/runs/YOUR_RUN_ID`. @@ -193,10 +193,10 @@ Self-hosted, local, and GitHub Action runs cannot be cancelled through this endp * [Multi-agent orchestration](/platform/orchestration/) - parent/child model, run state transitions, and common patterns. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical task decomposition, worktree ownership, validation, and review handoff guidance. -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) - command reference for `oz agent run-cloud` and `oz run`. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - full HTTP reference and typed SDKs. +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) - command reference for `oz agent run-cloud` and `oz run`. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - full HTTP reference and typed SDKs. * [Managing cloud agents](/platform/managing-cloud-agents/) - how parent and child runs appear in the Agent Management Panel in the Warp app and the Runs page in the {VARS.WEB_APP}. * [Scheduled agents](/platform/triggers/scheduled-agents/) - start a recurring cloud parent that fans out children on a cron cadence. -* [Self-hosting](/platform/self-hosting/) - keep parent or child execution on your infrastructure while Warp tracks the runs. +* [Self-hosting](/factories/self-hosting/) - keep parent or child execution on your infrastructure while Warp tracks the runs. * [Handoff between local and cloud agents](/platform/handoff/) - promote a local parent to the cloud, or continue a finished cloud parent with a follow-up. * [Environments](/platform/environments/) - configure the runtime context cloud children execute in. diff --git a/src/content/docs/platform/overview.mdx b/src/content/docs/platform/overview.mdx index eee34d36b..aa656eee6 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -9,18 +9,10 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -[Cloud agents](/platform/) run on the {VARS.WARP_AUTOMATION_PLATFORM}. You define the work (a prompt or a skill) and what starts it, and the platform runs the agent and records what it did. For example, an agent can triage each new issue as it's filed, or start fixing a build the moment CI fails. +[Cloud agents](/platform/) run on the {VARS.WARP_AUTOMATION_PLATFORM}. You define a task and its trigger. The {VARS.WARP_AUTOMATION_PLATFORM} runs the agent and records the results. For example, an agent can triage each new issue as it's filed, or start fixing a build the moment CI fails. If you're new to cloud agents, the [Cloud agents quickstart](/platform/quickstart/) gets you to your first run in about ten minutes. -{/* Transition notice for the 2026-08-18 rename. Remove after 2026-10-06, when - the CLI and web app take their new names and the old one stops appearing. */} -:::note -**Oz is now the {VARS.WARP_AUTOMATION_PLATFORM}.** Only the name changed. Your existing integrations, API keys, scheduled agents, and scripts keep working exactly as before — nothing to migrate. - -The `oz` CLI and the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> keep the Oz name until October 6, 2026, which is why you'll still see it in commands and URLs. -::: - <VideoEmbed url="https://youtu.be/poLkJhO7fdo" title={`${VARS.WARP_AUTOMATION_PLATFORM} cloud agents overview video`} /> ## How a run works @@ -36,13 +28,13 @@ Every run follows the same path, whatever starts it: ## Integrations and triggers -Every run starts with a trigger. [Integrations](/platform/integrations/) turn events in other tools into runs: mention @warp in [Slack](/platform/integrations/slack/) and the agent gets the message and its thread, or run agents inside your [GitHub Actions](/platform/integrations/github-actions/) workflows with your CI context. [Scheduled agents](/platform/triggers/scheduled-agents/) start runs on a cron schedule. For event sources Warp doesn't cover, receive the event in your own system and start the run through the [API](/reference/api-and-sdk/); it becomes a normal, fully tracked task. +Every run starts with a trigger. [Integrations](/platform/integrations/) turn events in other tools into runs: mention @warp in [Slack](/platform/integrations/slack/) and the agent gets the message and its thread, or run agents inside your [GitHub Actions](/platform/integrations/github-actions/) workflows with your CI context. [Scheduled agents](/platform/triggers/scheduled-agents/) start runs on a cron schedule. For event sources Warp doesn't cover, receive the event in your own system and start the run through the [API](/factories/api-and-sdk/); it becomes a normal, fully tracked task. -Set up a first-party integration with `oz integration create` on the {VARS.WARP_AGENT_CLI}; the [integration setup guide](/reference/cli/integration-setup/) covers it end to end. +Set up a first-party integration with `oz integration create` on the {VARS.WARP_AGENT_CLI}; the [integration setup guide](/agents/cli/oz-cli/integration-setup/) covers it end to end. ## Tasks and tracking -Warp tracks every run as a task: its status, transcript, and outputs stay available after the run finishes. Watch or steer a live run with [session sharing](/agents/local-agents/session-sharing/), browse history in the [management UI](/platform/managing-cloud-agents/), or query it from the [{VARS.WARP_AGENT_CLI}](/reference/cli/) and the [API](/reference/api-and-sdk/). Access control decides who can run, view, or intervene in tasks. +Warp tracks every run as a task: its status, transcript, and outputs stay available after the run finishes. Watch or steer a live run with [session sharing](/agents/local-agents/session-sharing/), browse history in the [management UI](/platform/managing-cloud-agents/), or query it from the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) and the [API](/factories/api-and-sdk/). Access control decides who can run, view, or intervene in tasks. To fan work out across parent and child agents, see [multi-agent orchestration](/platform/orchestration/). @@ -52,17 +44,17 @@ An [environment](/platform/environments/) defines what a run needs: a Docker ima ## Hosts -A host is where the agent executes. By default runs execute on [Warp-hosted infrastructure](/platform/warp-hosting/), with nothing to set up. On Enterprise plans, [self-hosted runners](/platform/self-hosting/) keep code and execution inside your own network while Warp still tracks the runs. +A host is where the agent executes. By default runs execute on [Warp-hosted infrastructure](/factories/warp-hosting/), with nothing to set up. On Enterprise plans, [self-hosted runners](/factories/self-hosting/) keep code and execution inside your own network while Warp still tracks the runs. ![Architecture diagram: Warp-designed and customer-defined triggers create an agent task, which is routed to agent runners on Warp or customer infrastructure](../../../assets/agent-platform/platform-architecture.png) ## The CLI -The [{VARS.WARP_AGENT_CLI}](/reference/cli/) starts and manages runs where there's no UI: CI jobs, scripts, and remote servers. Start a run with `oz agent run`, and it reports progress to Warp like any other task, so work that starts on a CI runner shows up alongside everything else your team runs. For interactive sessions, use [agents in the Warp app](/agents/). +The [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) starts and manages runs where there's no UI: CI jobs, scripts, and remote servers. Start a run with `oz agent run`, and it reports progress to Warp like any other task, so work that starts on a CI runner shows up alongside everything else your team runs. For interactive sessions, use [agents in the Warp app](/agents/). ## API and SDKs -The [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) creates and inspects tasks over HTTP: submit a prompt with optional configuration, poll status, and fetch results with full provenance. Teams use it to start agents from incident tooling and internal systems, build dashboards over run history, and coordinate large batches of runs. Official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs add typed requests and responses, built-in retries, and consistent errors. Start with an SDK unless you need full control over your HTTP client. +The [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) creates and inspects tasks over HTTP: submit a prompt with optional configuration, poll status, and fetch results with full provenance. Teams use it to start agents from incident tooling and internal systems, build dashboards over run history, and coordinate large batches of runs. Official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs add typed requests and responses, built-in retries, and consistent errors. Start with an SDK unless you need full control over your HTTP client. ## Secrets @@ -82,4 +74,4 @@ Runs pick up your team's shared setup no matter what triggered them: [MCP server * [Cloud agents](/platform/) - what cloud agents are, how they get triggered, and how to run them with or without the Warp app. * [Cloud agents quickstart](/platform/quickstart/) - run your first cloud agent in about ten minutes. * [Environments](/platform/environments/) - define the toolchain and repos a run executes against. -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - drive the platform programmatically. +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - drive the platform programmatically. diff --git a/src/content/docs/platform/oz-web-app.mdx b/src/content/docs/platform/oz-web-app.mdx index b40860d23..12fc8807d 100644 --- a/src/content/docs/platform/oz-web-app.mdx +++ b/src/content/docs/platform/oz-web-app.mdx @@ -38,7 +38,7 @@ The {VARS.WEB_APP} is ideal when you want to: * **Configure environments** — Set up repos, Docker images, and setup commands through a form-based flow * **Set up integrations** — Connect Slack and Linear with a guided setup flow, and configure how [GitHub](/platform/integrations/github/) mention-triggered runs execute -For scripting, automation, and CI/CD workflows, use the [{VARS.WARP_AGENT_CLI}](/reference/cli/) or [API](/reference/api-and-sdk/). +For scripting, automation, and CI/CD workflows, use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) or [API](/factories/api-and-sdk/). ## Getting started @@ -217,7 +217,7 @@ To create a new environment: 6. Click **Create environment**. The environment appears on the Environments page. :::note -For advanced environment configuration, see [Environments](/platform/environments/) and the [CLI reference](/reference/cli/integration-setup/). +For advanced environment configuration, see [Environments](/platform/environments/) and the [CLI reference](/agents/cli/oz-cli/integration-setup/). ::: ## Integrations @@ -251,5 +251,5 @@ For detailed integration setup instructions, see [Slack](/platform/integrations/ * [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [Environments](/platform/environments/) — Configure runtime context for cloud agents * [Managing Cloud Agents](/platform/managing-cloud-agents/) — Monitor agent activity and inspect runs -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — Command-line interface for running agents -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — Programmatic access to cloud agents +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Command-line interface for running agents +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — Programmatic access to cloud agents diff --git a/src/content/docs/platform/quickstart.mdx b/src/content/docs/platform/quickstart.mdx index b597b592c..dc62652c9 100644 --- a/src/content/docs/platform/quickstart.mdx +++ b/src/content/docs/platform/quickstart.mdx @@ -102,7 +102,7 @@ Follow the prompts to save your task definition. Once created, you can run it ag **How this works:** Skills capture successful agent workflows as reusable building blocks. Instead of typing the same prompt repeatedly, you define it once. You can use it yourself, share it with teammates, schedule it to run automatically, or trigger it from integrations. Learn more about [Skills as Agents](/platform/skills-as-agents/). -**Prefer using the CLI?** See the [{VARS.WARP_AGENT_CLI} quickstart](/reference/cli/quickstart/) for CLI-based workflows. +**Prefer using the CLI?** See the [{VARS.WARP_AGENT_CLI} quickstart](/agents/cli/oz-cli/quickstart/) for CLI-based workflows. --- @@ -114,7 +114,7 @@ Now that you've run your first cloud agent, try these next steps: * [**Trigger agents from Slack or Linear**](/platform/integrations/quickstart/) - Connect Warp to team tools so mentions and issue updates can launch cloud agent runs. * [**Orchestrate multiple agents**](/platform/orchestration/multi-agent-runs/) - Fan work out across parent and child agents for large refactors, PR review swarms, and parallel package migrations. * [**Turn successful prompts into reusable skills**](/platform/skills-as-agents/) - Save repeatable agent workflows and run them again from the CLI, web app, API, or a schedule. -* [**Build programmatic automations**](/reference/api-and-sdk/quickstart/) - Start cloud agent runs from your own systems with the {VARS.API_SDK_NAME}. +* [**Build programmatic automations**](/factories/api-and-sdk/quickstart/) - Start cloud agent runs from your own systems with the {VARS.WARP_PLATFORM_API}. For example, schedule a recurring agent from the CLI: @@ -135,13 +135,13 @@ Integrations require a team on Build, Max, or Business plan. ## Troubleshooting **Environment creation fails**\ -Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/platform/environments/) for more guidance on choosing Docker images and [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the related API error. +Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/platform/environments/) for more guidance on choosing Docker images and [`environment_setup_failed`](/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the related API error. **Agent can't access repos**\ -Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works) and [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). For automated workflows using an agent API key, make sure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`; permission mismatches can surface as [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/). +Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/agents/cli/oz-cli/integration-setup/#how-github-authorization-works) and [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/). For automated workflows using an agent API key, make sure [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`; permission mismatches can surface as [`not_authorized`](/factories/api-and-sdk/troubleshooting/errors/not-authorized/). **Not enough credits to run cloud agents**\ -Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. If a run is blocked because the billed principal has no remaining credits, see [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). +Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. If a run is blocked because the billed principal has no remaining credits, see [`insufficient_credits`](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/). **More resources** diff --git a/src/content/docs/platform/secrets.mdx b/src/content/docs/platform/secrets.mdx index e336eb55c..d11582d61 100644 --- a/src/content/docs/platform/secrets.mdx +++ b/src/content/docs/platform/secrets.mdx @@ -12,6 +12,8 @@ Cloud agents often need to interact with external systems such as APIs, database Warp-managed secrets are designed to work across [cloud agent](/platform/) and [integration](/platform/integrations/) triggers (CLI, Slack, Linear, and schedules), support both team-wide and personal credentials, and give engineering and security teams visibility into what agents can access. +For factory work, declare the managed secrets a factory or individual factory agent receives in its [factory definition](/factories/factory-as-code/#secrets). This page remains the reference for creating, scoping, and rotating the shared secrets. + **Warp-managed secrets are useful when:** * A cloud agent needs to call an API or CLI that does not support OAuth @@ -290,7 +292,7 @@ Individual runs can override which secrets the run receives by listing them on t * **Explicit list of secret names** - Only the listed secrets are injected. Any other secrets the caller can access are skipped for this run. * **Empty list** - The run opts out of all secret injection. No managed secrets are injected, even for triggers that would otherwise receive them. -Run-level scoping is exposed through the public REST API on the run config. See the [{VARS.API_SDK_NAME} reference](/reference/api-and-sdk/) for the exact field and shape. +Run-level scoping is exposed through the public REST API on the run config. See the [{VARS.WARP_PLATFORM_API} reference](/factories/api-and-sdk/) for the exact field and shape. :::note Secret names that don't exist in the caller's scope are silently skipped at injection time rather than failing the run. The run detail view surfaces any references that were requested but not resolved so you can spot typos or stale names. diff --git a/src/content/docs/platform/self-hosting/index.mdx b/src/content/docs/platform/self-hosting/index.mdx deleted file mode 100644 index baaa956c6..000000000 --- a/src/content/docs/platform/self-hosting/index.mdx +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: Self-hosting overview -description: >- - Run cloud agents on your own infrastructure with a managed worker daemon or - unmanaged CLI-based execution you control. ---- -import { VARS } from '@data/vars'; - -Self-hosting lets your team run cloud agent workloads on your own infrastructure instead of Warp-managed servers. You control the execution environment, compute resources, and network access. Repository clones, source files, build artifacts, runtime secrets, and agent execution workspaces stay on your infrastructure, and agents can reach services behind your VPN or firewall. - -**New to self-hosting?** Start with the [Self-hosting quickstart](/platform/self-hosting/quickstart/) to get a managed worker running on Docker in under 10 minutes. - -**Want a CLI-only path with no Docker requirement?** Jump straight to the [Unmanaged quickstart](/platform/self-hosting/unmanaged/#unmanaged-quickstart) to run `oz agent run` directly on any host. - -:::note -**Enterprise feature**: Self-hosted agents are available exclusively to teams on an Enterprise plan. To enable self-hosting for your team, [contact sales](https://www.warp.dev/contact-sales). -::: - -## Managed vs unmanaged - -Self-hosting has two architectures. The core distinction is **who orchestrates agent runs** — not who owns the compute. Both models keep code and execution on your infrastructure. - -* **Managed** — The {VARS.WARP_AUTOMATION_PLATFORM} orchestrates agent runs. You run the `oz-agent-worker` daemon on your infrastructure; it connects to the {VARS.WARP_AUTOMATION_PLATFORM} and waits for work. [Slack](/platform/integrations/slack/) mentions, Linear comments, [schedules](/platform/triggers/scheduled-agents/), API calls, and `oz agent run-cloud` commands all route tasks to your worker, which executes them in isolated Docker containers, Kubernetes Jobs, or directly on the host. Similar to a [GitHub self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners). -* **Unmanaged** — You orchestrate agent runs. You invoke `oz agent run` directly from your existing CI pipeline, Kubernetes pod, VM, or dev box. The {VARS.WARP_AUTOMATION_PLATFORM} provides session tracking and observability for each run, but does not start or stop agents for you. - -### At a glance - -| Aspect | **Managed** | **Unmanaged** | -| --- | --- | --- | -| **Who triggers runs** | The {VARS.WARP_AUTOMATION_PLATFORM} (Slack, Linear, schedules, API, `run-cloud`) | Your system (CI, cron, scripts) | -| **What runs on your infra** | Long-lived `oz-agent-worker` daemon | One-shot `oz agent run` invocations | -| **OS support** | Linux (macOS/Windows coming) | Linux, macOS, Windows | -| **Execution isolation** | Docker container, Kubernetes Job, or direct host | Whatever your host provides | -| **Automatic environment setup** | Yes (via Warp [environments](/platform/environments/)) | No (you manage it) | -| **Session tracking and steering** | Yes | Yes | - -The two architectures are not mutually exclusive. Some teams run managed workers for integration-triggered work and unmanaged agents in CI pipelines. The deployment models diagram on [Deployment patterns](/platform/deployment-patterns/) compares what runs where in each model. - -## How self-hosting works - -Warp uses a split-plane architecture: **execution happens on your infrastructure**, while **orchestration, session management, and LLM inference route through Warp's backend**. Agent interactions — including code context in session transcripts and LLM prompts — transit Warp's control plane under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or train on it. - -If your security requirement is "repository clones and execution must stay on our infrastructure," self-hosting is designed for that. If your requirement is "no code context can ever route through Warp or an external LLM provider," review [Security and networking](/platform/self-hosting/security-and-networking/) with your Warp account team before deploying. - -![Self-hosted execution architecture showing the managed worker on customer infrastructure connecting outbound to the Warp control plane](../../../../assets/agent-platform/customer-dedicated-saas.png) - -The [self-hosted execution flow](/platform/architecture/#self-hosted-execution-flow) reference explains each numbered step in the diagram. - -With any self-hosted architecture: - -* **Agent runs are tracked and steerable** — View status, metadata, and session transcripts in the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>, the Warp app, or via the [API/SDK](/reference/api-and-sdk/). Authorized teammates can attach to running sessions to monitor or steer agents. -* **Connectivity to Warp's backend is required** — Agents need outbound access to Warp for orchestration, session storage, and LLM inference. No inbound ports need to be opened. -* **Resource limits are controlled by your infrastructure** — Concurrency and compute are only limited by the machines you provision, not by Warp. - -:::note -Enterprise teams that need full control over LLM inference routing can use [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through their own cloud provider accounts. Cloud agent support varies by provider; see each provider's setup guide for details. -::: - ---- - -## Choosing an architecture - -:::caution -**OS support:** The managed architecture is **Linux-only** today (macOS and Windows support is coming). If you need agents to run on macOS or Windows, use the [unmanaged](/platform/self-hosting/unmanaged/) architecture, which works on any platform Warp supports. -::: - -Use these questions to decide between managed and unmanaged: - -1. **Do you need agents to run on Windows or macOS?** - * Yes → Use the [unmanaged](/platform/self-hosting/unmanaged/) architecture. Managed is Linux-only today. - * No, Linux works → Continue to the next question. -2. **Do you want the {VARS.WARP_AUTOMATION_PLATFORM} to handle starting and stopping agents** (from Slack, the web interface, the Warp app, schedules, or the API)? - * Yes → Use the [managed](#managed-architecture) architecture. - * No, you have your own triggering mechanism → Use the [unmanaged](/platform/self-hosting/unmanaged/) architecture. -3. **Can your development environment run in a Docker container or Kubernetes pod?** - * Yes, Docker → [Managed: Docker](/platform/self-hosting/managed-docker/) backend. - * Yes, Kubernetes → [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) backend. - * No (multi-service stacks that don't fit a single container, or environments where container runtimes aren't available) → [Unmanaged](/platform/self-hosting/unmanaged/) or [Managed: Direct](/platform/self-hosting/managed-direct/). -4. **Do you have your own orchestrator** (CI/CD, Kubernetes, internal job scheduler) **that starts agents on demand?** - * Yes → [Unmanaged](/platform/self-hosting/unmanaged/), using `oz agent run` as a drop-in. - * No → [Managed](#managed-architecture). - -### Choosing a managed backend - -The managed architecture supports three backends for task execution: - -1. **Are you deploying the worker into a Kubernetes cluster?** - * Yes → Use the [Kubernetes backend](/platform/self-hosting/managed-kubernetes/). Each task runs as a Kubernetes Job in your cluster; install with the included Helm chart. - * No → Continue. -2. **Is Docker available on your worker host?** - * Yes → Use the [Docker backend](/platform/self-hosting/managed-docker/) (default). Tasks run in isolated containers. - * No → Use the [Direct backend](/platform/self-hosting/managed-direct/). Tasks run directly on the host. -3. **Do you need container-level isolation between tasks?** - * Yes → [Docker](/platform/self-hosting/managed-docker/) or [Kubernetes](/platform/self-hosting/managed-kubernetes/) backend. - * No → Any backend works. -4. **Do you need Kubernetes-native scheduling, resource management, or policy enforcement?** - * Yes → [Kubernetes backend](/platform/self-hosting/managed-kubernetes/). - * No → [Docker](/platform/self-hosting/managed-docker/) or [Direct](/platform/self-hosting/managed-direct/) is simpler to set up. - ---- - -## Managed architecture - -With the managed architecture, you run the `oz-agent-worker` daemon on your infrastructure. The daemon connects to the {VARS.WARP_AUTOMATION_PLATFORM}'s backend, waits for tasks to be assigned to it, and executes those tasks on its host using one of three backends: - -* **[Docker backend](/platform/self-hosting/managed-docker/)** (default) — Runs each task in an isolated Docker container. -* **[Kubernetes backend](/platform/self-hosting/managed-kubernetes/)** — Runs each task as a Kubernetes Job in your cluster. -* **[Direct backend](/platform/self-hosting/managed-direct/)** — Runs each task directly on the host without a container runtime. - -The managed architecture enables full orchestration by the {VARS.WARP_AUTOMATION_PLATFORM} — it can remotely start agents via Slack, Linear, the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a>, the API/SDK, and the `oz agent run-cloud` command. Agents can access host resources through volume mounts (Docker), Kubernetes-native configuration (Kubernetes), and injected environment variables. - -## Unmanaged architecture - -With the [unmanaged architecture](/platform/self-hosting/unmanaged/), you run `oz agent run` inside your own orchestrator or dev environment. This works on any platform Warp supports (Linux, macOS, Windows), with no dependency on Docker or any other sandboxing platform. - -You're responsible for executing `oz agent run` on your infrastructure — similar to how you'd integrate Claude Code or Codex CLI. The agent runs directly on the host, which could itself be a Kubernetes pod, VM, container, or CI runner. - ---- - -## Routing runs to self-hosted workers - -This section applies to **all managed backends** (Docker, Kubernetes, and Direct). Once a worker is connected, route cloud agent runs to it by specifying the `--host` flag (or equivalent) with your worker ID. The `--host` value must match the `--worker-id` of a connected worker exactly. - -:::note -Unmanaged runs don't need routing — you invoke `oz agent run` directly on the host where you want the agent to execute. Routing is only relevant for managed workers. -::: - -### From the CLI - -```bash -oz agent run-cloud --prompt "Refactor the authentication module" --host "my-worker" -``` - -You can combine `--host` with any other `run-cloud` flags, such as `--environment`, `--model`, `--mcp`, `--skill`, `--computer-use`, and `--attach`. - -### From scheduled agents - -When creating or updating a schedule, specify the host: - -```bash -oz schedule create --name "daily-cleanup" \ - --cron "0 9 * * *" \ - --prompt "Run dead code cleanup" \ - --environment ENV_ID \ - --host "my-worker" - -oz schedule update SCHEDULE_ID --host "my-worker" -``` - -### From integrations - -When creating or updating an integration, specify the host: - -```bash -oz integration create slack --host "my-worker" ... -oz integration update linear --host "my-worker" ... -``` - -All tasks created through that integration route to your self-hosted worker. - -### From the API and SDKs - -When creating a run via the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), include `worker_host` in the config: - -```bash -curl -X POST https://app.warp.dev/api/v1/agent/run \ - --header 'Authorization: Bearer YOUR_API_KEY' \ - --header 'Content-Type: application/json' \ - --data '{ - "prompt": "Refactor the authentication module", - "config": { - "environment_id": "ENV_ID", - "worker_host": "my-worker" - } - }' -``` - -### From the web UI - -When creating a run, schedule, or integration in the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a>, select your self-hosted worker from the host dropdown. - ---- - -## Environments with self-hosted workers - -Self-hosted workers fully support [environments](/platform/environments/). When a task specifies an environment, the worker resolves the Docker image, clones the repositories, runs setup commands, and executes the agent inside the prepared container or Kubernetes Job. - -The same environment can be used for both Warp-hosted and self-hosted runs without modification. If your agents need custom tools, binaries, scripts, or system packages, add them to the environment's Docker image. See [Environments](/platform/environments/) for details on creating and configuring custom images. - -:::note -With the Kubernetes backend, setting a [`default_image`](/platform/self-hosting/reference/#kubernetes-backend-config) on the worker lets you skip creating a Warp environment when all your tasks use the same base image. -::: - -:::caution -Musl-based Docker images (such as Alpine Linux) are not supported as task images. The agent runtime requires glibc. Use glibc-based images like Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images. -::: - -## Monitoring runs - -Self-hosted runs have the same observability as Warp-hosted runs: - -* **Run history** — View task status, history, and metadata in the {VARS.DASHBOARD}, hosted in the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a>, or filter by source and status in the [Agent Management Panel](/platform/managing-cloud-agents/). -* **Session sharing** — Authorized teammates can attach to running tasks to [monitor progress](/platform/viewing-cloud-agent-runs/). -* **APIs and SDKs** — Query task history and build monitoring using the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). - -For infrastructure-level observability, the `oz-agent-worker` daemon can export OpenTelemetry metrics (worker health, task throughput, capacity saturation) to Prometheus, an OTLP collector, or the console. See [Monitoring](/platform/self-hosting/monitoring/) for setup, the full metric catalog, and sample PromQL queries. - ---- - -## Related pages - -* [Self-hosting quickstart](/platform/self-hosting/quickstart/) — Get a managed worker running in ~10 minutes. -* [Unmanaged](/platform/self-hosting/unmanaged/) — Run `oz agent run` in your CI, K8s, or dev environment. -* [Managed: Docker](/platform/self-hosting/managed-docker/) — Default managed setup with the Docker backend. -* [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Managed setup with the Kubernetes backend and Helm chart. -* [Managed: Direct](/platform/self-hosting/managed-direct/) — Managed setup with no container runtime. -* [Self-hosted worker reference](/platform/self-hosting/reference/) — CLI flags and config file schema. -* [Monitoring](/platform/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. -* [Security and networking](/platform/self-hosting/security-and-networking/) — Data boundaries, network egress, and security considerations. -* [Troubleshooting](/platform/self-hosting/troubleshooting/) — Worker won't start, tasks not picked up, and other common issues. -* [Deployment patterns](/platform/deployment-patterns/) — How self-hosting compares to CLI-only and Warp-hosted deployment. -* [Scheduled agents](/platform/triggers/scheduled-agents/) — Route recurring cloud agent work to a self-hosted worker with `--host`. -* [Integrations](/platform/integrations/) — Point Slack, Linear, and other triggers at a self-hosted worker. -* [Managing cloud agents](/platform/managing-cloud-agents/) — Inspect self-hosted runs alongside Warp-hosted ones. -* [Environments](/platform/environments/) — Define the runtime context for agent tasks. -* [Customizing workspace snapshots](/platform/handoff/snapshots/) — Configure end-of-run snapshots so handoff works when running outside the bundled cloud agent image. diff --git a/src/content/docs/platform/skills-as-agents.mdx b/src/content/docs/platform/skills-as-agents.mdx index e2e7d5ed7..d70e0fa49 100644 --- a/src/content/docs/platform/skills-as-agents.mdx +++ b/src/content/docs/platform/skills-as-agents.mdx @@ -12,6 +12,8 @@ You can start an agent from a [skill](/agents/capabilities/skills/)—a reusable Skills work with both **local agents** (running on your machine) and **cloud agents** (running in Warp's infrastructure). +Skills that run independently of a factory are covered here. For instructions scoped to a factory or one of its agents, see [factory skills](/factories/factory-skills/). + This is useful when you want: * **Consistent behavior** — The same skill produces the same workflow every time, regardless of who triggers it or where it runs. @@ -52,7 +54,7 @@ For cloud agent runs (`oz agent run-cloud`), skills are discovered from reposito 3. **The skill appears** in the Agents list in the {VARS.WEB_APP} :::note -You can also list available skills programmatically using the `GET /agent` endpoint. See the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) reference for details. +You can also list available skills programmatically using the `GET /agent` endpoint. See the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) reference for details. ::: ### Extra skill directories in cloud runs @@ -105,7 +107,7 @@ oz agent run-cloud \ --prompt "additional context" ``` -For full CLI documentation, see [Using skills](/reference/cli/#using-skills) in the CLI reference. +For full CLI documentation, see [Using skills](/agents/cli/oz-cli/#using-skills) in the CLI reference. ### API & SDK @@ -121,7 +123,7 @@ Use the `skill_spec` parameter when creating a run: } ``` -For full API documentation, see [Agent configuration](/reference/api-and-sdk/#agent-configuration) in the API reference. +For full API documentation, see [Agent configuration](/factories/api-and-sdk/#agent-configuration) in the API reference. --- @@ -164,5 +166,5 @@ Suggested skills appear on the Agents page under the **Suggested** filter. * [Environments](/platform/environments/) — Configure repositories and runtime context for cloud agents * [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [{VARS.WEB_APP}](/platform/oz-web-app/) — Visual interface for managing cloud agents -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — Command-line interface for running agents -* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — Programmatic access to cloud agents +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Command-line interface for running agents +* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) — Programmatic access to cloud agents diff --git a/src/content/docs/platform/team-access-billing-and-identity.mdx b/src/content/docs/platform/team-access-billing-and-identity.mdx index 094b0b384..0ff3590b0 100644 --- a/src/content/docs/platform/team-access-billing-and-identity.mdx +++ b/src/content/docs/platform/team-access-billing-and-identity.mdx @@ -38,7 +38,7 @@ Individual users can run cloud agents via the CLI or API without being part of a **How it works:** -* Run agents using `oz agent run-cloud` or the {VARS.API_SDK_NAME} +* Run agents using `oz agent run-cloud` or the {VARS.WARP_PLATFORM_API} * Credits are drawn from your Warp credits (including cloud agent credits, when applicable) * Agents execute on Warp-hosted infrastructure @@ -110,7 +110,7 @@ This ensures runs are scoped to what the user is allowed to see and modify, and By default, cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Warp Factories** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual's token. -This is useful for fully automated workflows that use an [agent API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. +This is useful for fully automated workflows that use an [agent API key](/agents/cli/oz-cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. ### How it works @@ -233,9 +233,9 @@ How credits are consumed depends on how the agent run is triggered and authentic * On Build, Max, and Business plans, Warp bills the team owner: the owner's plan-included credits, then the team's shared add-on credit pool. With auto-reload off, the request is blocked when both are depleted. With auto-reload on, usage can trigger a reload into the team's shared pool subject to the team-wide monthly spend cap. * On Enterprise plans, these runs draw from the team-scoped credit pool, per your Enterprise contract terms. * Ideal for CI/CD pipelines, scheduled tasks, and other automated workflows. -* For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Warp Factories GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. +* For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Warp Factories GitHub App. Alternatively, use a [personal API key](/agents/cli/oz-cli/api-keys/) to authenticate as an individual user. -For more details on creating and using API keys, see [API Keys](/reference/cli/api-keys/). +For more details on creating and using API keys, see [API Keys](/agents/cli/oz-cli/api-keys/). :::note When a user triggers an agent via Slack or Linear, the run still follows that same order — plan-included credits first, then shared team grants, then any applicable user-scoped grants — as long as the triggering user's identity can be mapped to their Warp account. @@ -263,9 +263,9 @@ It's the team's responsibility to manage triggers, confirm they behave as intend If a cloud agent or integration run fails with an error code, use the error reference to narrow the fix: -* **Missing GitHub or external authorization** - See [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) when a user needs to authorize GitHub, Slack, or Linear before a run can continue. -* **Insufficient repo permissions** - See [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/) when the triggering user or GitHub App lacks access to the repo the agent needs. -* **Credits or spend caps block a run** - See [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) or [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/) when the billed account has depleted credits or reached a configured spend cap. +* **Missing GitHub or external authorization** - See [`external_authentication_required`](/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/) when a user needs to authorize GitHub, Slack, or Linear before a run can continue. +* **Insufficient repo permissions** - See [`not_authorized`](/factories/api-and-sdk/troubleshooting/errors/not-authorized/) when the triggering user or GitHub App lacks access to the repo the agent needs. +* **Credits or spend caps block a run** - See [`insufficient_credits`](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/) or [`budget_exceeded`](/factories/api-and-sdk/troubleshooting/errors/budget-exceeded/) when the billed account has depleted credits or reached a configured spend cap. --- diff --git a/src/content/docs/platform/transitioning-from-oz.mdx b/src/content/docs/platform/transitioning-from-oz.mdx new file mode 100644 index 000000000..9a132166c --- /dev/null +++ b/src/content/docs/platform/transitioning-from-oz.mdx @@ -0,0 +1,42 @@ +--- +title: Transitioning from the {{WEB_APP}} +description: >- + Keep existing legacy web app, CLI, SDK, and API workflows while using Warp + Factories for new multi-stage software development workflows. +sidebar: + label: "Transitioning from the {{WEB_APP}}" +--- +import { VARS } from '@data/vars'; + +Warp Factories supports new multi-stage software development workflows. Existing users can continue using their current workflows without taking action. + +## Current status and future direction + +| Surface | Current status | Future direction | +| --- | --- | --- | +| **{VARS.WEB_APP}** | Existing workflows continue to work. | Existing workflows remain supported. Migration guidance will be available over time. | +| **{VARS.WARP_AGENT_CLI} (`oz`)** | Existing commands continue to work. | Relevant functionality moves toward the {VARS.WARP_CLI}. Warp will publish migration guidance before support changes. | +| **{VARS.WARP_CLI} (`warp`)** | Available for its current supported functionality. | The preferred direction for CLI functionality. | +| **`oz-sdk-python` and `oz-sdk-typescript`** | Existing SDK packages continue to work. | Packages may be renamed or repackaged under Warp with migration guidance. | +| **{VARS.WARP_PLATFORM_API}** | Existing endpoints continue to work; no endpoint migration is required. | Documentation and naming may change while compatibility remains. | +| **New software factories** | Use <a href={VARS.FACTORY_WEB_APP_URL}>Warp Factories</a> for new multi-stage development workflows. | Warp Factories remains the primary product experience for software factories. | + +## Moving an existing workflow + +### Existing web app workflows + +Continue using the <a href={VARS.WEB_APP_URL}>{VARS.WEB_APP}</a> for existing cloud agents, environments, schedules, integrations, and runs. Moving an existing workflow into a factory is optional. Contact your account team to evaluate the move for your workflow. + +### CLI functionality + +Continue using `oz` commands for existing workflows. Use the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) for current command reference and the [{VARS.WARP_CLI}](/agents/cli/) for current `warp` functionality. + +### SDK packages and API + +The official SDK repositories retain their current package names: [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript). Existing API integrations remain compatible as documentation moves to the [{VARS.WARP_PLATFORM_API}](/factories/developer-tools/). + +## Related pages + +* [{VARS.WARP_AUTOMATION_PLATFORM} overview](/platform/overview/) - Configure standalone cloud-agent workflows. +* [Warp Factories overview](/factories/) - Build and operate a standing software factory. +* [{VARS.WARP_PLATFORM_API} & SDKs](/factories/developer-tools/) - Use factory endpoints, Agent & run endpoints, SDKs, and API errors. diff --git a/src/content/docs/platform/triggers/index.mdx b/src/content/docs/platform/triggers/index.mdx index c30ca6039..490144081 100644 --- a/src/content/docs/platform/triggers/index.mdx +++ b/src/content/docs/platform/triggers/index.mdx @@ -8,6 +8,8 @@ import { VARS } from '@data/vars'; A trigger is anything that starts a cloud agent run without you typing a prompt: a recurring schedule, an integration like Slack or Linear, a CI event, or a call to the API. This page covers the full set, including the [integrations](/platform/integrations/) that connect agents to the tools your team already uses. +For triggers that route work through one factory's named agents and workflow, use [factory automations](/factories/automations/) and [factory integrations](/factories/connect-your-factory/). + To set up your first recurring agent, follow the [Scheduled Agents Quickstart](/platform/triggers/scheduled-agents-quickstart/). If you're choosing between schedules, Slack, Linear, GitHub, GitHub Actions, the {VARS.WARP_AGENT_CLI}, or the API, start with [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). @@ -15,8 +17,8 @@ If you're choosing between schedules, Slack, Linear, GitHub, GitHub Actions, the ## Available trigger types * **[Scheduled Agents](/platform/triggers/scheduled-agents/)** - Run agents on a recurring schedule using cron expressions. -* **[CLI](/reference/cli/)** - Trigger cloud agents directly from your terminal using the {VARS.WARP_AGENT_CLI}. -* **[API & SDK](/reference/api-and-sdk/)** - Programmatically trigger agents via the Warp API or SDK. +* **[CLI](/agents/cli/oz-cli/)** - Trigger cloud agents directly from your terminal using the {VARS.WARP_AGENT_CLI}. +* **[API & SDK](/factories/api-and-sdk/)** - Programmatically trigger agents via the Warp API or SDK. * **[Integrations](/platform/integrations/)** - Trigger agents from external services like Slack, Linear, or Jira. * **[GitHub](/platform/integrations/github/)** - Mention `@warp-agent` on an issue, pull request, or review comment to start an agent that replies in the thread. * **[GitHub Actions](/platform/integrations/github-actions/)** - Run agents from your own CI workflows and repository events. diff --git a/src/content/docs/platform/triggers/scheduled-agents.mdx b/src/content/docs/platform/triggers/scheduled-agents.mdx index f9e8b71f6..55e633cf1 100644 --- a/src/content/docs/platform/triggers/scheduled-agents.mdx +++ b/src/content/docs/platform/triggers/scheduled-agents.mdx @@ -69,7 +69,7 @@ Use `oz schedule create` (with required flags) to define a new Scheduled Agent. * A cron schedule. * A prompt or skill that the agent will execute. * An optional environment in which the agent will run. -* An optional [model selection](/reference/cli/#using-agent-profiles). +* An optional [model selection](/agents/cli/oz-cli/#using-agent-profiles). * [Optional MCP server configuration](/platform/mcp/). ```bash @@ -115,7 +115,7 @@ oz schedule create \ Once created, the agent will automatically run at the specified times without further action. -Scheduled Agents support the same [model selection](/reference/cli/) and [MCP server configuration](/platform/mcp/) as other cloud agent triggers. +Scheduled Agents support the same [model selection](/agents/cli/oz-cli/) and [MCP server configuration](/platform/mcp/) as other cloud agent triggers. #### Cron schedule format @@ -290,7 +290,7 @@ Each scheduled run behaves like a standard cloud agent run, with a few important * Runs execute automatically without human intervention. * All usage is billed to the team’s shared credit balance. -If a scheduled run fails, it does not block future runs. Each execution is independent. Use the [API error reference](/reference/api-and-sdk/troubleshooting/errors/) to interpret any returned error code. +If a scheduled run fails, it does not block future runs. Each execution is independent. Use the [API error reference](/factories/api-and-sdk/troubleshooting/errors/) to interpret any returned error code. ### Permissions and responsibility diff --git a/src/content/docs/platform/self-hosting/unmanaged.mdx b/src/content/docs/platform/unmanaged-execution.mdx similarity index 88% rename from src/content/docs/platform/self-hosting/unmanaged.mdx rename to src/content/docs/platform/unmanaged-execution.mdx index 49cf1d397..15df82c37 100644 --- a/src/content/docs/platform/self-hosting/unmanaged.mdx +++ b/src/content/docs/platform/unmanaged-execution.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; With the unmanaged architecture, **you orchestrate agent runs** by invoking `oz agent run` directly from your existing CI pipelines, Kubernetes pods, VMs, or dev boxes. The agent runs on whatever host the command is executed from; Warp tracks the session for you but does not start or stop agents. :::note -Unmanaged is the right choice if you already have a system that schedules work (CI, internal orchestrators, cron, dev environments). If you'd rather have the {VARS.WARP_AUTOMATION_PLATFORM} trigger and route runs from Slack, Linear, schedules, or the API, use the [managed architecture](/platform/self-hosting/#managed-architecture) instead. +Unmanaged is the right choice if you already have a system that schedules work (CI, internal orchestrators, cron, dev environments). If you'd rather have the {VARS.WARP_AUTOMATION_PLATFORM} trigger and route runs from Slack, Linear, schedules, or the API, use the [managed architecture](/factories/self-hosting/#managed-architecture) instead. ::: ## When to use unmanaged @@ -33,8 +33,8 @@ No Docker, no worker daemon, no environment required — just the {VARS.WARP_AGE ### Prerequisites -* **The {VARS.WARP_AGENT_CLI}** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. -* **A Warp API key** — For automation, create an agent API key in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. +* **The {VARS.WARP_AGENT_CLI}** installed on the machine where agents will run. See [Installing the CLI](/agents/cli/oz-cli/#installing-the-cli) for platform-specific instructions. +* **A Warp API key** — For automation, create an agent API key in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a>. See [API Keys](/agents/cli/oz-cli/api-keys/) for personal vs. agent guidance. ### 1. Authenticate @@ -123,7 +123,7 @@ Unmanaged agents are tracked on Warp's backend. Each run creates a persistent se * **View** in the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>. * **Attach to** via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer. -* **Query** through the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) for custom dashboards or monitoring. +* **Query** through the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) for custom dashboards or monitoring. Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/platform/mcp/), [secrets](/platform/secrets/), Warp Drive context, and saved prompts all apply. @@ -133,8 +133,8 @@ Unmanaged runs don't ship with the bundled declarations script, so end-of-run wo ## Related pages -* [Self-hosting overview](/platform/self-hosting/) — Compare managed and unmanaged, plus the architecture decision guide. +* [Self-hosting overview](/factories/self-hosting/) — Compare managed and unmanaged, plus the architecture decision guide. * [GitHub Actions integration](/platform/integrations/github-actions/) — Run agents in CI with the official action. -* [Deployment patterns](/platform/deployment-patterns/) — Pattern 1 (CLI-only) explains the unmanaged model conceptually. -* [{VARS.WARP_AGENT_CLI}](/reference/cli/) — Full CLI reference for `oz agent run` and related commands. +* [Deployment patterns](/factories/deployment-patterns/) — The Standalone CLI-only agents section describes the unmanaged model conceptually. +* [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/) — Full CLI reference for `oz agent run` and related commands. * [Agent Session Sharing](/agents/local-agents/session-sharing/) — Attach to running sessions to monitor or steer them. diff --git a/src/content/docs/platform/viewing-cloud-agent-runs.mdx b/src/content/docs/platform/viewing-cloud-agent-runs.mdx index 12cb6f3b1..54d9b0128 100644 --- a/src/content/docs/platform/viewing-cloud-agent-runs.mdx +++ b/src/content/docs/platform/viewing-cloud-agent-runs.mdx @@ -9,7 +9,7 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Cloud agent session sharing lets you open, inspect, and continue interacting with agent tasks that are running on remote virtual machines. Whether a cloud agent was triggered from [integrations](/platform/integrations/) like Slack, Linear, GitHub Actions, or the [{VARS.WARP_AGENT_CLI}](/reference/cli/), you can view its full session, follow along in real time, ask follow-up questions, and even "fork" the work into your local Warp environment. +Cloud agent session sharing lets you open, inspect, and continue interacting with agent tasks that are running on remote virtual machines. Whether a cloud agent was triggered from [integrations](/platform/integrations/) like Slack, Linear, GitHub Actions, or the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), you can view its full session, follow along in real time, ask follow-up questions, and even "fork" the work into your local Warp environment. Use cloud agent session sharing when you need to inspect a cloud agent run, debug a failed automation, or give teammates a shared record of what the agent did. The shared session is the review surface for the run: it shows the prompt, plan, commands, logs, outputs, and follow-up messages where available. @@ -37,7 +37,7 @@ Everything is accessible whether or not Warp is installed on the viewer’s mach #### 1. Open a remote cloud agent run -When a cloud agent starts working — for example, from a Slack mention, a Linear issue, or a [CLI](/reference/cli/) trigger — Warp attaches a shareable link to the run. +When a cloud agent starts working — for example, from a Slack mention, a Linear issue, or a [CLI](/agents/cli/oz-cli/) trigger — Warp attaches a shareable link to the run. * From [Slack](/platform/integrations/slack/), click **View Agent** in the agent response to open the session. * From [Linear](/platform/integrations/linear/), click the ↗ **Warp** button ("Open in Warp") on the ticket to open the session. diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx deleted file mode 100644 index 097333f4f..000000000 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: API Troubleshooting -description: >- - Troubleshooting resources for the {{API_SDK_NAME}}, including a full reference - for all platform error codes. ---- -import { VARS } from '@data/vars'; - -When the {VARS.API_SDK_NAME} encounters an error, it returns a structured response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807) with a machine-readable error code, HTTP status, and actionable resolution steps. - -## Resources - -* [**Errors**](/reference/api-and-sdk/troubleshooting/errors/) — Full reference for all API error codes, including causes, example responses, and resolution steps diff --git a/src/content/docs/reference/index.mdx b/src/content/docs/reference/index.mdx deleted file mode 100644 index 59996046e..000000000 --- a/src/content/docs/reference/index.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Technical reference -description: >- - Technical reference documentation for the {{WARP_AGENT_CLI}}, API, and SDK. ---- -import { VARS } from '@data/vars'; - -Technical reference documentation for the {VARS.WARP_AGENT_CLI}, API, and SDKs. Use these programmatic interfaces to run and manage agents from CI pipelines, scripts, backend services, and custom tooling without requiring the Warp desktop app. - -## CLI - -The [{VARS.WARP_AGENT_CLI}](/reference/cli/) lets you run and configure agents from any environment — locally, in CI pipelines, or on remote machines. - -- [API Keys](/reference/cli/api-keys/) - Create and manage API keys to authenticate the {VARS.WARP_AGENT_CLI} without human interaction, ideal for CI pipelines, headless servers, and containers. -- [Agent Profiles](/reference/cli/agent-profiles/) - Use agent profiles to control what the agent can access, how it behaves, and where it can act, including file access, command execution, and MCP server usage. -- [MCP Servers](/reference/cli/mcp-servers/) - Pass MCP server configuration to agent runs using the `--mcp` flag, by UUID, inline JSON, or file path. -- [Skills](/reference/cli/skills/) - Run agents from reusable instruction sets stored in your repositories using the `--skill` flag. -- [Warp Drive Context](/reference/cli/warp-drive/) - Reference saved prompts, notebooks, workflows, and rules from Warp Drive directly in CLI agent commands. -- [Integration Setup](/reference/cli/integration-setup/) - Configure environments and connect external tools like Slack and Linear so you can trigger agents from outside the terminal. -- [Troubleshooting](/reference/cli/troubleshooting/) - Find solutions to common CLI errors, including authentication issues, agent failures, environment problems, and Docker image issues. - -## API & SDK - -The [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) lets you create and monitor cloud agent runs over HTTP. Official SDKs for [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) provide typed clients with built-in retries and error handling. - -- [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) - example integration diff --git a/src/content/docs/support-and-community/plans-and-billing/credits.mdx b/src/content/docs/support-and-community/plans-and-billing/credits.mdx index 4d4cdf2dc..6d42f9ee4 100644 --- a/src/content/docs/support-and-community/plans-and-billing/credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/credits.mdx @@ -129,7 +129,7 @@ The following scenarios use compute credits: * **First-party integrations** - Running agents through Warp's integrations (Slack, Linear, GitHub, and others) * **Cloud agent runs** - Using `oz agent run-cloud` via the CLI -* **{VARS.API_SDK_NAME}** - Running agents through Warp's API +* **{VARS.WARP_PLATFORM_API}** - Running agents through Warp's API * **Cloud Mode** - Running an agent from Cloud Mode in the Warp app ### Not eligible for compute credits diff --git a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx index ceaf3c34a..f02dcf605 100644 --- a/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/pricing-faqs.mdx @@ -256,7 +256,7 @@ The waterfall is: When auto-reload is **off**, the request is blocked once both buckets are depleted. When auto-reload is **on**, cloud agent usage can trigger auto-reload into the team's shared pool subject to the team-wide spend cap; further cloud agent runs then draw from that reloaded balance until the cap is reached. -"Blocked" means the run fails immediately with an insufficient-credits error rather than queuing or retrying. For unattended runs (scheduled jobs, team-API-key triggers), this manifests as a failed run in the {VARS.DASHBOARD} with an [insufficient credits](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) error code; the run won't be retried automatically. Owners should monitor the dashboard and configure spend caps with headroom for critical scheduled workloads. +"Blocked" means the run fails immediately with an insufficient-credits error rather than queuing or retrying. For unattended runs (scheduled jobs, team-API-key triggers), this manifests as a failed run in the {VARS.DASHBOARD} with an [insufficient credits](/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/) error code; the run won't be retried automatically. Owners should monitor the dashboard and configure spend caps with headroom for critical scheduled workloads. :::note Enterprise plans support team-scoped credit pools, so this traffic draws from the team pool rather than an individual admin. See [enterprise billing](/enterprise/support-and-resources/billing/) for overage and contract terms. diff --git a/src/data/vars.ts b/src/data/vars.ts index eb2dab80c..36ff3f24c 100644 --- a/src/data/vars.ts +++ b/src/data/vars.ts @@ -7,9 +7,8 @@ // Use the future/conceptual name as the key; the value holds the current string. export const VARS = { - // Platform — renamed 8/18. The remaining Oz-valued keys below are the - // deliberate 10/6 holdouts: the `oz` binary and the Oz v1 webapp keep their - // names until that date, so they are NOT stale, they are pending. + // The `oz` binary and Oz web app are supported legacy surfaces. Their names + // remain in place while Warp publishes transition guidance for each surface. // // IMPORTANT: "Automation Platform" is a common-noun phrase, not a proper // noun like "Oz" was. Referential uses need a definite article in the prose @@ -17,9 +16,11 @@ export const VARS = { // attributive uses do not ("{{…}} settings", "{{…}}-hosted"). style_lint // enforces this. Do not add a bare referential use. WARP_AUTOMATION_PLATFORM: "Automation Platform", - WARP_AGENT_CLI: "Oz CLI", // the `oz` binary — holds until 10/6, then "Warp Agent CLI" - WEB_APP: "Oz web app", // legacy Oz v1 webapp (oz.warp.dev) — holds until 10/6 - WEB_APP_URL: "https://oz.warp.dev", // holds until 10/6, then "https://app.warp.dev" + // Legacy key retained for existing Oz CLI references. It refers only to the + // `oz` binary; use WARP_CLI for the separate Warp Agent CLI (`warp` binary). + WARP_AGENT_CLI: "Oz CLI", + WEB_APP: "Oz web app", + WEB_APP_URL: "https://oz.warp.dev", // Renamed per HYC (8/17), same shape as PLATFORM_RUN below: a plain // platform-level term, with "factory dashboard" written directly on pages // that are specifically about a factory. Lowercase: "Warp Factories" is the @@ -41,7 +42,7 @@ export const VARS = { // Kept singular so `{VARS.PLATFORM_RUN}s` pluralizes correctly at the call // sites that do that. PLATFORM_RUN: "cloud agent run", - API_SDK_NAME: "Oz API & SDK", // holds until 10/6, then "Warp API & SDK" + WARP_PLATFORM_API: "Warp Platform API", // Warp Factories web app — a net-new product surface at platform.warp.dev // (soft launch ~2026-08-18), separate from the legacy Oz v1 webapp above. @@ -50,17 +51,10 @@ export const VARS = { FACTORY_WEB_APP: "Warp Factories web app", FACTORY_WEB_APP_URL: "https://platform.warp.dev", - // Warp Agent CLI — the standalone terminal front-end (the `warp` binary). - // Launch name confirmed via the launch blog draft (2026-07-28). - // - // NOTE: the WARP_AGENT_CLI key above was reserved for renaming the Oz CLI to - // this same name. That overlap is now resolved by product direction: on - // 2026-10-06 (the same holdout date as the WARP_AGENT_CLI value above, not - // the 8/18 platform rename) the Oz CLI is retired and wrapped into the Warp - // Agent CLI, leaving a single CLI. The two keys are expected to collapse - // into one at that point. Keeping them separate until the convergence - // ships, since merging them now would rewrite prose across both CLI doc - // surfaces. + // Warp Agent CLI — the preferred direction for CLI functionality (the + // `warp` binary). This is distinct from WARP_AGENT_CLI, which references + // the legacy Oz CLI (`oz` binary). Relevant Oz CLI functionality will move + // here over time. WARP_CLI: "Warp Agent CLI", // Feature names (stable — keys and values expected to remain unchanged) diff --git a/src/pages/api.astro b/src/pages/api.astro index 4701d9132..68fd401c4 100644 --- a/src/pages/api.astro +++ b/src/pages/api.astro @@ -36,24 +36,24 @@ const specBaseUrl = (specObject.servers as Array<{ url?: string }> | undefined)? <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> - <title>Agent API Reference | Warp - + Warp Platform API reference | Warp + - - + + - + - - + + @@ -199,17 +199,17 @@ const specBaseUrl = (specObject.servers as Array<{ url?: string }> | undefined)? document.body.classList.add(resolved === 'dark' ? 'dark-mode' : 'light-mode'); })(); - + llms.txt. -

Warp Automation Platform HTTP API reference

+

Warp Platform API reference

-
+

{specInfo?.title}

{specInfo?.description}

Base URL: {specBaseUrl}

@@ -261,8 +261,8 @@ const specBaseUrl = (specObject.servers as Array<{ url?: string }> | undefined)? // doesn't show a fake "interactive" affordance (per scalar/scalar#5079). defaultOpenAllTags: true, metaData: { - title: 'Agent API Reference', - description: 'Interactive API reference for the Agent API.', + title: 'Warp Platform API reference', + description: 'Interactive reference for the Warp Platform API.', }, // --------------------------------------------------------------- // Scalar consumes `customCss` as a runtime string, so we can't diff --git a/src/pages/openapi.yaml.ts b/src/pages/openapi.yaml.ts index 801660a5b..b846187a1 100644 --- a/src/pages/openapi.yaml.ts +++ b/src/pages/openapi.yaml.ts @@ -4,7 +4,7 @@ import fs from 'node:fs'; export const prerender = true; /** - * Serves the raw Oz Agent API OpenAPI spec at /openapi.yaml so LLMs, crawlers, + * Serves the raw Warp Platform API OpenAPI spec at /openapi.yaml so LLMs, crawlers, * and developer tooling can consume the machine-readable definition directly. * * The spec source of truth is `developers/agent-api-openapi.yaml` (same file diff --git a/src/sidebar.ts b/src/sidebar.ts index 5115ad6ef..6adbdebe5 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -27,13 +27,10 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { label: 'Getting started', items: [ - // Shortened at the 8/18 rename. This label duplicates index.mdx's - // frontmatter title, which IS tokenized, so the two would have - // disagreed once the variable flipped. "Getting started with Warp - // and the Automation Platform" is too long for a sidebar row, and - // Warp is the umbrella product anyway. Keep both in sync. - { label: 'Getting started with Warp', link: '/' }, - { slug: 'quickstart', label: 'Warp quickstart' }, + // The root product overview remains in the Terminal topic until + // the GA navigation change adds a separate Terminal landing page. + { label: 'Warp products', link: '/' }, + { slug: 'quickstart', label: 'Quickstart' }, 'getting-started/quickstart/installation-and-setup', 'getting-started/quickstart/coding-in-warp', 'getting-started/quickstart/customizing-warp', @@ -247,13 +244,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ link: '/agents/', icon: 'puzzle', items: [ - { - label: 'Agents', - items: [ - { slug: 'agents', label: 'Overview' }, - 'agents/getting-started/faqs', - ], - }, + { slug: 'agents', label: 'Overview' }, { label: 'Warp Agents', items: [ @@ -354,6 +345,23 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agents/cli/reference', label: 'CLI reference' }, ], }, + { + label: `${VARS.WARP_AGENT_CLI} (legacy)`, + collapsed: true, + items: [ + { slug: 'agents/cli/oz-cli', label: 'Overview' }, + { slug: 'agents/cli/oz-cli/quickstart', label: 'Quickstart' }, + { slug: 'agents/cli/oz-cli/api-keys', label: 'API keys' }, + { slug: 'agents/cli/oz-cli/agent-profiles', label: 'Agent profiles' }, + { slug: 'agents/cli/oz-cli/mcp-servers', label: 'MCP servers' }, + { slug: 'agents/cli/oz-cli/skills', label: 'Skills' }, + { slug: 'agents/cli/oz-cli/warp-drive', label: 'Warp Drive context' }, + { slug: 'agents/cli/oz-cli/integration-setup', label: 'Integration setup' }, + { slug: 'agents/cli/oz-cli/artifacts', label: 'Artifacts' }, + { slug: 'agents/cli/oz-cli/federate', label: 'Federated identity' }, + 'agents/cli/oz-cli/troubleshooting', + ], + }, { label: 'Third-Party CLI Agents', items: [ @@ -371,6 +379,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agents/agent-memory', label: 'Agent Memory' }, ], }, + { slug: 'agents/getting-started/faqs', label: 'Agent FAQs' }, ], }, { @@ -389,17 +398,11 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // next door, since the underlying concepts are the same. items: [ { - // 'Getting started', not 'Get started': matches the Terminal, - // Enterprise, and Guides tabs. - label: 'Getting started', + label: 'Overview', items: [ { slug: 'factories', label: 'Overview' }, - { slug: 'factories/quickstart', label: 'Quickstart' }, - // 'Warp' is redundant inside the Factories tab, and the sibling - // labels ('Factory agents', 'Factory MCP') drop it too. This also - // resolves a desync: the page's own frontmatter label already said - // 'How Factories work', which this override was silently shadowing. { slug: 'factories/how-factories-work', label: 'How Factories work' }, + { slug: 'factories/quickstart', label: 'Quickstart' }, ], }, { @@ -414,10 +417,41 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // now the Automations primitive's conceptual home, parallel to Factory // agents and Factory skills, not just a filters reference. { slug: 'factories/automations', label: 'Factory automations' }, - { slug: 'factories/factory-as-code', label: 'Factory definition' }, - { slug: 'factories/infrastructure-and-security', label: 'Infrastructure & security' }, + { slug: 'factories/factory-as-code', label: 'Definitions as code' }, + { + label: 'Infrastructure', + items: [ + { slug: 'factories/infrastructure-and-security', label: 'Overview' }, + { slug: 'factories/deployment-patterns', label: 'Deployment patterns' }, + { slug: 'factories/warp-hosting', label: 'Warp-hosted execution' }, + { slug: 'factories/runners', label: 'Runners' }, + { + label: 'Managed self-hosting', + collapsed: true, + items: [ + { slug: 'factories/self-hosting', label: 'Overview' }, + { slug: 'factories/self-hosting/quickstart', label: 'Quickstart' }, + { slug: 'factories/self-hosting/managed-docker', label: 'Docker backend' }, + { slug: 'factories/self-hosting/managed-kubernetes', label: 'Kubernetes backend' }, + { slug: 'factories/self-hosting/managed-direct', label: 'Direct backend' }, + 'factories/self-hosting/monitoring', + { slug: 'factories/self-hosting/reference', label: 'Worker reference' }, + 'factories/self-hosting/troubleshooting', + ], + }, + ], + }, ], }, + { + label: 'Measure & improve', + items: [ + { slug: 'factories/measure-and-improve', label: 'Overview' }, + { slug: 'factories/measure-and-improve/scorers', label: 'Scorers' }, + { slug: 'factories/measure-and-improve/self-improvement', label: 'Self-improvement' }, + { slug: 'factories/benchmarks', label: 'Benchmarks' }, + ], + }, { // 'Integrations' per HYC (8/17), replacing 'Work intake'. // @@ -426,8 +460,8 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ // Integrations > Integrations > Slack. // // 'Connect your factory' leads because it is the overview for this - // group; Factory MCP trails because it is a connection mechanism - // rather than a third-party service. + // group. The direct developer interfaces live in Developer tools + // rather than alongside third-party service integrations. label: 'Integrations', items: [ { slug: 'factories/connect-your-factory', label: 'Connect your factory' }, @@ -436,12 +470,24 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/integrations/gitlab', label: 'GitLab' }, { slug: 'factories/integrations/linear', label: 'Linear' }, { slug: 'factories/integrations/jira', label: 'Jira' }, - // Custom webhooks connect any JSON-posting system, so they sit - // between the named third-party services and the API-style - // mechanisms below. Label matches the factory dashboard's nav. - // The overview holds the concept and the happy path; each - // provider whose setup differs from it gets its own page nested - // here (HYC, 9/15), same shape as 'Measure and improve' below. + ], + }, + { + label: 'Developer tools', + items: [ + { + label: 'API & SDKs', + items: [ + { slug: 'factories/developer-tools', label: 'Overview' }, + { slug: 'factories/factory-api', label: 'Factory endpoints' }, + { slug: 'factories/api-and-sdk', label: 'Agent & run endpoints' }, + { label: 'API reference', link: '/api' }, + { label: 'Python SDK', link: 'https://github.com/warpdotdev/oz-sdk-python' }, + { label: 'TypeScript SDK', link: 'https://github.com/warpdotdev/oz-sdk-typescript' }, + { slug: 'factories/api-and-sdk/troubleshooting/errors', label: 'Errors' }, + ], + }, + { slug: 'factories/factory-mcp', label: 'Factory MCP' }, { label: 'Webhooks', collapsed: false, @@ -450,41 +496,21 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'factories/webhooks/vercel', label: 'Vercel' }, ], }, - // Alongside Factory MCP: both are direct API-style connection - // mechanisms rather than third-party services, so they trail the - // per-service integrations above. - { slug: 'factories/factory-api', label: 'Factory API' }, - { slug: 'factories/factory-mcp', label: 'Factory MCP' }, ], }, { - // Same label as the Automation Platform tab's group for watching and - // steering runs, because it covers the same ground one level up: the - // factory dashboard is where you watch a factory, and scorers are how - // you measure it. + // The factory dashboard and inbox are operational surfaces. Measurement + // and optimization pages live earlier under 'Measure and improve'. label: 'Management & observability', items: [ { slug: 'factories/factory-inbox', label: 'Factory inbox' }, { slug: 'factories/factory-dashboard', label: 'Factory dashboard' }, - { - label: 'Measure and improve', - collapsed: false, - items: [ - { slug: 'factories/measure-and-improve', label: 'Overview' }, - { slug: 'factories/measure-and-improve/scorers', label: 'Scorers' }, - { slug: 'factories/measure-and-improve/self-improvement', label: 'Self-improvement' }, - { slug: 'factories/benchmarks', label: 'Benchmarks' }, - ], - }, ], }, - // Troubleshooting sits outside the groups, last in the tab. It was in - // 'Management & observability' next to the dashboard and Scorers pages, - // which read as a sibling of the measurement surfaces rather than as - // the place you go when something is broken. A bare trailing item is - // the same shape the Automation Platform tab uses for its leading - // 'Overview'. + // Keep troubleshooting and legacy transition guidance as direct trailing + // items rather than creating singleton groups. { slug: 'factories/troubleshooting', label: 'Troubleshooting' }, + { slug: 'platform/transitioning-from-oz', label: 'Legacy Oz workflows' }, ], }, { @@ -506,11 +532,13 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ icon: 'cloud-download', items: [ { slug: 'platform/overview', label: 'Overview' }, + { slug: 'platform/architecture', label: 'Architecture' }, { label: 'Cloud Agents', items: [ { slug: 'platform', label: 'Overview' }, { slug: 'platform/quickstart', label: 'Quickstart' }, + { slug: 'platform/transitioning-from-oz', label: 'Transitioning from Oz' }, { // Runtime (which agent executes the run) is kept separate from // configuration (how any run is set up) -- HYC review, 8/14. @@ -571,6 +599,8 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ }, { slug: 'platform/team-access-billing-and-identity', label: 'Access, billing, and identity' }, { slug: 'platform/faqs', label: 'Cloud agent FAQs' }, + { slug: 'platform/unmanaged-execution', label: 'Unmanaged execution' }, + { slug: 'platform/execution-security', label: 'Execution security' }, ], }, { @@ -579,7 +609,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'platform/environments', label: 'Overview' }, { slug: 'platform/environments/configuring-environments', label: 'Configuring environments' }, { slug: 'platform/environments/troubleshooting-environments', label: 'Troubleshooting' }, - { slug: 'platform/runners', label: 'Runners' }, ], }, { @@ -641,105 +670,6 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'platform/orchestration/multi-agent-runs', label: 'Running orchestrated agents' }, ], }, - { - // Named for what the group contains, not just its largest member: it - // holds a comparison page (deployment-patterns), a Warp-HOSTED page, - // and the self-hosting set. Labeling it 'Self-hosting' put - // 'Warp-hosted agents' under its own opposite. - label: 'Deployment & hosting', - items: [ - { slug: 'platform/architecture', label: 'Architecture' }, - { slug: 'platform/deployment-patterns', label: 'Deployment patterns' }, - { slug: 'platform/warp-hosting', label: 'Warp-hosted agents' }, - // Qualified: a bare 'Overview'/'Quickstart' would now read as the - // whole group's, not self-hosting's. Both match their page titles. - { slug: 'platform/self-hosting', label: 'Self-hosting overview' }, - { slug: 'platform/self-hosting/quickstart', label: 'Self-hosting quickstart' }, - { slug: 'platform/self-hosting/managed-docker', label: 'Managed: Docker' }, - { slug: 'platform/self-hosting/managed-kubernetes', label: 'Managed: Kubernetes' }, - { slug: 'platform/self-hosting/managed-direct', label: 'Managed: Direct' }, - { slug: 'platform/self-hosting/unmanaged', label: 'Unmanaged' }, - 'platform/self-hosting/monitoring', - { slug: 'platform/self-hosting/reference', label: 'Self-hosted worker reference' }, - 'platform/self-hosting/security-and-networking', - { slug: 'platform/self-hosting/troubleshooting', label: 'Troubleshooting' }, - ], - }, - ], - }, - { - label: 'API & Reference', - link: '/reference/', - icon: 'open-book', - items: [ - { - // API Reference promoted to the top of the sidebar (was buried 3 - // levels deep under API & SDK) per HYC/Rachael's Slack discussion on - // discoverability after the top-level API tab was removed. - label: 'Technical Reference', - items: [ - { slug: 'reference', label: 'Overview' }, - { label: 'API Reference', link: '/api' }, - ], - }, - { - label: 'CLI', - items: [ - { slug: 'reference/cli', label: `${VARS.WARP_AGENT_CLI} (legacy)` }, - { slug: 'reference/cli/quickstart', label: 'Quickstart' }, - { slug: 'reference/cli/api-keys', label: 'API Keys' }, - { slug: 'reference/cli/agent-profiles', label: 'Agent Profiles' }, - { slug: 'reference/cli/mcp-servers', label: 'MCP Servers' }, - { slug: 'reference/cli/skills', label: 'Skills' }, - { slug: 'reference/cli/warp-drive', label: 'Warp Drive Context' }, - { slug: 'reference/cli/integration-setup', label: 'Integration Setup' }, - { slug: 'reference/cli/artifacts', label: 'Artifacts' }, - { slug: 'reference/cli/federate', label: 'Federated identity' }, - 'reference/cli/troubleshooting', - ], - }, - { - label: 'API & SDK', - items: [ - { slug: 'reference/api-and-sdk', label: VARS.API_SDK_NAME }, - { slug: 'reference/api-and-sdk/quickstart', label: 'Quickstart' }, - // API Reference link moved to the top-level 'Technical Reference' - // group above for discoverability -- not duplicated here. - 'reference/api-and-sdk/demo-sentry-monitoring-with-sdk', - { - label: 'API Troubleshooting', - collapsed: true, - items: [ - { slug: 'reference/api-and-sdk/troubleshooting', label: 'API Troubleshooting' }, - { - label: 'Errors', - collapsed: true, - items: [ - { slug: 'reference/api-and-sdk/troubleshooting/errors', label: 'Errors' }, - 'reference/api-and-sdk/troubleshooting/errors/insufficient-credits', - 'reference/api-and-sdk/troubleshooting/errors/feature-not-available', - 'reference/api-and-sdk/troubleshooting/errors/external-authentication-required', - 'reference/api-and-sdk/troubleshooting/errors/not-authorized', - 'reference/api-and-sdk/troubleshooting/errors/invalid-request', - 'reference/api-and-sdk/troubleshooting/errors/resource-not-found', - 'reference/api-and-sdk/troubleshooting/errors/budget-exceeded', - 'reference/api-and-sdk/troubleshooting/errors/integration-disabled', - 'reference/api-and-sdk/troubleshooting/errors/integration-not-configured', - 'reference/api-and-sdk/troubleshooting/errors/operation-not-supported', - 'reference/api-and-sdk/troubleshooting/errors/environment-setup-failed', - 'reference/api-and-sdk/troubleshooting/errors/content-policy-violation', - 'reference/api-and-sdk/troubleshooting/errors/conflict', - 'reference/api-and-sdk/troubleshooting/errors/authentication-required', - 'reference/api-and-sdk/troubleshooting/errors/resource-unavailable', - 'reference/api-and-sdk/troubleshooting/errors/internal-error', - 'reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout', - 'reference/api-and-sdk/troubleshooting/errors/agent-process-failed', - ], - }, - ], - }, - ], - }, ], }, { @@ -817,13 +747,17 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ icon: 'setting', items: [ { - label: 'Getting started', + label: 'Overview', items: [ { slug: 'enterprise', label: 'Overview' }, - { slug: 'enterprise/getting-started/quickstart', label: 'Quick start' }, + ], + }, + { + label: 'Getting started', + items: [ + { slug: 'enterprise/getting-started/quickstart', label: 'Quickstart' }, { slug: 'enterprise/getting-started/getting-started-enterprise', label: 'Getting started for admins' }, { slug: 'enterprise/getting-started/getting-started-developers', label: 'Getting started for developers' }, - { slug: 'enterprise/getting-started/faq', label: 'FAQ' }, ], }, { @@ -859,6 +793,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ 'enterprise/support-and-resources/billing', { slug: 'enterprise/support-and-resources/troubleshooting-login', label: 'Troubleshooting login' }, { slug: 'enterprise/support-and-resources/feedback-and-feature-requests', label: 'Feedback and feature requests' }, + { slug: 'enterprise/getting-started/faq', label: 'FAQ' }, ], }, ], @@ -869,7 +804,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ link: '/guides/', icon: 'rocket', items: [ - { slug: 'guides', label: 'Guides' }, + { slug: 'guides', label: 'Overview' }, { label: 'Getting started', items: [ diff --git a/vercel.json b/vercel.json index 55a2455af..1ee6a3c17 100644 --- a/vercel.json +++ b/vercel.json @@ -359,7 +359,7 @@ }, { "source": "/platform/api-sdk", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { @@ -1094,32 +1094,32 @@ }, { "source": "/agent-platform/cloud-agents/managed-worker-reference(/?)", - "destination": "/platform/self-hosting/reference/", + "destination": "/factories/self-hosting/reference/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/direct-backend(/?)", - "destination": "/platform/self-hosting/managed-direct/", + "destination": "/factories/self-hosting/managed-direct/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/docker-connectivity(/?)", - "destination": "/platform/self-hosting/managed-docker/", + "destination": "/factories/self-hosting/managed-docker/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/helm-chart(/?)", - "destination": "/platform/self-hosting/managed-kubernetes/", + "destination": "/factories/self-hosting/managed-kubernetes/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/kubernetes-backend(/?)", - "destination": "/platform/self-hosting/managed-kubernetes/", + "destination": "/factories/self-hosting/managed-kubernetes/", "statusCode": 308 }, { "source": "/agent-platform/cloud-agents/managed-worker-reference/private-docker-registries(/?)", - "destination": "/platform/self-hosting/managed-docker/", + "destination": "/factories/self-hosting/managed-docker/", "statusCode": 308 }, { @@ -1549,7 +1549,7 @@ }, { "source": "/agent-platform/platform/deployment-patterns(/?)", - "destination": "/platform/deployment-patterns/", + "destination": "/factories/deployment-patterns/", "statusCode": 308 }, { @@ -1924,12 +1924,12 @@ }, { "source": "/errors", - "destination": "/reference/api-and-sdk/troubleshooting/errors/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/", "statusCode": 308 }, { "source": "/errors/:code", - "destination": "/reference/api-and-sdk/troubleshooting/errors/:code/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/:code/", "statusCode": 308 }, { @@ -2759,12 +2759,12 @@ }, { "source": "/reference/agent-api-and-sdk(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/ambient-agents/mcp-servers-for-agents(/?)", - "destination": "/reference/cli/mcp-servers/", + "destination": "/agents/cli/oz-cli/mcp-servers/", "statusCode": 308 }, { @@ -2784,147 +2784,147 @@ }, { "source": "/reference/api-and-sdk/troubleshooting/errors/authentication_required(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/authentication-required/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/authentication-required/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/budget_exceeded(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/budget-exceeded/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/content_policy_violation(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/content-policy-violation/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/content-policy-violation/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/environment_setup_failed(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/environment-setup-failed/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/external_authentication_required(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/external-authentication-required/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/agent_process_failed(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/agent-process-failed/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/agent-process-failed/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/feature_not_available(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/feature-not-available/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/feature-not-available/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/infrastructure_timeout(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/infrastructure-timeout/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/insufficient_credits(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/insufficient-credits/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/integration_disabled(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/integration-disabled/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/integration-disabled/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/integration_not_configured(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/integration-not-configured/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/internal_error(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/internal-error/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/internal-error/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/invalid_request(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/invalid-request/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/invalid-request/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/not_authorized(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/not-authorized/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/not-authorized/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/operation_not_supported(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/operation-not-supported/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/operation-not-supported/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/resource_not_found(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/resource-not-found/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/resource-not-found/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/troubleshooting/errors/resource_unavailable(/?)", - "destination": "/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/resource-unavailable/", "statusCode": 308 }, { "source": "/reference/cli#api-key-authentication", - "destination": "/reference/cli/api-keys/", + "destination": "/agents/cli/oz-cli/api-keys/", "statusCode": 308 }, { "source": "/reference/cli#quickstart-guide", - "destination": "/reference/cli/quickstart/", + "destination": "/agents/cli/oz-cli/quickstart/", "statusCode": 308 }, { "source": "/reference/cli/README.md#api-key-authentication", - "destination": "/reference/cli/api-keys/", + "destination": "/agents/cli/oz-cli/api-keys/", "statusCode": 308 }, { "source": "/reference/cli/integrations-and-environments(/?)", - "destination": "/reference/cli/integration-setup/", + "destination": "/agents/cli/oz-cli/integration-setup/", "statusCode": 308 }, { "source": "/reference/cli/mcp-for-cloud-agents(/?)", - "destination": "/reference/cli/mcp-servers/", + "destination": "/agents/cli/oz-cli/mcp-servers/", "statusCode": 308 }, { "source": "/reference/cli/mcp-servers-for-cloud-agents(/?)", - "destination": "/reference/cli/mcp-servers/", + "destination": "/agents/cli/oz-cli/mcp-servers/", "statusCode": 308 }, { "source": "/reference/developers/cli(/?)", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/reference/developers/cli#api-key-authentication", - "destination": "/reference/cli/api-keys/#authenticating-with-api-keys", + "destination": "/agents/cli/oz-cli/api-keys/#authenticating-with-api-keys", "statusCode": 308 }, { "source": "/reference/developers/cli#generating-api-keys", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/reference/developers/cli#linux", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/reference/integrations/integrations-overview/integrations-and-environments(/?)", - "destination": "/reference/cli/integration-setup/", + "destination": "/agents/cli/oz-cli/integration-setup/", "statusCode": 308 }, { "source": "/reference/integrations/integrations-overview/integrations-and-environments#creating-an-environment", - "destination": "/reference/cli/integration-setup/#step-1-creating-an-environment", + "destination": "/agents/cli/oz-cli/integration-setup/#step-1-creating-an-environment", "statusCode": 308 }, { @@ -2939,57 +2939,57 @@ }, { "source": "/reference/platform/agent-api-and-sdk(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/platform/agent-api-and-sdk#agent-sdk", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/platform/agent-api-and-sdk/agent(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/platform/agent-api-and-sdk/agent-1(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/platform/agent-api-and-sdk/demo-sentry-monitoring-with-sdk(/?)", - "destination": "/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/", + "destination": "/factories/api-and-sdk/demo-sentry-monitoring-with-sdk/", "statusCode": 308 }, { "source": "/reference/platform/cli(/?)", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/reference/platform/cli#api-key-authentication", - "destination": "/reference/cli/api-keys/", + "destination": "/agents/cli/oz-cli/api-keys/", "statusCode": 308 }, { "source": "/reference/platform/cli/api-keys(/?)", - "destination": "/reference/cli/api-keys/", + "destination": "/agents/cli/oz-cli/api-keys/", "statusCode": 308 }, { "source": "/reference/platform/cli/integrations-and-environments(/?)", - "destination": "/reference/cli/integration-setup/", + "destination": "/agents/cli/oz-cli/integration-setup/", "statusCode": 308 }, { "source": "/reference/platform/cli/troubleshooting(/?)", - "destination": "/reference/cli/troubleshooting/", + "destination": "/agents/cli/oz-cli/troubleshooting/", "statusCode": 308 }, { "source": "/reference/platform/warp-platform(/?)", - "destination": "/reference/", + "destination": "/factories/developer-tools/", "statusCode": 308 }, { @@ -4574,17 +4574,17 @@ }, { "source": "/reference/api-and-sdk/api-and-sdk(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/api-and-sdk/models(/?)", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/reference/cli/cli(/?)", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -4724,7 +4724,7 @@ }, { "source": "/platform/warp-platform(/?)", - "destination": "/reference/", + "destination": "/factories/developer-tools/", "statusCode": 308 }, { @@ -4779,12 +4779,12 @@ }, { "source": "/errors/", - "destination": "/reference/api-and-sdk/troubleshooting/errors/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/", "statusCode": 308 }, { "source": "/errors/:code/", - "destination": "/reference/api-and-sdk/troubleshooting/errors/:code/", + "destination": "/factories/api-and-sdk/troubleshooting/errors/:code/", "statusCode": 308 }, { @@ -4814,7 +4814,7 @@ }, { "source": "/platform/cli", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -4959,7 +4959,7 @@ }, { "source": "/platform/agent-api-and-sdk", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { @@ -5157,11 +5157,6 @@ "destination": "/agent-platform/capabilities/web-search/", "statusCode": 308 }, - { - "source": "/platform/deployment-patterns", - "destination": "/platform/deployment-patterns/", - "statusCode": 308 - }, { "source": "/agent-platform/warps-agent/agent-context/images-as-context", "destination": "/agent-platform/local-agents/agent-context/images-as-context/", @@ -5199,7 +5194,7 @@ }, { "source": "/platform/agent-api-and-sdk/agent-1", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { @@ -5209,7 +5204,7 @@ }, { "source": "/agent-platform/cloud-agents/self-hosting/managed-worker-reference", - "destination": "/platform/self-hosting/", + "destination": "/factories/self-hosting/", "statusCode": 308 }, { @@ -5254,7 +5249,7 @@ }, { "source": "/platform/cli/troubleshooting", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -5864,7 +5859,7 @@ }, { "source": "/developers/cli", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -6054,72 +6049,72 @@ }, { "source": "/platform/agent-api-and-sdk/agent", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/platform/agent-api-and-sdk/demo-sentry-monitoring-with-sdk", - "destination": "/reference/api-and-sdk/", + "destination": "/factories/api-and-sdk/", "statusCode": 308 }, { "source": "/platform/cli#api-key-authentication", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#bundled-with-warp", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#id-2.-authenticate", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#id-3.-run-an-agent", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#id-4.-add-github-context-optional", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#id-5.-next-steps", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#interactive-login-local-machines", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#running-agents", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#running-locally-warp-agent-run", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#running-the-cli", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#standalone-package", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { "source": "/platform/cli#what-is-the-warp-cli", - "destination": "/reference/cli/", + "destination": "/agents/cli/oz-cli/", "statusCode": 308 }, { @@ -6249,7 +6244,7 @@ }, { "source": "/integrations/integrations-overview/integrations-and-environments", - "destination": "/reference/cli/integration-setup/", + "destination": "/agents/cli/oz-cli/integration-setup/", "statusCode": 308 }, { @@ -6557,6 +6552,106 @@ "destination": "/agents/", "statusCode": 308 }, + { + "source": "/platform/deployment-patterns(/?)", + "destination": "/factories/deployment-patterns/", + "statusCode": 308 + }, + { + "source": "/platform/warp-hosting(/?)", + "destination": "/factories/warp-hosting/", + "statusCode": 308 + }, + { + "source": "/platform/runners(/?)", + "destination": "/factories/runners/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting(/?)", + "destination": "/factories/self-hosting/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/quickstart(/?)", + "destination": "/factories/self-hosting/quickstart/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/managed-docker(/?)", + "destination": "/factories/self-hosting/managed-docker/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/managed-kubernetes(/?)", + "destination": "/factories/self-hosting/managed-kubernetes/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/managed-direct(/?)", + "destination": "/factories/self-hosting/managed-direct/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/monitoring(/?)", + "destination": "/factories/self-hosting/monitoring/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/reference(/?)", + "destination": "/factories/self-hosting/reference/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/troubleshooting(/?)", + "destination": "/factories/self-hosting/troubleshooting/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/unmanaged(/?)", + "destination": "/platform/unmanaged-execution/", + "statusCode": 308 + }, + { + "source": "/platform/self-hosting/security-and-networking(/?)", + "destination": "/platform/execution-security/", + "statusCode": 308 + }, + { + "source": "/reference(/?)", + "destination": "/agents/cli/oz-cli/", + "statusCode": 308 + }, + { + "source": "/reference/api-and-sdk(/?)", + "destination": "/factories/api-and-sdk/", + "statusCode": 308 + }, + { + "source": "/reference/api-and-sdk/troubleshooting(/?)", + "destination": "/factories/api-and-sdk/troubleshooting/errors/", + "statusCode": 308 + }, + { + "source": "/factories/api-and-sdk/troubleshooting(/?)", + "destination": "/factories/api-and-sdk/troubleshooting/errors/", + "statusCode": 308 + }, + { + "source": "/reference/api-and-sdk/:path*", + "destination": "/factories/api-and-sdk/:path*", + "statusCode": 308 + }, + { + "source": "/reference/cli(/?)", + "destination": "/agents/cli/oz-cli/", + "statusCode": 308 + }, + { + "source": "/reference/cli/:path*", + "destination": "/agents/cli/oz-cli/:path*", + "statusCode": 308 + }, { "source": "/agents/cli-agents(/?)", "destination": "/agents/cli-agents/overview/",