diff --git a/.agents/references/terminology.md b/.agents/references/terminology.md index 7c329d4dd..d0b91fdc4 100644 --- a/.agents/references/terminology.md +++ b/.agents/references/terminology.md @@ -2,7 +2,7 @@ Use this glossary everywhere you write about Warp. Keep definitions short, concrete, and consistent. If a term is likely unfamiliar outside developer audiences, include a short plain-language explanation you can reuse on first mention. -For the summary of the most critical terms (core features, Oz terms, terms to avoid), see the [Terminology standards](../../AGENTS.md#terminology-standards) section of AGENTS.md. This file is the full canonical reference. +For the summary of the most critical terms (core features, Automation Platform terms, terms to avoid), see the [Terminology standards](../../AGENTS.md#terminology-standards) section of AGENTS.md. This file is the full canonical reference. > **Product name variables**: Product names are defined in `src/data/vars.ts`. When writing new content, use `{VARS.WARP_AGENT_CLI}` (body prose) or `{{WARP_AGENT_CLI}}` (frontmatter) rather than hardcoding product names. See the ["Content variables" section of AGENTS.md](../../AGENTS.md#content-variables) for full usage instructions. @@ -33,7 +33,7 @@ For the summary of the most critical terms (core features, Oz terms, terms to av *Usage note:* Use as the name of the feature, not "input box." - **Warp** — The agentic development environment for professional developers, built around a modern terminal and AI agents. - *Usage note:* Use "Warp" as the product name. Add "AI terminal" only when you need the positioning shorthand. Do not use "Warp Terminal" unless specifically distinguishing from Oz. + *Usage note:* Use "Warp" as the product name. Add "AI terminal" only when you need the positioning shorthand. Do not use "Warp Terminal" unless specifically distinguishing from the Automation Platform. ## Navigation and UI terms @@ -71,7 +71,7 @@ For the summary of the most critical terms (core features, Oz terms, terms to av ## Agent concepts -- **Cloud Agents** — Agents that run in the cloud on a schedule, trigger, or integration, without interactive input. Managed by the Oz Platform. +- **Cloud Agents** — Agents that run in the cloud on a schedule, trigger, or integration, without interactive input. Managed by the Automation Platform. *Usage note:* Use lowercase "cloud agents" in most contexts. Capitalize as "Cloud Agents" only when referring to the product section or feature name. - **Agent Profiles** — Saved configurations that define how an Agent runs (for example, permissions and model selection). @@ -95,7 +95,7 @@ For the summary of the most critical terms (core features, Oz terms, terms to av - **Slash Commands** — Built-in commands you run by typing `/` to trigger actions (or run saved prompts). -- **Agent Memory** — Oz's persistent, cross-harness memory layer that lets agents read and write durable knowledge across conversations, harnesses, and devices. Currently in research preview. +- **Agent Memory** — The Automation Platform's persistent, cross-harness memory layer that lets agents read and write durable knowledge across conversations, harnesses, and devices. Currently in research preview. *Usage note:* Capitalize as a feature name. Lowercase "memory" only when describing the generic concept (e.g., "the memory layer"). - **memory store** — A named collection of memories owned by a user (personal) or team. Multiple agents can share a store, and per-agent attachments control read/write access. @@ -133,18 +133,39 @@ For the summary of the most critical terms (core features, Oz terms, terms to av - **Workflow** / **Workflows** — Saved, runnable workflows in Warp Drive (often multi-step command sequences). -## Oz terminology +## Automation Platform terminology -### Warp Agent vs Oz +Renamed from "Oz" on 2026-08-18. Two surfaces keep the Oz name until 2026-09-15 +and are **not** stale in the meantime: the `oz` CLI binary and the Oz v1 web app +at `oz.warp.dev`. See "What still says Oz" at the end of this section. + +### The article rule + +"Oz" was a proper noun and read correctly bare. "Automation Platform" is a +common-noun phrase, so it needs a definite article in referential positions. +This is the single most common mistake when writing about the platform. + +- **Referential** (the platform as an entity — subject, object, possessor) takes + "the": "with the Automation Platform", "The Automation Platform provides", + "the Automation Platform's backend". +- **Attributive** (modifying a following noun) stays bare: "Automation Platform + settings", "Automation Platform-hosted", "Automation Platform overview". + +In docs prose, always write the name as `{VARS.WARP_AUTOMATION_PLATFORM}` (body) +or `{{WARP_AUTOMATION_PLATFORM}}` (frontmatter) rather than the literal string, +and put the article outside the token. `style_lint` enforces both: `hardcoded-var` +catches the literal, `platform-determiner` catches a missing article. + +### Warp Agent vs the Automation Platform - **Warp Agent** — Warp's built-in agent harness. Capitalized, singular, treated as a proper noun. Use "Warp Agent" when specifically referring to the built-in harness, especially when contrasting with third-party agents (Claude Code, Codex, etc.), or when referencing the Settings label (**Settings** > **Agents** > **Warp Agent**). Use lowercase "agent" / "agents" everywhere else. *Usage note:* Avoid "Warp's agent" and "Warp's agents" — the ambiguous middle ground, and the main source of capitalization drift in the docs. Rewrite as "the Warp Agent" (the built-in harness), "agents" or "agents in Warp" (generic), or "the Warp Agent harness" (the server-side runtime). *Usage note:* In prose the term takes the definite article — "the Warp Agent". Reserve the bare form for headings, sidebar labels, page titles, and the Settings path. "Runs the Warp Agent" reads correctly; "runs Warp Agent" reads as a different product. -- **Oz is the platform, not the agent.** Never introduce Oz as "Warp's agent" or equate the two. Oz runs and coordinates agents; the Warp Agent is the agent. +- **The Automation Platform is the platform, not the agent.** Never introduce it as "Warp's agent" or equate the two. The Automation Platform runs and coordinates agents; the Warp Agent is the agent. - **Warp Agent CLI** — The standalone terminal program (the `warp` binary) that runs the Warp Agent in any terminal, including over SSH and on machines without the Warp app. Documented at `/agents/cli/`. *Usage note:* Distinct from the Oz CLI (the `oz` binary), which runs and manages cloud agents. At the next launch (approximately August 18, 2026) the Oz CLI is retired and wrapped into the Warp Agent CLI, leaving a single CLI under this name. Until that ships, keep the two clearly separate in prose; afterwards, "Warp Agent CLI" covers both. -- **Oz** — Warp's programmable platform for running and coordinating agents at scale -- There is typically one Warp environment per user session. Oz can run many agents concurrently, across machines, repos, and teams. +- **Automation Platform** — Warp's programmable platform for running and coordinating agents at scale +- There is typically one Warp environment per user session. The Automation Platform can run many agents concurrently, across machines, repos, and teams. ### Core terms @@ -157,14 +178,17 @@ For the summary of the most critical terms (core features, Oz terms, terms to av - **Environment** — The execution context for an agent, including repo access, dependencies, secrets, compute, and runtime configuration. -- **Oz** — Warp's programmable platform for running and coordinating agents at scale. - *Example:* With Oz, you can orchestrate multiple agents to automate and parallelize complex workflows. +- **Automation Platform** — Warp's programmable platform for running and coordinating agents at scale. + *Example:* With the Automation Platform, you can orchestrate multiple agents to automate and parallelize complex workflows. -- **Oz dashboard** — The app surface to manage all Oz runs, unified across the Warp app and web. +- **cloud agent dashboard** — The app surface to manage all runs, unified across the Warp app and web. + *Usage note:* Platform-level default (HYC, 2026-08-17). Use `{VARS.DASHBOARD}`. On pages specifically about a factory, write "factory dashboard" directly. Both are lowercase common nouns, so capitalize only at the start of a sentence or bullet — which the variable cannot do, so reword rather than leading a bullet with it. -- **Oz run** — A single execution lifecycle of an agent, including actions, outputs, and logs. An Oz run is always cloud-based. +- **cloud agent run** — A single execution lifecycle of an agent, including actions, outputs, and logs. Always cloud-based. + *Usage note:* This is the platform-level default (HYC, 2026-08-17). Use `{VARS.PLATFORM_RUN}`, or "Warp cloud agent run" when you need to disambiguate from another vendor's runs. On pages that are specifically about a factory, write "factory run" directly instead — the variable holds the general term, so it cannot carry that distinction. - **Oz web app** — The web app for configuring agents and managing runs. + *Usage note:* Holds the Oz name until 2026-09-15. Use `{VARS.WEB_APP}`. - **subagent** — A child agent created by a parent agent to parallelize or delegate work. @@ -180,9 +204,15 @@ For the summary of the most critical terms (core features, Oz terms, terms to av ### Preferred phrases -- ✅ "Ask Oz to..." -- ✅ "Oz can help you..." -- ✅ "What would you like Oz to do?" +The platform is not something you address. It runs and coordinates agents; the +agent is what you ask. The older "Ask Oz to..." phrasings worked only because +"Oz" was doing double duty as both platform and assistant, which the rename +ended — "Ask the Automation Platform to..." is plainly wrong. Address the agent. + +- ✅ "Ask the agent to..." +- ✅ "Run an agent on the Automation Platform" +- ✅ "The Automation Platform can run this on a schedule" +- ❌ "Ask the Automation Platform to..." — you ask an agent, not a platform ### Terms to avoid @@ -197,6 +227,30 @@ For the summary of the most critical terms (core features, Oz terms, terms to av - ❌ "AI agents" → Use "agents" (the "AI" prefix is redundant) - ❌ "Ambient Agents" / "ambient agents" → Use "Cloud Agents" / "cloud agents" ("ambient" is no longer a product term; acceptable only in code identifiers like `AmbientAgentConfig`) - ❌ "agent identity" / "agent identities" → Use "agent," "agents," or "cloud agent(s)" in user-facing copy. Use legacy API names such as `agent_identity_uid` or `/agent/identities` only when documenting the exact field, path, or compatibility behavior. +- ❌ A bare "Automation Platform" in a referential position → Add "the". See "The article rule" above. +- ❌ The literal string "Automation Platform" in prose → Use `{VARS.WARP_AUTOMATION_PLATFORM}` / `{{WARP_AUTOMATION_PLATFORM}}`. + +### What still says Oz + +Not every "Oz" in the docs is stale. These are deliberate and correct until +2026-09-15, when they get their own value flip: + +- **The `oz` binary** and every `oz ` invocation. Commands inside code + fences are never rewritten. `{VARS.WARP_AGENT_CLI}` renders "Oz CLI". +- **`oz.warp.dev`** and the Oz v1 web app. `{VARS.WEB_APP}`, `{VARS.WEB_APP_URL}`. +- **`{VARS.API_SDK_NAME}`**, which renders "Oz API & SDK". +- **`oz-agent-worker`, `oz-agent-action`, `oz-skills`** — repository and package + names, not product names. These may never change. +- **The `@oz-agent` GitHub handle.** Handles are strings the product owns; + variabilizing them would silently rewrite a working handle into an invalid + one. This one keeps its name. + *The Slack/Linear handle moved from `@Oz` to `@warp` on 2026-08-17. It is + hardcoded for the same reason — that is what made it a safe one-line change + when the answer came back, rather than something a variable flip had already + broken.* +- **Changelog entries.** Historical records of what shipped under the old name. +- **Settings labels** such as **Settings** > **Cloud platform** > **Oz Cloud API + Keys**. These are literal UI strings and change only when the app does. ## Platform terms @@ -219,6 +273,56 @@ For the summary of the most critical terms (core features, Oz terms, terms to av - **Warp CLI** — Ambiguous since the Warp Agent CLI launched; avoid the bare term. Use "Oz CLI" for the `oz` binary that runs and manages cloud agents (formerly called `warp-cli`), or "Warp Agent CLI" for the `warp` binary that runs the Warp Agent in any terminal. +- **Automation Platform** — Warp's cloud agent platform, covering environments, integrations, orchestration, self-hosting, and the Agent API/SDK. Renamed from "Oz" on 2026-08-18. + *Usage note:* See "Automation Platform terminology" above for the full entry and the article rule. Always write it as `{VARS.WARP_AUTOMATION_PLATFORM}` / `{{WARP_AUTOMATION_PLATFORM}}`, never as a literal string, so a future rename stays a one-line change. + +## Warp Factories terminology + +### The product/instance rule + +This works like GitHub Actions. **Warp Factories** is the product and is always +written in full. An individual **factory** is a common noun and is always +lowercase. A bare capitalized **Factory** is never a proper noun — there is no +such product. + +- ✅ "Warp Factories is in Early Access" (the product) +- ✅ "your factory", "each factory's agents", "set up a factory" (an instance) +- ✅ "factory dashboard", "factory run", "factory agents", "factory definition" +- ❌ "the Factory", "your Factory", "Factory runs", "Factory metrics" +- ❌ "Factories" on its own to mean the product — write "Warp Factories" + +Sentence-initial capitals are positional, not proper nouns: a heading, sidebar +label, or page title may begin "Factory agents" or "Factory dashboard" for the +same reason it would begin "Cloud agents." The rule governs mid-sentence prose. + +Verbatim product strings are quoted as they ship, even when they break the rule. +The setup wizard currently renders **Factory name**, **Add your Factory to your +team**, and "Factory running!", and the sidebar renders **Factory definition**. +Docs match the screen; the fix belongs in the app. + +- **Warp Factories** — Warp's product for deploying and operating cloud software factories: automation loops around the SDLC where cloud agents triage, spec, implement, review, and verify work, with humans in the loop at key decision points. Launched in Early Access 2026-08-18. + *Usage note:* Capitalize both words as the product name; plural "Factories." Always write it in full — never a bare "Factory" or "Factories." Distinct from "software factory" (see below), the generic industry term for the pattern. + +- **software factory** — The generic, lowercase industry term for an automation loop around the SDLC (triage, spec, implement, review, verify). Warp Factories is Warp's product implementation of this pattern. + *Usage note:* Lowercase when used generically ("a software factory," "cloud software factories"). Capitalize only when part of the product name "Warp Factories." + +- **factory** — An individual deployed instance of a software factory, built on Warp Factories infrastructure. + *Usage note:* Lowercase common noun ("your factory," "set up a factory"). + +- **factory definitions as code** — The practice of specifying a factory's repos, agent roles, skills, MCPs, and permissions as version-controlled code, similar to infrastructure-as-code. Enables rollback, canarying, and agentic self-improvement of the factory itself. + +- **work item** — A unit of work moving through a factory (for example an issue, ticket, or triggered task) as it passes through triage, spec, implementation, review, and verification. + +- **foreman agent** — The orchestrator agent that receives a work item's triggering context and dispatches subagents to move it through the factory, choosing model, harness, and context for each step. + +- **Factory MCP** — The MCP server that lets any coding agent or MCP client interact with a factory: push work in, pull status, or guide sessions. + *Usage note:* The one sanctioned exception to the product/instance rule above, because it is the feature's own shipped name — the server registers as `warp-factory` and its skill calls itself "the Warp Factory MCP." Capitalize both words; do not generalize the exception to other phrases. + +- **factory dashboard** — The web app surface for operating a single factory: its work items, runs, agents, automations, and settings. + *Usage note:* Lowercase common noun. Distinct from **Dashboard**, the metrics page inside it, which is also the factory's landing page — bold **Dashboard** when you mean that page, and leave "factory dashboard" unbolded when you mean the surface. Replaced "control room," a docs-only coinage that appeared nowhere in the product. + +- **AI sovereignty** — Warp Factories' positioning around customer ownership and control of inference, hosting, and data exhaust (agent conversations, evals, memories) for their factory. + ## Technical terms - **AI** — not "A.I." Normalize all instances to "AI." diff --git a/.agents/skills/style_lint/SKILL.md b/.agents/skills/style_lint/SKILL.md index ae442c1f3..94c45f25f 100644 --- a/.agents/skills/style_lint/SKILL.md +++ b/.agents/skills/style_lint/SKILL.md @@ -60,6 +60,7 @@ python3 .agents/skills/style_lint/style_lint.py --all --fix --create-pr - **Deprecated terminology**: "whitelist" (→ "allowlist"), "blacklist"/"blocklist" (→ "denylist") - **External product names**: "Github" (→ "GitHub"), "github actions" (→ "GitHub Actions"), "MacOS" (→ "macOS"), "A.I." (→ "AI") - **Unrecognized terms** (warning): Bolded terms that look like product names but aren't in `terminology.md`. Flags candidates for glossary addition — not errors, just suggestions. +- **Warp Factories naming**: A bare capitalized "Factory" used as a proper noun. "Warp Factories" is the product and is written in full; an individual "factory" is lowercase. Sentence-, heading-, bullet-, quote-, and cell-initial capitals are positional and stay, as do frontmatter titles and labels, the shipped feature name "Factory MCP", and verbatim UI strings such as **Factory name** and **Add your Factory to your team**. Regression cases live in `test_factory_proper_noun.py`. - **Hardcoded product name strings**: Product name strings that have a corresponding key in `src/data/vars.ts` but appear as literal text rather than variable syntax. Reports instances of known strings like "Oz CLI", "Oz web app", "oz.warp.dev", "Oz dashboard", "Oz run" (any value currently in `src/data/vars.ts`) in body prose and frontmatter. These are flagged as `⚠️ [IMPORTANT]` in PR context and reported (not auto-fixed) — they should use `{VARS.KEY}` in prose and `{{TOKEN}}` in frontmatter. ## Auto-fix behavior @@ -72,6 +73,16 @@ When run with `--fix`: This skill checks broader formatting and terminology. The `validate_ui_refs` skill validates UI paths and Command Palette names against the warp-internal codebase. They complement each other with no overlap. Both can run in scheduled cloud agent workflows. +## Tests + +Two checks have regression suites, because both are narrow rules where the hard +part is not firing on legitimate text. Run them after touching either check: + +```bash +python3 .agents/skills/style_lint/test_platform_determiner.py +python3 .agents/skills/style_lint/test_factory_proper_noun.py +``` + ## Dependencies Requires Python 3.7+. Optional: `requests` (for Slack notifications), `gh` CLI (for PR creation). diff --git a/.agents/skills/style_lint/style_lint.py b/.agents/skills/style_lint/style_lint.py index 5ec8b518b..7b685bc39 100644 --- a/.agents/skills/style_lint/style_lint.py +++ b/.agents/skills/style_lint/style_lint.py @@ -39,7 +39,7 @@ "Codebase Context", "Code Review", "Command Palette", "Global Rules", "Oz CLI", "Oz Platform", "Project Rules", "Slash Commands", "Terminal Mode", "Universal Input", "Warp Drive", - "Warp Platform", + "Warp Platform", "Automation Platform", "Warp Factories", "Factory MCP", } # Terminology: wrong → right (case-sensitive checks) @@ -76,6 +76,13 @@ # entries whose values are expected to change at a product rename. Stable feature # names (AGENT_MODE, WARP_DRIVE, etc.) are intentionally excluded. # +# The bare "Oz" entries do double duty after the 8/18 rename. They no longer +# only mean "this should have been tokenized" -- a hardcoded "Oz" in prose is +# now a *stale* product name as well. Both readings want the same fix, so the +# entries stay. The "Automation Platform" entry is the mirror image: it catches +# the new name being hardcoded, which would silently miss the 9/15 changes and +# any later rename. +# # Each entry: (literal_string, var_key, suggestion) RENAME_SENSITIVE_VAR_STRINGS: List[Tuple[str, str, str]] = [ ("Oz CLI", "WARP_AGENT_CLI", "{VARS.WARP_AGENT_CLI} in prose or {{WARP_AGENT_CLI}} in frontmatter"), @@ -83,8 +90,83 @@ ("oz.warp.dev", "WEB_APP_URL", "{VARS.WEB_APP_URL} in prose or {{WEB_APP_URL}} in frontmatter"), ("Oz dashboard", "DASHBOARD", "{VARS.DASHBOARD} in prose or {{DASHBOARD}} in frontmatter"), ("Oz run", "PLATFORM_RUN", "{VARS.PLATFORM_RUN} in prose or {{PLATFORM_RUN}} in frontmatter"), + ("Oz API & SDK", "API_SDK_NAME", "{VARS.API_SDK_NAME} in prose or {{API_SDK_NAME}} in frontmatter"), + ("Oz Platform", "WARP_AUTOMATION_PLATFORM", "{VARS.WARP_AUTOMATION_PLATFORM} in prose or {{WARP_AUTOMATION_PLATFORM}} in frontmatter"), + ("Automation Platform", "WARP_AUTOMATION_PLATFORM", "{VARS.WARP_AUTOMATION_PLATFORM} in prose or {{WARP_AUTOMATION_PLATFORM}} in frontmatter"), + ("Oz", "WARP_AUTOMATION_PLATFORM", "{VARS.WARP_AUTOMATION_PLATFORM} in prose or {{WARP_AUTOMATION_PLATFORM}} in frontmatter"), ] +# Phrasings that deliberately name the old product. A transition callout has to +# say "Oz" to do its job, so without this the guard would fight the very copy +# that explains the rename -- and the author's only workaround would be to +# backtick a product name, which is semantically wrong. +# +# Keyed on explicit transition phrasings rather than a per-file or per-page +# opt-out, so an unrelated stale "Oz" elsewhere on the same page is still +# caught. Only old-name literals are suppressed; a hardcoded *new* name on the +# same line still gets flagged, since nothing about a transition sentence +# excuses that. +RENAME_TRANSITION_MARKERS: Tuple[str, ...] = ( + "formerly Oz", + "formerly called Oz", + "formerly the Oz", + "Oz is now", + "was called Oz", + "renamed from Oz", + # Explains why "Oz" still appears in commands and URLs before 9/15. + "the Oz name", +) + +# Product names that merely contain "Oz" but are not the platform name, so they +# do not change when it does. "Oz by Warp" is the GitHub App as it appears in +# GitHub's own UI, at github.com/apps/oz-by-warp, and is what PRs and commits +# are attributed to. Renaming it in the docs would make them disagree with what +# the reader sees on GitHub. Same reasoning as the `@oz-agent` handle. +# +# Matched as a suffix on the literal rather than added as its own entry, +# because the goal is to suppress rather than redirect: there is no variable +# these should be using instead. +RENAME_EXEMPT_SUFFIXES: Tuple[str, ...] = ( + " by Warp", +) + +# Determiner check for WARP_AUTOMATION_PLATFORM. See check_platform_determiner. +# +# "Oz" was a proper noun and read correctly bare. "Automation Platform" is a +# common-noun phrase and needs a definite article in referential positions. The +# defect is invisible in source -- `The {{WARP_AUTOMATION_PLATFORM}} provides` +# looks fine in the .mdx and only reads wrong once rendered -- so it needs a +# lint rule rather than review attention. +PLATFORM_TOKEN = re.compile(r"\{VARS\.WARP_AUTOMATION_PLATFORM\}|\{\{WARP_AUTOMATION_PLATFORM\}\}") +PLATFORM_DETERMINER = re.compile(r"\b(the|a|an|its|their|your|our|this|that)\s*(\*\*|\*|\[)?\s*$", re.IGNORECASE) +# Prepositions that take a noun phrase, so a bare platform name after one reads +# as a proper noun and is wrong under the new name. +PLATFORM_PREPOSITIONS = re.compile( + r"\b(with|to|in|on|by|from|for|into|across|via|using|of|about|through|within)\s*(\*\*|\*|\[)?\s*$", + re.IGNORECASE, +) +# Verbs that mark the token as a clause subject. +PLATFORM_SUBJECT_VERBS = re.compile( + r"^\s*(\*\*|\*)?\s*(is|are|was|were|can|will|provides|gives|uses|reads|detects|supports|posts|runs|orchestrates|handles|manages|creates|lets|exposes|routes|tracks)\b" +) +# A lowercase word directly after the token usually means the token is +# modifying it -- "{...} orchestration", "automated {...} runs", "{...} cloud +# environments" -- which is attributive and correctly bare. Function words are +# excluded because they continue the sentence rather than extend the noun +# phrase, so "with {...} for cloud runs" is still referential. +PLATFORM_FUNCTION_WORDS = { + "a", "an", "and", "are", "as", "at", "be", "blocks", "but", "by", "can", + "for", "from", "if", "in", "is", "of", "on", "or", "so", "than", "that", + "the", "then", "to", "was", "were", "when", "which", "while", "will", "with", +} +PLATFORM_NEXT_WORD = re.compile(r"^\s+([a-z][a-z-]*)") +# Several subject verbs double as nouns -- "runs", "uses", "reads". Requiring +# the token to actually begin a clause keeps "automated {...} runs" (a noun +# phrase) from being read as "{...} runs" (a subject and its verb). +PLATFORM_CLAUSE_START = re.compile( + r"(^|[.:!?]\s+|[-\u2013\u2014]\s+|^\s*[*-]\s+)(\*\*|\*|\[)?\s*$" +) + # Oz terms to avoid (case-insensitive patterns) OZ_TERMS_TO_AVOID = [ (r"\bagent identities\b", "Use 'agents' or 'cloud agents' unless referring to legacy API names in code"), @@ -181,6 +263,11 @@ ) MARKDOWN_LINK = re.compile(r"\[([^\]]*)\]\(([^)]+)\)") VIDEO_EMBED_TITLE = re.compile(r"\btitle\s*=\s*([\"'])(.*?)\1", re.DOTALL) +# JSX expression titles, e.g. title={`${VARS.WEB_APP} walkthrough`} — used when +# the title includes a rename-sensitive {VARS.KEY} reference. Content can't be +# statically evaluated, so these are treated as present but skipped by the +# generic-title check below. +VIDEO_EMBED_TITLE_EXPR = re.compile(r"\btitle\s*=\s*\{(.*?)\}", re.DOTALL) # Common bolded words that are NOT product terms (false positive suppression) COMMON_BOLD_WORDS = { @@ -656,21 +743,29 @@ def check_video_embed_titles(lines: List[str], filepath: str) -> List[Issue]: issues = [] for line_number, tag in _iter_video_embed_tags(lines): title_match = VIDEO_EMBED_TITLE.search(tag) - if not title_match or not title_match.group(2).strip(): - issues.append(Issue( - filepath, line_number, "video-title", - "VideoEmbed missing title prop. Add a specific title that describes the integration, workflow, feature, or task shown.", - "error", - )) + if title_match and title_match.group(2).strip(): + title = title_match.group(2).strip() + if _is_generic_video_title(title): + issues.append(Issue( + filepath, line_number, "video-title", + f"Generic VideoEmbed title: \"{title}\". Use a specific title that describes what the video shows.", + "warning", + )) continue - title = title_match.group(2).strip() - if _is_generic_video_title(title): - issues.append(Issue( - filepath, line_number, "video-title", - f"Generic VideoEmbed title: \"{title}\". Use a specific title that describes what the video shows.", - "warning", - )) + # Not a quoted string literal — check for a JSX expression title, e.g. + # title={`${VARS.WEB_APP} walkthrough`}. Content isn't statically + # evaluable, so skip the generic-title check but still confirm a + # non-empty title prop is present. + expr_match = VIDEO_EMBED_TITLE_EXPR.search(tag) + if expr_match and expr_match.group(1).strip(): + continue + + issues.append(Issue( + filepath, line_number, "video-title", + "VideoEmbed missing title prop. Add a specific title that describes the integration, workflow, feature, or task shown.", + "error", + )) return issues @@ -890,19 +985,73 @@ def check_hardcoded_vars(lines: List[str], filepath: str) -> List[Issue]: Skips fenced code blocks and inline code spans so that CLI examples like `oz.warp.dev` in a code fence are not flagged. + + Literals are checked longest-first and matches are deduplicated by span so + overlapping rename-sensitive names are not double-flagged. + + Matches use word boundaries (`\b`) rather than plain substring search, so + literals don't false-positive inside unrelated tokens such as URL query + params, hashes, or other identifiers. + + An "@"-prefixed occurrence is skipped because mention handles are literal + strings that do not necessarily change with product names. Variabilizing + a handle could silently rewrite it into an invalid value at rename time. + + Old-name literals are also skipped on lines carrying a phrase from + RENAME_TRANSITION_MARKERS, so "formerly Oz" copy can name the old product + without the guard objecting. New-name literals on those lines still flag. """ issues = [] in_code_block = False + sorted_strings = sorted(RENAME_SENSITIVE_VAR_STRINGS, key=lambda entry: -len(entry[0])) + compiled = [ + (literal, var_key, suggestion, re.compile(r"\b" + re.escape(literal) + r"\b")) + for literal, var_key, suggestion in sorted_strings + ] for i, line in enumerate(lines, 1): if line.strip().startswith("```"): in_code_block = not in_code_block continue if in_code_block: continue + # Text that describes an image must match the image, so it cannot be + # tokenized. Two separate reasons, same conclusion: + # + # Alt text is markdown, not JSX -- `![... {VARS.WEB_APP}](...)` renders + # the literal "VARS.WEB_APP" on the page, so tokenizing it is simply + # broken. Figcaptions *are* JSX and would substitute correctly, but a + # caption that auto-flips ahead of the screenshot it captions is worse + # than one that stays stale: the page would claim a name the image + # visibly contradicts. Both have to be updated by hand, together with + # the images, when the screenshots are retaken. + if line.lstrip().startswith("![") or "= s and span[1] <= e for s, e in matched_spans): + continue + # Mention handles are literal strings, not prose. See docstring. + if span[0] > 0 and prose_line[span[0] - 1] == "@": + continue + # Only the old name is excused by transition phrasing; a + # hardcoded new name is still a bug on the same line. + if is_transition_line and literal.startswith(("Oz", "oz")): + continue + # Distinct product names that happen to contain "Oz". + if any( + prose_line[span[1]:].startswith(suffix) + for suffix in RENAME_EXEMPT_SUFFIXES + ): + continue + matched_spans.append(span) issues.append(Issue( filepath, i, "hardcoded-var", f'Hardcoded "{literal}" should use {suggestion} (see src/data/vars.ts)', @@ -911,6 +1060,204 @@ def check_hardcoded_vars(lines: List[str], filepath: str) -> List[Issue]: return issues +def check_platform_determiner(lines: List[str], filepath: str) -> List[Issue]: + """Flag {VARS.WARP_AUTOMATION_PLATFORM} used referentially without an article. + + "Oz" was a proper noun and read correctly bare: "with Oz", "Oz provides", + "Oz's backend". "Automation Platform" is a common-noun phrase, so the same + positions need a definite article: "with the ...", "The ... provides", + "the ...'s backend". + + This is worth a lint rule rather than review attention because the defect is + invisible in the source file. `The {{WARP_AUTOMATION_PLATFORM}} provides` + looks correct in the .mdx and only reads wrong once the variable is + substituted at build time. + + Only high-confidence positions are flagged, so that attributive uses stay + quiet: + * possessive -- token followed by 's + * prepositional -- token directly after "with", "to", "in", and friends + * subject -- token directly before a finite verb + + Deliberately NOT flagged, because bare is correct there: + * attributive compounds -- "{{...}} settings", "{{...}}-hosted", and any + token directly followed by a lowercase noun it modifies + * frontmatter title/label values -- "{{...}} overview" + * bold term leads in definition lists -- "* **{VARS....}** - ..." + + A determiner on the previous line still counts, so a soft-wrapped sentence + or a wrapped frontmatter description is not falsely flagged. + """ + issues = [] + in_code_block = False + in_frontmatter = False + # Frontmatter is not uniformly exempt. `title` and `sidebar.label` are + # headline-style and correctly bare, but `description` is a sentence, and it + # becomes the meta description -- the text search engines and AI engines + # read before deciding whether to cite the page. Skipping all of + # frontmatter left exactly that field unguarded against the defect this + # check exists to catch. + in_description = False + for i, line in enumerate(lines, 1): + stripped = line.strip() + if i == 1 and stripped == "---": + in_frontmatter = True + continue + if in_frontmatter: + if stripped == "---": + in_frontmatter = False + in_description = False + continue + # A description can be inline or a folded block (`description: >-`) + # continuing over several indented lines. Track which key we are + # inside so the continuation lines are scanned too. + key = re.match(r"([a-zA-Z_]+):", stripped) + if key: + in_description = key.group(1) == "description" + if not in_description: + continue + # fall through and scan this line + if stripped.startswith("```"): + in_code_block = not in_code_block + continue + if in_code_block or not PLATFORM_TOKEN.search(line): + continue + for m in PLATFORM_TOKEN.finditer(line): + before = line[:m.start()] + after = line[m.end():] + # A wrapped line can leave the determiner on the previous line. + lookback = before if before.strip() else (lines[i - 2] if i >= 2 else "") + if PLATFORM_DETERMINER.search(lookback): + continue + if after[:1] == "-": # attributive compound, e.g. "{{...}}-hosted" + continue + if re.match(r"^\s*[*-]\s+\*\*\s*$", before): # bold term lead + continue + + # Order matters. Possessive and subject positions are unambiguous, + # so they are classified first. The attributive exemption applies + # only to the prepositional case, which is the one that is genuinely + # ambiguous: "with {...} orchestration" modifies a noun and is fine + # bare, while "with {...}." is referential and needs the article. + # Applying the exemption earlier would swallow "{...} provides ...", + # since "provides" is just a lowercase word to a regex. + if after.startswith("'s") or after.startswith("\u2019s"): + position = "possessive" + elif PLATFORM_SUBJECT_VERBS.match(after) and PLATFORM_CLAUSE_START.search(before): + position = "as a clause subject" + elif PLATFORM_PREPOSITIONS.search(lookback): + nxt = PLATFORM_NEXT_WORD.match(after) + if nxt and nxt.group(1) not in PLATFORM_FUNCTION_WORDS: + continue # attributive: the token modifies the next noun + position = "after a preposition" + else: + continue + + issues.append(Issue( + filepath, i, "platform-determiner", + f"{{VARS.WARP_AUTOMATION_PLATFORM}} used {position} without a " + f"determiner. The value is a common-noun phrase, so this renders " + f'as e.g. "with Automation Platform". Add "the" before it.', + "warning", + )) + return issues + + +# "Warp Factories" is the product; a "factory" is an instance. A bare +# capitalized "Factory" is never a proper noun, with two classes of exception: +# the feature's own name (Factory MCP) and verbatim product strings the docs +# quote from the app. Both are matched on the word that FOLLOWS "Factory". +FACTORY_ALLOWED_NEXT_WORDS = { + # Feature name, shipped as such: the server registers as `warp-factory`. + "MCP", + # Verbatim UI strings. Changing these would make the docs disagree with the + # screen, so they are quoted as-is until the app copy changes. + "name", # **Factory name** field in the setup wizard + "definition", # **Factory definition** sidebar tab + "integrations", # **Factory integrations** section in Settings + "running", # "Factory running!" on the setup summary screen +} +# Whole phrases that are correct despite containing a bare "Factory": verbatim +# UI strings the docs quote, and references to unrelated products that happen to +# be named Factory. +FACTORY_ALLOWED_PHRASES = ( + "Add your Factory to your team", # verbatim setup wizard heading + "Factory's CLI coding agent", # Factory.ai, the company behind Droid +) +FACTORY_BARE = re.compile(r"\bFactory\b") +# Markup that can sit between the start of a sentence and the word itself: +# heading hashes, list bullets, blockquotes, emphasis, link text, quotes, and +# table cell pipes. Stripped before deciding whether the position is initial. +FACTORY_LEADING_MARKUP = re.compile(r"[\s*_\[\(\"'|>#\-\u2014\u2013]+$") + + +def check_factory_proper_noun(lines: List[str], filepath: str) -> List[Issue]: + """Flag a bare capitalized "Factory" used as a proper noun. + + The rule works like GitHub Actions: "Warp Factories" is the product and is + always written in full, an individual "factory" is a lowercase common noun, + and there is no product called "Factory". See AGENTS.md -> Warp Factories + terminology. + + Quiet by construction, because most capitalized "Factory" occurrences are + legitimate: + * "Warp Factories" and "Warp Factory" -- the product name + * sentence-, heading-, bullet-, link-, quote-, and cell-initial position, + where the capital is positional rather than a proper noun + * fenced code blocks, inline code, link targets, and HTML attributes + * frontmatter, whose titles and sidebar labels are headline-style + * the exceptions in FACTORY_ALLOWED_NEXT_WORDS and + FACTORY_ALLOWED_PHRASES + """ + issues = [] + in_code_block = False + in_frontmatter = False + for i, line in enumerate(lines, 1): + stripped = line.strip() + if i == 1 and stripped == "---": + in_frontmatter = True + continue + if in_frontmatter: + if stripped == "---": + in_frontmatter = False + continue + if stripped.startswith("```"): + in_code_block = not in_code_block + continue + if in_code_block or "Factory" not in line: + continue + if any(phrase in line for phrase in FACTORY_ALLOWED_PHRASES): + continue + # Strip inline code, link targets, and HTML/JSX attributes: a slug like + # `/factories/factory-as-code/` or an `alt="..."` value is not prose. + prose = re.sub(r"`[^`]*`", "", line) + prose = re.sub(r"\]\([^)]*\)", "]", prose) + prose = re.sub(r'\w+="[^"]*"', "", prose) + for m in FACTORY_BARE.finditer(prose): + before = prose[:m.start()] + after = prose[m.end():] + if before.rstrip().endswith("Warp"): + continue # "Warp Factories" / "Warp Factory" + # Strip the markup between the sentence start and the word, then ask + # whether anything is left. Nothing left means the capital is + # positional; a preceding clause means it is being used as a name. + prefix = FACTORY_LEADING_MARKUP.sub("", before) + if not prefix or prefix.endswith((".", "!", "?", ":", "|", "—")): + continue + nxt = re.match(r"\s+(\w+)", after) + if nxt and nxt.group(1) in FACTORY_ALLOWED_NEXT_WORDS: + continue + issues.append(Issue( + filepath, i, "factory-proper-noun", + 'Bare "Factory" used as a proper noun. "Warp Factories" is the ' + 'product and is written in full; an individual factory is ' + 'lowercase. Write "factory" (or "Warp Factories" if you mean ' + "the product).", + "warning", + )) + return issues + + # Cache glossary terms once at module level _glossary_cache: Optional[set] = None @@ -940,6 +1287,8 @@ def run_all_checks(filepath: Path) -> List[Issue]: issues.extend(check_oz_terms(lines, str(filepath))) issues.extend(check_deprecated_terms(lines, str(filepath))) issues.extend(check_hardcoded_vars(lines, str(filepath))) + issues.extend(check_platform_determiner(lines, str(filepath))) + issues.extend(check_factory_proper_noun(lines, str(filepath))) issues.extend(check_unrecognized_terms(lines, str(filepath), _get_glossary())) return issues diff --git a/.agents/skills/style_lint/test_factory_proper_noun.py b/.agents/skills/style_lint/test_factory_proper_noun.py new file mode 100644 index 000000000..43fab69be --- /dev/null +++ b/.agents/skills/style_lint/test_factory_proper_noun.py @@ -0,0 +1,100 @@ +#!/usr/bin/env python3 +"""Regression cases for check_factory_proper_noun. + +Run from the repo root: + python3 .agents/skills/style_lint/test_factory_proper_noun.py + +The rule is narrow: "Warp Factories" is the product, an individual "factory" is +a lowercase common noun, and a bare capitalized "Factory" is never a proper +noun. Almost all of the difficulty is in NOT firing, because a capital F is +usually positional rather than a name -- headings, sidebar labels, bullets, +table cells, quoted terms, and link text all start with one legitimately. + +The first draft of this check produced 9 hits across the docs and 8 of them +were wrong: heading-initial ("## Factory-definition pull request checks"), +list-initial link text ("* [Factory dashboard](...)"), frontmatter labels, a +quoted term at the start of a sentence, a verbatim UI string ("Add your Factory +to your team"), and a reference to Factory.ai, the company behind Droid. Each +of those is a case below. If you touch the check, run this first. +""" +import importlib.util +import pathlib +import sys + +HERE = pathlib.Path(__file__).parent +spec = importlib.util.spec_from_file_location("style_lint", HERE / "style_lint.py") +style_lint = importlib.util.module_from_spec(spec) +spec.loader.exec_module(style_lint) + +CASES = [ + # (text, should_flag, description) + # --- genuine proper-noun uses --- + ("See [Factory agents](/factories/factory-agents/) for the roles.", True, + "mid-sentence link text"), + ("Every Factory gets its own Slack app.", True, + "mid-sentence, standing in for the product"), + ("Runs started by the Factory are tracked.", True, + "definite article plus a capital"), + ("Review the Factory metrics before deciding.", True, + "mid-sentence attributive use of the banned form"), + # --- the product name, written correctly --- + ("Warp Factories is in Early Access.", False, "the product name"), + ("Connect Warp Factories to your repository.", False, "product name mid-sentence"), + # --- positional capitals --- + ("## Factory-definition pull request checks", False, "heading-initial"), + ("### Factory agents", False, "subheading-initial"), + ("* [Factory dashboard](/factories/factory-dashboard/) - the surface.", False, + "list-initial link text"), + ("Factory setup doesn't choose models for you.", False, "sentence-initial"), + ('"Factory dashboard" names the whole surface.', False, "quoted term, sentence-initial"), + ("| **Factory definition** | The definition files |", False, "table-cell-initial"), + ("The tab is read-only. Factory owners can still edit it.", False, + "initial after a sentence boundary"), + # --- sanctioned exceptions --- + ("Send work through the Factory MCP.", False, "Factory MCP is the shipped feature name"), + ("Enter a **Factory name**, such as `Payments`.", False, "verbatim UI field label"), + ("The **Factory definition** tab lists the files.", False, "verbatim UI tab label"), + ("1. In factory setup, go to **Add your Factory to your team**.", False, + "verbatim UI string, allowlisted as a phrase"), + ("* **Droid** — Factory's CLI coding agent", False, + "Factory.ai, an unrelated company"), + # --- non-prose --- + ("Fetch `/api/v1/Factory/source` for the definition.", False, "inline code"), + ('Factory settings page', False, "HTML attribute"), +] + +FRONTMATTER_CASE = ( + ['---', 'title: Factory dashboard', 'sidebar:', ' label: "Factory agents"', '---', + 'The factory dashboard is the web app for one factory.'], + False, + "frontmatter titles and labels are headline-style", +) + + +def main() -> int: + failures = 0 + for text, should_flag, description in CASES: + flagged = bool(style_lint.check_factory_proper_noun(text.split("\n"), "test.mdx")) + ok = flagged == should_flag + if not ok: + failures += 1 + print(f" [{'PASS' if ok else 'FAIL'}] {description:<48} flagged={flagged}") + + lines, should_flag, description = FRONTMATTER_CASE + flagged = bool(style_lint.check_factory_proper_noun(lines, "test.mdx")) + ok = flagged == should_flag + if not ok: + failures += 1 + print(f" [{'PASS' if ok else 'FAIL'}] {description:<48} flagged={flagged}") + + total = len(CASES) + 1 + print() + if failures: + print(f"{failures} of {total} cases regressed.") + return 1 + print(f"All {total} cases behave correctly.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.agents/skills/style_lint/test_platform_determiner.py b/.agents/skills/style_lint/test_platform_determiner.py new file mode 100644 index 000000000..bfb4dc060 --- /dev/null +++ b/.agents/skills/style_lint/test_platform_determiner.py @@ -0,0 +1,62 @@ +#!/usr/bin/env python3 +"""Regression cases for check_platform_determiner. + +Run from the repo root: + python3 .agents/skills/style_lint/test_platform_determiner.py + +The check has to separate three referential positions (possessive, +prepositional, subject) from several attributive ones that are correctly bare. +The ordering between those tests is load-bearing and easy to get wrong: an +earlier draft applied the attributive exemption before classifying position, +which silently stopped flagging "{...} provides ..." because "provides" is +just a lowercase word to a regex. A later draft flagged "automated {...} runs" +because "runs" is in the subject-verb list even though it is a noun there. + +Both bugs are covered below. If you touch the check, run this first. +""" +import importlib.util +import pathlib +import sys + +HERE = pathlib.Path(__file__).parent +spec = importlib.util.spec_from_file_location("style_lint", HERE / "style_lint.py") +style_lint = importlib.util.module_from_spec(spec) +spec.loader.exec_module(style_lint) + +T = "{VARS.WARP_AUTOMATION_PLATFORM}" + +CASES = [ + # (text, should_flag, description) + (f"Run agents with {T}.", True, "prepositional - needs the article"), + (f"{T} provides the CLI and API.", True, "clause subject - needs the article"), + (f"Connects to {T}'s backend.", True, "possessive - needs the article"), + (f"Handled by {T}, then reported.", True, "prepositional before a comma"), + (f"Run agents with the {T}.", False, "determiner already present"), + (f"Use {T} orchestration for this.", False, "attributive - modifies a noun"), + (f"An environment for automated {T} runs.", False, "attributive - 'runs' is a noun here"), + (f"Available in {T} cloud environments.", False, "attributive - modifies a noun"), + (f"Deploy on {T}-hosted infrastructure.", False, "hyphenated compound"), + (f"* **{T}** - the platform.", False, "bold term lead in a definition list"), + (f"available with the\n{T} for teams.", False, "determiner on the previous line"), +] + + +def main() -> int: + failures = 0 + for text, should_flag, description in CASES: + flagged = bool(style_lint.check_platform_determiner(text.split("\n"), "test.mdx")) + ok = flagged == should_flag + if not ok: + failures += 1 + print(f" [{'PASS' if ok else 'FAIL'}] {description:<48} flagged={flagged}") + + print() + if failures: + print(f"{failures} of {len(CASES)} cases regressed.") + return 1 + print(f"All {len(CASES)} cases behave correctly.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/AGENTS.md b/AGENTS.md index 624c90d2a..b22336adb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,7 +59,7 @@ Avoid words that are ambiguous between singular and plural. - **Serial comma**: Always use it. "Environments, integrations, and schedules" — not "Environments, integrations and schedules." - **Contractions**: Allowed and encouraged to match our approachable tone. Use "you're," "don't," "it's," "can't." Exception: avoid contractions in error messages or formal warnings. - **Tense**: Use present tense to describe how things work ("Warp indexes your codebase"). Use imperative for instructions ("Configure your environment"). -- **Person**: Use second person ("you") for instructions. Avoid first person plural ("we") in procedural content. First person is acceptable in conceptual or narrative text when referring to Warp as a company ("We designed Oz to..."). +- **Person**: Use second person ("you") for instructions. Avoid first person plural ("we") in procedural content. First person is acceptable in conceptual or narrative text when referring to Warp as a company ("We designed the Automation Platform to..."). ### Inclusive language - Use gender-neutral pronouns ("they/them") for unknown users @@ -116,7 +116,7 @@ Every description answers "what will I get from this page?" The shape of that an - ✅ `Environments give cloud agents the same toolchain and setup on every run, no matter what triggers them.` - ❌ `Learn about environments and why they are useful.` - **Procedural** - Say what task the reader will complete. Start with an imperative verb. - - ✅ `Connect Slack to Oz so mentions and channel messages can trigger cloud agent runs.` + - ✅ `Connect Slack to the Automation Platform so mentions and channel messages can trigger cloud agent runs.` - ❌ `This page explains the Slack integration setup process.` - **Quickstart** - Say what the reader ends up with, plus the time budget. Start with an imperative verb. - ✅ `Install the Warp Agent CLI, log in, and run your first agent conversation in about five minutes.` @@ -639,7 +639,7 @@ Product feature names retain their standard capitalization. Match the exact casi - **Codebase Context** - Warp indexes your Git-tracked codebase to help Agents understand your code. - **Admin Panel** - Team management surface for controlling members, roles, and billing. - **Agent Management Panel** - Interface for viewing and managing running agents (not "agent dashboard" or "agent manager"). -- **Agent Memory** - Persistent, cross-harness memory layer for Oz agents that captures durable facts, decisions, and outcomes across conversations (currently in research preview). Capitalize as a feature name; use lowercase "memory store" for individual stores. +- **Agent Memory** - Persistent, cross-harness memory layer for cloud agents that captures durable facts, decisions, and outcomes across conversations (currently in research preview). Capitalize as a feature name; use lowercase "memory store" for individual stores. - **Handoff** - Feature for moving agent work between a local Warp session and the cloud, or continuing a finished cloud run; supports local-to-cloud, cloud-to-cloud, and cloud-to-local. Capitalize as a feature name; lowercase "hand off" only as a verb. ### Capitalizing "agent" @@ -662,24 +662,34 @@ This is the single most drifted term in the docs, so the rule is narrow on purpo ❌ "Profiles control how Warp's agents behave." (ambiguous) ❌ "Warp's agent can run commands." (ambiguous) -### Oz terminology +### Automation Platform terminology -#### Warp Agent vs Oz +Renamed from "Oz" on 2026-08-18. The `oz` CLI binary and the Oz v1 web app at `oz.warp.dev` keep the Oz name until 2026-09-15 and are not stale in the meantime. See `.agents/references/terminology.md` → "What still says Oz" for the full holdout list. + +#### The article rule +"Oz" was a proper noun and read correctly bare. "Automation Platform" is a common-noun phrase, so it needs a definite article in referential positions. This is the most common mistake when writing about the platform. + +- **Referential** (subject, object, possessor) takes "the": "with the Automation Platform", "The Automation Platform provides", "the Automation Platform's backend". +- **Attributive** (modifying a following noun) stays bare: "Automation Platform settings", "Automation Platform-hosted", "Automation Platform overview". + +Write the name as `{VARS.WARP_AUTOMATION_PLATFORM}` in body prose or `{{WARP_AUTOMATION_PLATFORM}}` in frontmatter, never as a literal string, and keep the article outside the token. `style_lint` enforces both halves: `hardcoded-var` catches the literal, `platform-determiner` catches the missing article. + +#### Warp Agent vs the Automation Platform - **Warp Agent** — Warp's built-in agent harness. Use "Warp Agent" when specifically referring to the built-in harness, especially when contrasting with third-party agents (Claude Code, Codex, etc.), or when referencing the Settings label (**Settings** > **Agents** > **Warp Agent**). -- **Oz is the platform, not the agent.** Never introduce Oz as "Warp's agent" or equate the two. Oz runs and coordinates agents; the Warp Agent is the agent. -- **Oz** — Warp's programmable platform for running and coordinating agents at scale -- There is typically one Warp environment per user session. Oz can run many agents concurrently, across machines, repos, and teams. +- **The Automation Platform is the platform, not the agent.** Never introduce it as "Warp's agent" or equate the two. The Automation Platform runs and coordinates agents; the Warp Agent is the agent. +- **Automation Platform** — Warp's programmable platform for running and coordinating agents at scale +- There is typically one Warp environment per user session. The Automation Platform can run many agents concurrently, across machines, repos, and teams. #### Core terms - **agent** - A combination of agent instructions (skill or prompt), trigger (cron, webhook, manual), environment (local, cloud), profile, and host. Agents can be local or cloud. Use lowercase "agent" in most contexts; use "Warp Agent" only when referring specifically to the built-in Warp harness. - **cloud agent** - An agent running in the cloud, from a trigger, schedule, or started from someone's local machine - **subagent** - A child agent created by a parent agent to parallelize or delegate work - **conversation** - An interactive execution lifecycle within the Warp Terminal, regardless of whether it's local or in the cloud -- **Oz** - Warp's programmable platform for running and coordinating agents at scale -- **Oz run** - A single execution lifecycle of an agent, including actions, outputs, and logs. Always cloud-based. +- **Automation Platform** - Warp's programmable platform for running and coordinating agents at scale +- **cloud agent run** - A single execution lifecycle of an agent, including actions, outputs, and logs. Always cloud-based. Use `{VARS.PLATFORM_RUN}`. On factory-specific pages, write "factory run" directly. - **Environment** - The execution context for an agent, including repo access, dependencies, secrets, compute, and runtime configuration -- **Oz dashboard** - The app surface to manage all Oz runs, unified across the Warp app and web -- **Oz web app** - The web app for configuring agents and managing runs +- **cloud agent dashboard** - The app surface to manage all runs, unified across the Warp app and web. Use `{VARS.DASHBOARD}`. On factory-specific pages, write "factory dashboard" directly. +- **Oz web app** - The web app for configuring agents and managing runs. Holds the Oz name until 2026-09-15; use `{VARS.WEB_APP}`. #### Oz CLI commands - `oz agent run` - Run a local agent @@ -691,9 +701,12 @@ This is the single most drifted term in the docs, so the rule is narrow on purpo - `oz run list/get` - Get info on cloud agent runs #### Preferred phrases -- ✅ "Ask Oz to..." -- ✅ "Oz can help you..." -- ✅ "What would you like Oz to do?" +The platform is not something you address — it runs and coordinates agents, and the agent is what you ask. The older "Ask Oz to..." phrasings worked only because "Oz" was doing double duty as both platform and assistant, which the rename ended. + +- ✅ "Ask the agent to..." +- ✅ "Run an agent on the Automation Platform" +- ✅ "The Automation Platform can run this on a schedule" +- ❌ "Ask the Automation Platform to..." — you ask an agent, not a platform #### Terms to avoid - ❌ "Oz agent" / "Oz agents" → Use "agent" / "agents" (or "Warp Agent" / "Warp Agents" when referring to the built-in harness) @@ -708,6 +721,23 @@ This is the single most drifted term in the docs, so the rule is narrow on purpo - ❌ "Ambient Agents" / "ambient agents" → Use "Cloud Agents" / "cloud agents" ("ambient" is no longer a product term) - ❌ "Agent Modality" or "agent modality" → Use "Terminal and Agent modes" (this was an internal name, not user-facing) - ❌ "agent identity" / "agent identities" → Use "agent," "agents," or "cloud agent(s)" in user-facing copy. Use legacy API names such as `agent_identity_uid` or `/agent/identities` only when documenting the exact field, path, or compatibility behavior. +- ❌ A bare "Automation Platform" in a referential position → Add "the". See [The article rule](#the-article-rule). +- ❌ The literal string "Automation Platform" in prose → Use `{VARS.WARP_AUTOMATION_PLATFORM}` / `{{WARP_AUTOMATION_PLATFORM}}`. + +### Warp Factories terminology + +This works like GitHub Actions. **Warp Factories** is the product and is always written in full. An individual **factory** is a common noun and is always lowercase. A bare capitalized **Factory** is never a proper noun. + +- ✅ "Warp Factories is in Early Access" (the product) +- ✅ "your factory", "each factory's agents", "factory dashboard", "factory run", "factory agents" +- ❌ "the Factory", "your Factory", "Factory runs", "Factory metrics" +- ❌ "Factories" on its own to mean the product → write "Warp Factories" + +Sentence-initial capitals are positional, not proper nouns — a heading or sidebar label may begin "Factory agents" for the same reason it would begin "Cloud agents." The rule governs mid-sentence prose. `style_lint` enforces it with the `factory-proper-noun` check. + +**Exceptions, quoted as they ship:** **Factory MCP** is the feature's own name (the server registers as `warp-factory`). Verbatim UI strings — **Factory name**, **Foreman name**, **Factory integrations**, **Add your Factory to your team**, "Factory running!", and the **Factory definition** sidebar label — are quoted as the app renders them. + +See `.agents/references/terminology.md` → "Warp Factories terminology" for the full glossary. ### Technical terms - **AI** (not "A.I.") diff --git a/astro.config.mjs b/astro.config.mjs index ff2e45722..b8c6d0097 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -200,18 +200,23 @@ export default defineConfig({ // llms-small.txt; our patch (patches/starlight-llms-txt+0.8.1.patch) // extends it to llms-full.txt and custom sets as well. exclude: ['support-and-community/community/open-source-licenses'], + // This string is the first thing an AI engine reads about Warp, so it + // carries the product lineup. Kept in sync with the rename and with + // launches: it said "the Oz platform" until the 8/18 rename, which + // left the most-consumed AI-facing artifact on the old name. description: - 'Documentation for Warp, the agentic development environment. Covers Warp Terminal, Warp Agents, and the Oz platform for cloud agents and orchestration at scale.', + 'Documentation for Warp, the agentic development environment. Covers the Warp terminal, Warp agents, the Automation Platform for cloud agents and orchestration at scale, and Warp Factories for running software factories.', customSets: [ { label: 'Terminal', description: 'Warp Terminal features and configuration.', paths: ['terminal/**'] }, { label: 'Agents', description: 'Warp\'s agents: capabilities, local agents, and CLI agents.', paths: ['agents/**'] }, + { label: 'Factories', description: 'Warp Factories documentation for setup, agent roles, definitions as code, integrations, measurement, and infrastructure.', paths: ['factories/**'] }, { label: 'Warp Agent CLI', description: 'The Warp Agent CLI: agent conversations, shell commands, permissions, and configuration in any terminal.', paths: ['agents/cli/**'] }, - { label: 'Oz Platform', description: 'Warp\'s Oz platform: cloud agents, orchestration, triggers, integrations, environments, harnesses, and self-hosting.', paths: ['platform/**'] }, + { label: 'Automation Platform', description: 'Warp\'s Automation Platform: cloud agents, orchestration, triggers, integrations, environments, harnesses, and self-hosting.', paths: ['platform/**'] }, { label: 'Code', description: 'Code editor, code review, and Git worktrees.', paths: ['code/**'] }, { 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: 'Reference', description: 'CLI and API reference.', paths: ['reference/**'] }, + { 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/src/assets/agent-platform/most-flexible-platform-for-building-with-agents.png b/src/assets/agent-platform/most-flexible-platform-for-building-with-agents.png index 794a0e017..c427b30e6 100644 Binary files a/src/assets/agent-platform/most-flexible-platform-for-building-with-agents.png and b/src/assets/agent-platform/most-flexible-platform-for-building-with-agents.png differ diff --git a/src/assets/agent-platform/oz-diagram.png b/src/assets/agent-platform/oz-diagram.png deleted file mode 100644 index f1793268f..000000000 Binary files a/src/assets/agent-platform/oz-diagram.png and /dev/null differ diff --git a/src/assets/agent-platform/platform-architecture.png b/src/assets/agent-platform/platform-architecture.png new file mode 100644 index 000000000..d7c399e59 Binary files /dev/null and b/src/assets/agent-platform/platform-architecture.png differ diff --git a/src/assets/terminal/warp-factories-welcome.png b/src/assets/terminal/warp-factories-welcome.png new file mode 100644 index 000000000..1a2d5fcea Binary files /dev/null and b/src/assets/terminal/warp-factories-welcome.png differ diff --git a/src/assets/terminal/warp-oz-welcome.png b/src/assets/terminal/warp-oz-welcome.png deleted file mode 100644 index 6224a456c..000000000 Binary files a/src/assets/terminal/warp-oz-welcome.png and /dev/null differ diff --git a/src/components/CopyPageButton.astro b/src/components/CopyPageButton.astro index b892b0f41..56d5b8a3b 100644 --- a/src/components/CopyPageButton.astro +++ b/src/components/CopyPageButton.astro @@ -1,11 +1,27 @@ --- /** * CopyPageButton — Scalar-style dropdown with: - * - Copy page (copies raw MDX body as markdown) + * - Copy page (copies the MDX body as markdown, with imports stripped and + * product-name variables resolved -- see resolveMdxSource below) * - Copy agent prompt (copies a context-appropriate prompt for the page type) * - View as Markdown (opens .md URL in new tab) * - Export as PDF (window.print) */ +import { VARS } from '@data/vars'; + +// Not global, and applied line by line from the top of the file rather than +// across the whole body: an MDX component import only ever appears in the +// leading block, while a code sample can legitimately contain the same shape. +// A global replace ate `import OpenAI from "openai";` out of the Node example +// in guides/external-tools/how-to-set-up-ollama.mdx, so the copied snippet no +// longer ran. +const IMPORT_LINE = /^import\s+[^\n]*?from\s+['"][^'"]+['"];?\s*$/; +// The optional leading `$` matters: MDX authors write `{VARS.KEY}` in prose but +// `${VARS.KEY}` inside JSX template literals, e.g. href={`${VARS.WEB_APP_URL}/runs`}. +// Matching only the braces leaves the dollar behind and yields `$https://...`. +const PROSE_TOKEN = /\$?\{VARS\.([A-Z0-9_]+)\}/g; +const FRONTMATTER_TOKEN = /\{\{([A-Z0-9_]+)\}\}/g; + interface Props { body: string; title: string; @@ -13,7 +29,48 @@ interface Props { agentPrompt?: string; } const { body, title, agentPrompt } = Astro.props; -const markdownContent = `# ${title}\n\n${body}`; + +/** + * `body` arrives as raw MDX source, so it still carries authoring scaffolding: + * `import` statements at the top and unsubstituted `{VARS.KEY}` / `{{KEY}}` + * product-name tokens throughout. + * + * That matters more than it looks. This payload is what "Copy page as Markdown + * for LLMs" puts on the clipboard, so without this an assistant reading the + * copied text sees the literal string `{VARS.WARP_AUTOMATION_PLATFORM}` instead + * of the product name -- worse than the stale name it replaced. + * + * The sibling `.md` route does not have this problem because + * `docs-markdown-integration.js` derives those files from the *rendered* HTML + * after the build, by which point Astro has resolved everything. This component + * runs during render and only has the source, so it repeats the two cleanups. + * + * Known gap: raw JSX (``) and directive syntax (`:::note`) still + * pass through here, where the `.md` route renders them properly. The durable + * fix is for this button to fetch the page's own `.md` URL on click rather than + * carry a second copy of the content. + */ +/** Drops the leading `import` block, stopping at the first line of content. */ +function stripLeadingImports(source: string): string { + const lines = source.split('\n'); + let start = 0; + while ( + start < lines.length && + (lines[start].trim() === '' || IMPORT_LINE.test(lines[start])) + ) { + start++; + } + return lines.slice(start).join('\n'); +} + +function resolveMdxSource(source: string): string { + const vars = VARS as unknown as Record; + return stripLeadingImports(source) + .replace(PROSE_TOKEN, (match, key) => vars[key] ?? match) + .replace(FRONTMATTER_TOKEN, (match, key) => vars[key] ?? match); +} + +const markdownContent = `# ${title}\n\n${resolveMdxSource(body)}`; const pageUrl = Astro.url.href; const pathname = Astro.url.pathname; diff --git a/src/components/CustomSidebar.astro b/src/components/CustomSidebar.astro index 954f822f7..2335992e7 100644 --- a/src/components/CustomSidebar.astro +++ b/src/components/CustomSidebar.astro @@ -69,7 +69,7 @@ import KapaLauncher from './KapaLauncher.astro'; 'getting-started': 'Getting started', 'knowledge-and-collaboration': 'Knowledge & collaboration', 'agents': 'Agents', - 'reference': 'Reference', + 'reference': 'API & Reference', 'changelog': 'Changelog', 'support-and-community': 'Support', 'enterprise': 'Enterprise', diff --git a/src/components/FeedbackFooter.astro b/src/components/FeedbackFooter.astro index c0fb7305b..e67786b46 100644 --- a/src/components/FeedbackFooter.astro +++ b/src/components/FeedbackFooter.astro @@ -34,7 +34,20 @@ const pageUrl = Astro.url.href; footer { flex-direction: column; gap: 1.25rem; - margin-top: 2rem; + /* Hairline marking the end of page content, so the CTA below reads as + footer chrome rather than a trailing sentence of the article. + Matches the divider treatment on the "On this page" panel footer + (`CustomPageSidebar.astro`). + + Spacing above the rule is NOT set here: this footer is a sibling of + `.sl-markdown-content` inside Starlight's ContentPanel, whose + `.sl-container > * + *` rule (specificity 0,1,1) already applies + `margin-top: 1.5rem` and outranks a bare `footer` selector (0,0,1). + A `margin-top: 2rem` previously declared here never took effect; + padding is used instead so the space below the rule is ours to set + and matches the 1.5rem gap above it. */ + padding-top: 1.5rem; + border-top: 1px solid var(--sl-color-hairline-light); } .kudos { align-items: center; diff --git a/src/components/WarpTopicNav.astro b/src/components/WarpTopicNav.astro index d36cf094c..d3bc29508 100644 --- a/src/components/WarpTopicNav.astro +++ b/src/components/WarpTopicNav.astro @@ -5,9 +5,8 @@ // Reference, etc.) as an inline-flex row with a small icon + label. The list // is sourced from `starlight-sidebar-topics`'s middleware, which exposes // `Astro.locals.starlightSidebarTopics.topics` on every Starlight route. -// Each topic carries `{ link, label, icon, badge, isCurrent }`; we consume -// `link`/`label`/`icon`/`isCurrent` and ignore `badge` for now (none of our -// topics ship one). The plugin's per-topic sidebar filtering lives in its +// Each topic carries `{ link, label, icon, badge, isCurrent }`. The plugin's +// per-topic sidebar filtering lives in its // middleware (it rewrites `starlightRoute.sidebar`), so removing the topic // list from the sidebar markup does NOT break that filtering — the same // filtered nav still renders below this row in the page sidebar. @@ -26,6 +25,11 @@ // underline share `--sl-color-text-accent`, which auto-adapts to dark // and light themes. // - No surrounding chip / box / bg — just type + icon +// - Topic badge (e.g. Factories "Early Access"): rendered as a plain span +// styled as a compact brand pill (Inter, 11px/600, accent tint, fully +// rounded) instead of Starlight's ``, whose monospace bordered +// box clashed with the nav type and was wide enough to wrap the nav +// onto a second row at common laptop widths. import { Icon } from '@astrojs/starlight/components'; const { topics } = Astro.locals.starlightSidebarTopics; @@ -33,14 +37,12 @@ const { topics } = Astro.locals.starlightSidebarTopics; // Per-topic icon overrides for topics where Starlight's icon registry doesn't // ship the right glyph (only 22 generic UI icons available; no robot/AI). The // `sidebar.ts` config keeps the closest Starlight name (e.g. `puzzle` for -// Agents, `seti:json` for API) so the mobile drawer falls back gracefully; -// this map points to a custom inline SVG that we render here in the header -// instead. +// Agents) so the mobile drawer falls back gracefully; this map points to a +// custom inline SVG that we render here in the header instead. const CUSTOM_TOPIC_ICONS: Record = { Agents: true, - API: true, Enterprise: true, - Oz: true, + 'Automation Platform': true, }; --- @@ -60,22 +62,7 @@ const CUSTOM_TOPIC_ICONS: Record = { this and the Starlight-rendered icons to a single uniform size. `currentColor` so each icon inherits the link's text color and picks up the active-state accent. */} - {topic.label === 'API' ? ( - /* `` brackets — the conventional dev-API glyph. - Two chevrons mirrored across center, stroke weight - matched to the other topic icons. */ - - - - - ) : topic.label === 'Enterprise' ? ( + {topic.label === 'Enterprise' ? ( /* Office building — simple outline: tall rectangle with window grid and entrance, stroke weight matched to the other topic icons. */ @@ -96,7 +83,7 @@ const CUSTOM_TOPIC_ICONS: Record = { - ) : topic.label === 'Oz' ? ( + ) : topic.label === 'Automation Platform' ? ( /* Cloud icon — Feather-style cloud outline, stroke weight matched to the other topic icons. */ = { ) : null} {topic.label} + {topic.badge && ( + {topic.badge.text} + )} ))} @@ -149,13 +139,14 @@ const CUSTOM_TOPIC_ICONS: Record = { diff --git a/src/content/docs/agents/agent-memory/index.mdx b/src/content/docs/agents/agent-memory/index.mdx index d8ee5d476..6c575a7da 100644 --- a/src/content/docs/agents/agent-memory/index.mdx +++ b/src/content/docs/agents/agent-memory/index.mdx @@ -1,18 +1,19 @@ --- title: Agent Memory (Research Preview) description: >- - Agent Memory gives agents in Oz persistent memory across supported harnesses, + Agent Memory gives agents in Warp persistent memory across supported harnesses, including the Warp Agent, Claude Code, and Codex. sidebar: label: "Agent Memory (Research Preview)" --- +import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; :::caution Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://www.warp.dev/oz/agent-memory#waitlist) to request access for your team. ::: -Agent Memory is a persistent memory system that lives on Oz and is shared across every supported agent harness, including the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to this memory system as they run, so durable facts, decisions, and outcomes from one conversation are available to the next — regardless of which harness, machine, or teammate triggers the work. +Agent Memory is a persistent memory system that lives on Warp and is shared across every supported agent harness, including the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to this memory system as they run, so durable facts, decisions, and outcomes from one conversation are available to the next — regardless of which harness, machine, or teammate triggers the work. Memory creation and retrieval are asynchronous and run in the background, so they don't consume tokens or add latency to the active task. @@ -27,7 +28,7 @@ Watch this short preview to see Agent Memory in context. * **Cross-harness memory** - One memory system is shared across the Warp Agent, Claude Code, Codex, and other harnesses as they're added. Third-party harnesses are covered when they run as cloud agents. * **Both local and cloud agents** - Supports interactive local agents in Warp and background cloud agents. * **Asynchronous by design** - Memory creation runs after a conversation ends. Retrieval runs in the background during a run. Neither consumes tokens or adds latency to the active task. -* **Automatic memory creation from conversations** - When a conversation ends, Oz extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. +* **Automatic memory creation from conversations** - When a conversation ends, Warp extracts durable facts, learnings, and outcomes and writes them as memories. New knowledge merges with existing memories or supersedes them on conflict. * **Shareable stores** - Memory is organized into stores. A store can be attached to one or more agents, so the same knowledge is available wherever those agents run. To share knowledge across a team, attach a store to an agent the whole team uses. * **Auto-memory for new agents** - New agents get a dedicated, agent-owned memory store by default, so they start building long-term memory from their first run. You can turn this off when you create the agent. * **Per-agent access and instructions** - Attach stores to specific agents with read-only or read-write access. Per-store instructions tell each agent how and when to use the store. @@ -36,7 +37,7 @@ Watch this short preview to see Agent Memory in context. ## Where Agent Memory runs -Agent Memory is part of Oz. Storage, memory creation, and retrieval all run on Oz alongside your agents. The same memory is accessible from any agent you run on Oz: +Agent Memory is part of Warp. Storage, memory creation, and retrieval all run on Warp alongside your agents. The same memory is accessible from any agent you run in Warp: * The local Warp Agent. * Cloud agents triggered from the CLI, web app, schedules, or integrations. @@ -58,7 +59,7 @@ Teams can use multiple stores to keep contexts separate, and attach the same sto ### Auto-memory for new agents -When you create an agent in the Oz web app, **Auto-memory** is on by default. With it enabled, Oz creates a dedicated memory store owned by that agent and uses it as the agent's default long-term memory: the agent reads relevant memories before it acts and writes durable facts, decisions, and preferences for future runs. Each agent has a single auto-memory store. +When you create an agent in the {VARS.WEB_APP}, **Auto-memory** is on by default. With it enabled, Warp creates a dedicated memory store owned by that agent and uses it as the agent's default long-term memory: the agent reads relevant memories before it acts and writes durable facts, decisions, and preferences for future runs. Each agent has a single auto-memory store. Auto-memory is different from automatic memory creation from conversations, described below: auto-memory is the store an agent gets by default, while automatic memory creation from conversations is how memories are written to a store after a conversation ends. @@ -66,15 +67,15 @@ You can turn Auto-memory off when you create the agent, and you can attach exist ## Automatic memory creation from conversations -When a conversation finishes, Oz extracts durable facts, learnings, and outcomes from the transcript and writes them as memories. Memory creation runs in the background after the conversation ends, so it doesn't consume tokens or add latency during that run. +When a conversation finishes, Warp extracts durable facts, learnings, and outcomes from the transcript and writes them as memories. Memory creation runs in the background after the conversation ends, so it doesn't consume tokens or add latency during that run. * **Memories evolve over time** - Agents update and supersede their own memories as new information arrives, including to resolve contradictions with prior memories. -You can also explicitly ask an agent to remember something during a conversation. Oz saves that memory to the appropriate store. +You can also explicitly ask an agent to remember something during a conversation. Warp saves that memory to the appropriate store. ## How agents use memory -When an agent starts a task, Oz searches the stores the agent can access for relevant memories and injects them as context. The search runs in the background, so the agent only sees the memories returned. Agents can also retrieve additional memories on demand mid-conversation when they determine it's relevant, similar to how they consult [Rules](/agents/capabilities/rules/) or [Codebase Context](/agents/capabilities/codebase-context/). You don't need to write retrieval queries or pre-load memory. +When an agent starts a task, Warp searches the stores the agent can access for relevant memories and injects them as context. The search runs in the background, so the agent only sees the memories returned. Agents can also retrieve additional memories on demand mid-conversation when they determine it's relevant, similar to how they consult [Rules](/agents/capabilities/rules/) or [Codebase Context](/agents/capabilities/codebase-context/). You don't need to write retrieval queries or pre-load memory. ## Attaching memory to your agents @@ -84,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 [Oz API](/reference/api-and-sdk/), in addition to managing them in the Oz web app. -* **Self-hosting support** - Run Agent Memory on a [self-hosted Oz](/platform/self-hosting/) instance to meet security, privacy, and compliance requirements. +* **Programmatic API access** - Read and manage memories and stores through the [{VARS.API_SDK_NAME}](/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. ## Join the waitlist diff --git a/src/content/docs/agents/capabilities/agent-notifications.mdx b/src/content/docs/agents/capabilities/agent-notifications.mdx index e1de8a8fc..41554eceb 100644 --- a/src/content/docs/agents/capabilities/agent-notifications.mdx +++ b/src/content/docs/agents/capabilities/agent-notifications.mdx @@ -4,6 +4,7 @@ description: >- Warp surfaces notifications from coding agents, both in-app and via desktop alerts, so you know exactly when an agent needs your attention. --- +import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; Warp delivers notifications from any supported coding agent so you always know when an agent finishes a task, encounters an error, or needs your input. Notifications work whether you're in a different tab or a different app. @@ -106,7 +107,7 @@ In a [multi-agent orchestration](/platform/orchestration/), the parent agent and That means: * **Toasts and the mailbox** - watch the parent's conversation for `Complete`, `Request`, and `Error` notifications. -* **Per-child state** - use the orchestration pill bar above the agent view header (in the Warp app) or the parent's **Sub-agents** tab on the [Runs page](https://oz.warp.dev/runs) (in the Oz web app) to see each child's live status. Both surfaces update as children transition through `INPROGRESS`, `SUCCEEDED`, `BLOCKED`, `FAILED`, `ERROR`, and `CANCELLED`. +* **Per-child state** - use the orchestration pill bar above the agent view header (in the Warp app) or the parent's **Sub-agents** tab on the Runs page (in the {VARS.WEB_APP}) to see each child's live status. Both surfaces update as children transition through `INPROGRESS`, `SUCCEEDED`, `BLOCKED`, `FAILED`, `ERROR`, and `CANCELLED`. * **Blocked children** - if a child blocks on user input (for example, a command approval request), open that child from the pill bar to resolve the block. The parent's transcript also reflects the child's `BLOCKED` state so the parent can wait, send a follow-up, or cancel the child. ## Related pages diff --git a/src/content/docs/agents/capabilities/computer-use/index.mdx b/src/content/docs/agents/capabilities/computer-use/index.mdx index 11ebbcbe2..3543f8a41 100644 --- a/src/content/docs/agents/capabilities/computer-use/index.mdx +++ b/src/content/docs/agents/capabilities/computer-use/index.mdx @@ -13,7 +13,7 @@ Computer Use enables agents to interact with desktop environments. The agent can A key use case is **testing UI changes** with a self-contained feedback loop, where the agent can verify that your code changes produce the expected visual and behavioral results without requiring manual testing. -## Overview +## Capabilities With Computer Use, agents can: @@ -42,7 +42,7 @@ Computer Use is **enabled by default** for cloud agent runs on Warp's built-in h Runs started from the Warp app don't use the server default: they always follow the app's **Computer use in Cloud Agents** setting ([`cloud_agent_computer_use_enabled`](/terminal/settings/all-settings/)), which is off by default. To control Computer Use for [Cloud Agents](/platform/) started from the Warp app, navigate to **Settings** > **Agents** > **Warp Agent** > **Experimental** > **Computer use in Cloud Agents**. -### Oz CLI +### CLI When running cloud agents with the [{VARS.WARP_AGENT_CLI}](/reference/cli/), use flags to control Computer Use per run: @@ -51,9 +51,9 @@ oz agent run-cloud --computer-use --prompt "" oz agent run-cloud --no-computer-use --prompt "" ``` -### Oz API +### API -When creating a cloud agent run with the [Oz API](/reference/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp's built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run: +When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/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: ```json { @@ -65,9 +65,9 @@ When creating a cloud agent run with the [Oz API](/reference/api-and-sdk/), the } ``` -For full API documentation, see the [Oz API & SDK](/reference/api-and-sdk/) reference. +For full API documentation, see the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) reference. -### Oz web app +### Web app In the {VARS.WEB_APP}, you can enable or disable Computer Use for: diff --git a/src/content/docs/agents/capabilities/computer-use/testing-and-recordings.mdx b/src/content/docs/agents/capabilities/computer-use/testing-and-recordings.mdx index 419c80bf0..6155e2b41 100644 --- a/src/content/docs/agents/capabilities/computer-use/testing-and-recordings.mdx +++ b/src/content/docs/agents/capabilities/computer-use/testing-and-recordings.mdx @@ -31,7 +31,7 @@ You don't need to ask the agent to record explicitly. Prompts like "test this ch ## How it works -1. **Confirm Computer Use is enabled.** Computer Use is enabled by default for cloud agent runs on Warp's built-in harness, so no setup is needed unless it was turned off for your run. See the [Computer Use](/agents/capabilities/computer-use/#enabling-computer-use) page for how to control it via the Warp app, the {VARS.WARP_AGENT_CLI}, or the Oz API. +1. **Confirm Computer Use is enabled.** Computer Use is enabled by default for cloud agent runs on Warp's built-in harness, so no setup is needed unless it was turned off for your run. See the [Computer Use](/agents/capabilities/computer-use/#enabling-computer-use) page for how to control it via the Warp app, the {VARS.WARP_AGENT_CLI}, or the {VARS.WARP_AUTOMATION_PLATFORM} API. 2. **Agent starts recording.** Once Computer Use is active, the agent begins a screen capture inside the sandbox. The recording is gated by your session's Computer Use approval. If you've already approved Computer Use for the run, recording starts automatically without a separate prompt. 3. **Agent exercises the UI.** The agent takes screenshots, clicks, types, scrolls, and drives the interface. Each successful interaction is tracked: when it started, when it finished, what actions it contained, and where the cursor moved. 4. **Agent stops and processes.** When the task is complete (or when the recording's configured time or size limit is reached), the agent stops capture. Before upload, the recording is post-processed: idle and thinking gaps are cut, leaving only the windows where real interaction happened, and action overlays are burned in so the video is annotated. @@ -43,7 +43,7 @@ You don't need to ask the agent to record explicitly. Prompts like "test this ch After the agent finishes its Computer Use session, any video recording appears as a block in the conversation. Clicking the block opens the full conversation view alongside the recording artifact. If the recording was produced by a cloud agent run, you can also access it by opening that run's transcript as a [cloud-synced conversation](/platform/viewing-cloud-agent-runs/). -### In the Oz web app +### In the web app Cloud agent runs are listed on the [Runs page of the {VARS.WEB_APP}](/platform/oz-web-app/#runs). Open a run to see its artifacts section, which lists any video recordings produced during that run. You can play the video directly from the run page or download it. @@ -81,7 +81,7 @@ The finished recording is attached to the pull request, giving a reviewer proof ### End-to-end QA of an existing flow -An agent walks through a critical user journey, such as the "New run" creation flow in the Oz web app, capturing the complete interaction. +An agent walks through a critical user journey, such as the "New run" creation flow in the {VARS.WEB_APP}, capturing the complete interaction. Example prompt: ```text @@ -90,7 +90,7 @@ Build the Oz web app and walk through the entire "New run" creation flow end to This gives you a reproducible, time-stamped clip of the flow that can be archived, diffed across releases, or shared with the team as a baseline. - + ### Reproducing a bug diff --git a/src/content/docs/agents/capabilities/full-terminal-use.mdx b/src/content/docs/agents/capabilities/full-terminal-use.mdx index 141c3f1a0..6a46f6dee 100644 --- a/src/content/docs/agents/capabilities/full-terminal-use.mdx +++ b/src/content/docs/agents/capabilities/full-terminal-use.mdx @@ -5,6 +5,7 @@ description: >- to monitor live output and run commands. --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; Full Terminal Use lets the Warp Agent operate directly inside interactive terminal applications like database shells, debuggers, text editors, and long-running servers. The agent can see the live terminal buffer, write commands, respond to prompts, and hand control back to you at any time. @@ -191,7 +192,7 @@ These settings apply to every session that uses Full Terminal Use. You can still All AI interactions from Full Terminal Use consume [credits](/support-and-community/plans-and-billing/credits/), including understanding your natural language requests. -Credits are consumed in a similar way as other Oz actions that use the same model and a similar context size. +Credits are consumed in a similar way as other Warp actions that use the same model and a similar context size. **Interactive sessions can consume more credits if:** diff --git a/src/content/docs/agents/capabilities/skills.mdx b/src/content/docs/agents/capabilities/skills.mdx index 8e3b6db0e..873ce1c1c 100644 --- a/src/content/docs/agents/capabilities/skills.mdx +++ b/src/content/docs/agents/capabilities/skills.mdx @@ -6,6 +6,7 @@ description: >- Create reusable instruction sets that teach agents specific tasks and share expertise across your team. --- +import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; import { FileTree } from '@astrojs/starlight/components'; @@ -413,7 +414,7 @@ This opens an interactive menu where you can: Warp maintains a public collection of ready-to-use skills in the [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. You can browse these skills for inspiration, copy them directly into your project's `.agents/skills/` directory, or adapt them to fit your team's workflows. -These same skills also appear as suggested agents in the [Oz web app](/platform/oz-web-app/), where you can run them directly in the cloud. +These same skills also appear as suggested agents in the [{VARS.WEB_APP}](/platform/oz-web-app/), where you can run them directly in the cloud. ## Suggested skills from Agent Memory @@ -434,7 +435,7 @@ This is useful when you want to reuse a skill's workflow but tailor the executio Skills can be used with both local and [cloud agents](/platform/) to create reusable, automated workflows. When running an agent via the CLI, web app, or API, you can specify a skill to provide the base instructions for the agent. -For a complete guide to running skill-based agents—including CLI usage, the Oz web app, scheduling, skill discovery, and API integration—see [Skills as Agents](/platform/skills-as-agents/). +For a complete guide to running skill-based agents—including CLI usage, the {VARS.WEB_APP}, scheduling, skill discovery, and API integration—see [Skills as Agents](/platform/skills-as-agents/). ## Related features diff --git a/src/content/docs/agents/cli-agents/claude-code.mdx b/src/content/docs/agents/cli-agents/claude-code.mdx index 935b34d93..d6e77a84f 100644 --- a/src/content/docs/agents/cli-agents/claude-code.mdx +++ b/src/content/docs/agents/cli-agents/claude-code.mdx @@ -6,6 +6,7 @@ description: >- Set up Claude Code in Warp with full notification support, rich input, code review, and more. --- +import { VARS } from '@data/vars'; Claude Code is Anthropic's agentic coding tool that operates directly in your terminal. It understands your codebase, executes commands, edits files, and manages Git workflows — all through natural language. For full documentation, see the [official Claude Code docs](https://code.claude.com/docs). @@ -14,7 +15,7 @@ Warp auto-detects Claude Code when you run it, giving you access to rich input c For installation, authentication, project configuration, and productivity tips, see the [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) guide. :::note -Claude Code is also available as a harness in Oz for cloud orchestration. See [Claude Code with Oz](/platform/harnesses/claude-code/). +Claude Code is also available as a harness in the {VARS.WARP_AUTOMATION_PLATFORM} for cloud orchestration. See [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/). ::: ## Setting up notifications @@ -75,6 +76,6 @@ Claude Code supports Warp's full set of agent integration features: * [Claude Code in Warp](https://www.warp.dev/agents/claude-code) — product overview * [Third-party CLI agents overview](/agents/cli-agents/overview/) — supported CLI agent integrations * [Remote Control](/agents/cli-agents/remote-control/) — publish a Claude Code session to monitor and steer it remotely -* [Claude Code with Oz](/platform/harnesses/claude-code/) — Claude Code as a cloud harness +* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) — Claude Code as a cloud harness * [OpenCode](/agents/cli-agents/opencode/) — OpenCode in Warp * [Codex](/agents/cli-agents/codex/) — Codex in Warp diff --git a/src/content/docs/agents/cli-agents/codex.mdx b/src/content/docs/agents/cli-agents/codex.mdx index 7e45948bd..5f24d2574 100644 --- a/src/content/docs/agents/cli-agents/codex.mdx +++ b/src/content/docs/agents/cli-agents/codex.mdx @@ -6,6 +6,7 @@ description: >- Set up Codex in Warp with notification support, rich input, code review, and more. --- +import { VARS } from '@data/vars'; Codex is OpenAI's open-source coding agent that runs in your terminal. It can write and edit code, execute commands, and navigate your codebase through natural language. For full documentation, see the [Codex GitHub repository](https://github.com/openai/codex). @@ -14,7 +15,7 @@ Warp auto-detects Codex when you run it, giving you access to rich input control For installation, authentication, project configuration, and productivity tips, see the [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) guide. :::note -Codex is also available as a harness in Oz for cloud orchestration. See [Codex with Oz](/platform/harnesses/codex/). +Codex is also available as a harness in the {VARS.WARP_AUTOMATION_PLATFORM} for cloud orchestration. See [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/). ::: ## Setting up notifications @@ -58,6 +59,6 @@ Codex supports Warp's full set of agent integration features: * [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) — step-by-step setup guide * [Codex in Warp](https://www.warp.dev/agents/codex) — product overview * [Third-party CLI agents overview](/agents/cli-agents/overview/) — supported CLI agent integrations -* [Codex with Oz](/platform/harnesses/codex/) — Codex as a cloud harness +* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) — Codex as a cloud harness * [Claude Code](/agents/cli-agents/claude-code/) — Claude Code in Warp * [OpenCode](/agents/cli-agents/opencode/) — OpenCode in Warp diff --git a/src/content/docs/agents/cli-agents/overview.mdx b/src/content/docs/agents/cli-agents/overview.mdx index 7bd8ce5ea..b1fda82a8 100644 --- a/src/content/docs/agents/cli-agents/overview.mdx +++ b/src/content/docs/agents/cli-agents/overview.mdx @@ -15,7 +15,7 @@ This feature set is also known as **universal agent support**. Looking for Warp's own CLI instead? The [Warp Agent CLI](/agents/cli/) runs the Warp Agent itself in any terminal. This page covers running third-party coding agents inside the Warp app. :::note -Claude Code and Codex are also supported as harnesses in Oz for [multi-agent orchestration](/platform/orchestration/). See [Harnesses in Oz](/platform/harnesses/). +Claude Code and Codex are also supported as harnesses in the {VARS.WARP_AUTOMATION_PLATFORM} for [multi-agent orchestration](/platform/orchestration/). See [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/). ::: ## Supported agents diff --git a/src/content/docs/agents/cli/cloud-and-orchestration.mdx b/src/content/docs/agents/cli/cloud-and-orchestration.mdx index 4bc5c14ed..8aa465260 100644 --- a/src/content/docs/agents/cli/cloud-and-orchestration.mdx +++ b/src/content/docs/agents/cli/cloud-and-orchestration.mdx @@ -6,7 +6,7 @@ description: >- --- import { VARS } from '@data/vars'; -The {VARS.WARP_CLI} connects your terminal sessions to Oz. You can hand off a local conversation to a cloud agent, pick a finished cloud run back up in your terminal, and coordinate multiple agents working in parallel, all without leaving the CLI. +The {VARS.WARP_CLI} connects your terminal sessions to the {VARS.WARP_AUTOMATION_PLATFORM}. You can hand off a local conversation to a cloud agent, pick a finished cloud run back up in your terminal, and coordinate multiple agents working in parallel, all without leaving the CLI. ## Hand off to a cloud agent diff --git a/src/content/docs/agents/cli/index.mdx b/src/content/docs/agents/cli/index.mdx index e10b37bdd..e1b746c20 100644 --- a/src/content/docs/agents/cli/index.mdx +++ b/src/content/docs/agents/cli/index.mdx @@ -27,10 +27,10 @@ To get a working setup in a few minutes, follow the [quickstart](/agents/cli/qui * **[Model choice](/agents/cli/models-and-usage/)** - Pick a model per conversation, bring your own provider API keys, and track credit usage. * **[Customization](/agents/cli/configuration/)** - Configure themes, the statusline, and the start screen through a local settings file. -## How it relates to the Warp app and Oz +## How it relates to the Warp app and cloud agents * **The Warp app** - The CLI runs the same [Warp Agent](/platform/harnesses/warp-agent/) harness as the Warp app, so your account, plan, model access, rules, and skills work the same in both. The CLI doesn't require the Warp app to be installed. -* **{VARS.WARP_AUTOMATION_PLATFORM}** - {VARS.WARP_AUTOMATION_PLATFORM} is Warp's programmable platform for running and coordinating agents at scale. The CLI connects to the same platform. Conversations sync to your Warp account, and you can hand work off to [cloud agents](/agents/cli/cloud-and-orchestration/) or continue a cloud run from your terminal. +* **{VARS.WARP_AUTOMATION_PLATFORM}** - The {VARS.WARP_AUTOMATION_PLATFORM} is Warp's programmable platform for running and coordinating agents at scale. The CLI connects to the same platform. Conversations sync to your Warp account, and you can hand work off to [cloud agents](/agents/cli/cloud-and-orchestration/) or continue a cloud run from your terminal. ## Checking your account, plan, and billing diff --git a/src/content/docs/agents/cli/reference.mdx b/src/content/docs/agents/cli/reference.mdx index 752efe138..7c819c762 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** > **Oz Cloud API Keys**. See the [API keys reference](/reference/cli/api-keys/) for details. +Create a key in the Warp app under **Settings** > **Cloud platform** > **{VARS.WARP_AUTOMATION_PLATFORM} Cloud API Keys**. See the [API keys reference](/reference/cli/api-keys/) for details. ### `--auto-approve` diff --git a/src/content/docs/agents/index.mdx b/src/content/docs/agents/index.mdx index facd27061..3cea38d07 100644 --- a/src/content/docs/agents/index.mdx +++ b/src/content/docs/agents/index.mdx @@ -4,10 +4,13 @@ description: >- The Warp Agent runs commands in a real terminal, carries your context across every surface, and works interactively or in the background. --- +import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; The **Warp Agent** is Warp's built-in coding agent. It works through multi-step tasks on its own, running commands in a real terminal and using the output to decide what to do next. You stay in the loop, approving actions and reviewing diffs before anything lands. +This page covers where to run the agent, the third-party CLI agents Warp supports, and the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/), which runs and coordinates agents at scale. + --- ## Where to use the Warp Agent @@ -16,7 +19,7 @@ You reach the same agent three ways. Which one you pick depends on where you're * **In the Warp app** - The full experience, with code review, agent management, and the terminal beside your conversation. * [**In any terminal, with the Warp Agent CLI**](/agents/cli/) - Run the `warp` command to start a conversation in any terminal emulator, over SSH, or on a machine where the Warp app isn't installed. -* [**In the cloud, as a cloud agent**](/platform/) - Run the agent in the background from a trigger, a schedule, or an integration, without keeping a session open. Cloud agents run on [Oz](/platform/overview/), Warp's platform for environments, triggers, orchestration, and observability. +* [**In the cloud, as a cloud agent**](/platform/) - Run the agent in the background from a trigger, a schedule, or an integration, without keeping a session open. Cloud agents run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/), Warp's platform for environments, triggers, orchestration, and observability. --- @@ -47,6 +50,16 @@ Separately from the Warp Agent, Warp gives third-party CLI coding agents first-c --- +## The platform behind the agent + +The [**{VARS.WARP_AUTOMATION_PLATFORM}**](/platform/overview/) 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, along with a CLI, API, and SDK for driving agents programmatically. + +To automate an entire workflow rather than a single task, use [Warp Factories](/factories/). Built on the {VARS.WARP_AUTOMATION_PLATFORM}, a factory runs a team of cloud agents that triage, spec, implement, review, and verify work. + +The {VARS.WARP_AUTOMATION_PLATFORM} tab covers the platform in full. + +--- + ## 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. diff --git a/src/content/docs/agents/inference/model-choice.mdx b/src/content/docs/agents/inference/model-choice.mdx index 770da6856..147f6113d 100644 --- a/src/content/docs/agents/inference/model-choice.mdx +++ b/src/content/docs/agents/inference/model-choice.mdx @@ -6,6 +6,7 @@ description: >- Choose from a curated set of top LLMs for Warp's Agents (or let Warp auto-select the best model). --- +import { VARS } from '@data/vars'; Warp lets you choose from a curated set of large language models to power your agents, or let Warp auto-select the best model for each task. Models from OpenAI, Anthropic, Google, and open source providers are available, with configurable reasoning levels and per-profile defaults. You can also define [custom routers](/agents/inference/custom-routers/) that pick a model for each task using your own logic. @@ -15,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 [Oz 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](/reference/cli/). ### Auto models diff --git a/src/content/docs/agents/local-agents/interacting-with-agents/index.mdx b/src/content/docs/agents/local-agents/interacting-with-agents/index.mdx index 2095b83f7..97518d26a 100644 --- a/src/content/docs/agents/local-agents/interacting-with-agents/index.mdx +++ b/src/content/docs/agents/local-agents/interacting-with-agents/index.mdx @@ -5,6 +5,7 @@ description: >- and multi-thread support. --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; Agent conversations in Warp are multi-turn interactions tied to terminal sessions. Continue previous threads with follow-ups, manage conversation history, attach context from blocks and files, and run multiple conversations simultaneously across windows, tabs, or panes. @@ -197,7 +198,7 @@ The **Active** dropdown lists conversations where you have sent at least one que * Select a conversation to switch to it immediately. * The conversation you're currently viewing is highlighted. -* Cloud agent conversations and Oz runs always appear in **Active** while they are open. +* Cloud agent conversations and runs always appear in **Active** while they are open. #### Past diff --git a/src/content/docs/agents/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx b/src/content/docs/agents/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx index b6d975135..87795a795 100644 --- a/src/content/docs/agents/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx +++ b/src/content/docs/agents/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx @@ -4,6 +4,7 @@ description: >- Warp provides two distinct modes: a clean terminal for commands, and a dedicated conversation view for multi-turn agent workflows. --- +import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; Warp provides two distinct modes: a clean terminal for running shell commands, and a dedicated conversation view for multi-turn interactions with the Warp Agent. Terminal mode keeps the interface minimal by default, while Agent Mode surfaces full controls for model selection, voice input, image attachments, and conversation management. @@ -17,7 +18,7 @@ Warp provides two distinct modes: a clean terminal for running shell commands, a Before diving in, here are two key concepts: * **Terminal session** - Your shell environment where you run commands. This is the default mode when you open Warp—a clean, traditional terminal input. -* **Agent conversation** - A multi-turn interaction with Oz. Conversations maintain context across exchanges and have their own dedicated view with richer controls. +* **Agent conversation** - A multi-turn interaction with the {VARS.WARP_AUTOMATION_PLATFORM}. Conversations maintain context across exchanges and have their own dedicated view with richer controls. Terminal and Agent modes make switching between these two contexts seamless while keeping them visually distinct. @@ -132,7 +133,7 @@ Cloud agent conversations are always stored in the cloud. For more details on ac * **From the conversation list panel** - Cloud conversations appear alongside local conversations. Click to open. * **From the management view** - Use the [Agent Management view](/platform/managing-cloud-agents/) to see all cloud agent runs, filter by status, and click any row to open the conversation. -* **From the Oz web app** - Access your cloud agents from the [Oz web app](https://oz.warp.dev) to manage runs from any browser. +* **From the {VARS.WEB_APP}** - Access your cloud agents from the {VARS.WEB_APP} to manage runs from any browser. For more on cloud agents, see [Cloud Agents overview](/platform/). diff --git a/src/content/docs/agents/local-agents/session-sharing.mdx b/src/content/docs/agents/local-agents/session-sharing.mdx index ada4bec43..ad56b38ea 100644 --- a/src/content/docs/agents/local-agents/session-sharing.mdx +++ b/src/content/docs/agents/local-agents/session-sharing.mdx @@ -4,9 +4,10 @@ description: >- Share live agent sessions so collaborators can view, steer, and interact with agent activity from any device — in real time or asynchronously. --- +import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; -**Agent Session Sharing** extends Warp's regular [Session Sharing](/knowledge-and-collaboration/session-sharing/) to include full visibility and control over Agent activity. Share any agent session — Oz or third-party — so collaborators can watch progress, review output, and steer the agent from the Warp app, a web browser, or a mobile device. +**Agent Session Sharing** extends Warp's regular [Session Sharing](/knowledge-and-collaboration/session-sharing/) to include full visibility and control over Agent activity. Share any agent session — {VARS.WARP_AUTOMATION_PLATFORM} or third-party — so collaborators can watch progress, review output, and steer the agent from the Warp app, a web browser, or a mobile device. Use Agent Session Sharing when teammates need the execution context behind an agent's work, not just the final answer or code diff. A shared agent session can show the prompt, responses, thinking states, tool use, planning steps, terminal output, and follow-up messages in one reviewable link. diff --git a/src/content/docs/changelog/2025.mdx b/src/content/docs/changelog/2025.mdx index 64e827069..b96e1c3fd 100644 --- a/src/content/docs/changelog/2025.mdx +++ b/src/content/docs/changelog/2025.mdx @@ -3,6 +3,7 @@ title: "Changelog — 2025" description: >- Warp release notes for 2025. Updates ship weekly, typically on Thursdays. --- +import { VARS } from '@data/vars'; Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) @@ -18,7 +19,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd **Bug fixes** -* Fixed a bug where Oz CLI runs could get stuck trying to run a denylisted command. +* Fixed a bug where {VARS.WARP_AGENT_CLI} runs could get stuck trying to run a denylisted command. ### 2025.12.10 (v0.2025.12.10.08.12) @@ -42,7 +43,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd **Improvements** -* The Oz CLI now displays more detailed information when the agent tries to take a prohibited action. +* The {VARS.WARP_AGENT_CLI} now displays more detailed information when the agent tries to take a prohibited action. * Allow dragging file paths from the Project Explorer into active terminal commands like claude code and gemini for referencing files and folders. **Bug fixes** @@ -50,7 +51,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd * Fixed a bug that could cause unbounded memory growth when using Warpified subshells or the legacy (non-tmux) SSH Warpify implementation. * Fixed a bug that could cause `comm` errors to appear in Warpified subshells. * \[Windows] Fixed keybinding for "find in code editor." This is now `CTRL-SHIFT-F` and configurable from Settings > Keyboard shortcuts. -* Ensured that the Oz CLI is available automatically on macOS. +* Ensured that the {VARS.WARP_AGENT_CLI} is available automatically on macOS. * Fixed toast messages showing "Notebook" instead of "Plan" when taking actions on Plans in Warp Drive. ### 2025.11.19 (v0.2025.11.19.08.12) @@ -100,7 +101,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd **Improvements** * Display conversation summaries when summarization is triggered. -* Added completions for the Oz CLI. +* Added completions for the {VARS.WARP_AGENT_CLI}. * Updated community links from Discord to Slack throughout the app. **Bug Fixes** @@ -136,7 +137,7 @@ Submit bugs and feature requests on our [GitHub board!](https://github.com/warpd * Added confirmation dialog when cancelling AI summarization requests. * You can now expand Suggested Code Diffs further on down arrow. * Restore closed panes using `CMD-SHIFT-T` or `CTRL-ALT-T` on Windows / Linux within 60 seconds of them being closed. -* Added shell completions for the Oz CLI. +* Added shell completions for the {VARS.WARP_AGENT_CLI}. * Warp Drive Environment Variables are now supported for Warp for Windows (PowerShell, Git Bash, and WSL). * Enriched the model picker to include detailed specs of each model's intelligence, speed and cost. diff --git a/src/content/docs/changelog/2026.mdx b/src/content/docs/changelog/2026.mdx index 3ee814b7b..edbadef2f 100644 --- a/src/content/docs/changelog/2026.mdx +++ b/src/content/docs/changelog/2026.mdx @@ -1426,7 +1426,7 @@ Oz is Warp's orchestration platform for cloud agents: launch parallel agents, au * **Run Cloud Agents from anywhere with built-in tracking** — start agents from Warp or via the CLI, triggers, or schedules. Every run is auditable and steerable. [Cloud Agents docs →](https://docs.warp.dev/platform/) * **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 [Oz web app](https://oz.warp.dev). +* **Track agents from the web** — manage runs, create schedules, configure environments, and set up integrations from any browser in the Oz web app. * **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/). diff --git a/src/content/docs/enterprise/enterprise-features/analytics-api.mdx b/src/content/docs/enterprise/enterprise-features/analytics-api.mdx index 959f15fba..be500dcb3 100644 --- a/src/content/docs/enterprise/enterprise-features/analytics-api.mdx +++ b/src/content/docs/enterprise/enterprise-features/analytics-api.mdx @@ -6,8 +6,9 @@ description: >- sidebar: label: "Analytics API" --- +import { VARS } from '@data/vars'; -The Enterprise Analytics API lets enterprise admins pull Warp usage data into their own dashboards, cost-allocation tooling, or audit pipelines. It exposes three read-only endpoints over HTTPS that return aggregated team metrics, per-user rollups, and message-level activity events for the agents your team runs in Warp and Oz. +The Enterprise Analytics API lets enterprise admins pull Warp usage data into their own dashboards, cost-allocation tooling, or audit pipelines. It exposes three read-only endpoints over HTTPS that return aggregated team metrics, per-user rollups, and message-level activity events for the agents your team runs in Warp and the {VARS.WARP_AUTOMATION_PLATFORM}. :::note[Early access] The Enterprise Analytics API is in Early Access. It is available to all enterprise teams. To start collecting data for your team, an admin must open the Warp app and turn on **Enterprise Usage Reporting (Early Access)** in **Admin Panel** > **Privacy** — no usage data is recorded until that toggle is on. @@ -28,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** > **Oz Cloud 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** > **{VARS.WARP_AUTOMATION_PLATFORM} Cloud 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. * **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 @@ -296,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** > **Oz Cloud 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** > **{VARS.WARP_AUTOMATION_PLATFORM} Cloud 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. ### Are these calls billed? 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 c8805b257..1130480de 100644 --- a/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx +++ b/src/content/docs/enterprise/enterprise-features/architecture-and-deployment.mdx @@ -4,6 +4,7 @@ description: >- Understand Warp's system architecture and choose the right deployment model for your organization - Warp-hosted, self-hosted, or hybrid. --- +import { VARS } from '@data/vars'; Warp's architecture separates the **control plane** (orchestration, observability, and LLM inference) from the **execution plane** (where agents run, code is accessed, and commands execute). This separation gives enterprise teams flexibility to choose where sensitive workloads run while maintaining centralized management and visibility. @@ -14,9 +15,9 @@ Use this information to evaluate which deployment model fits your organization's Warp's cloud agent infrastructure has four key components: 1. **Trigger** - What starts an agent run (CI step, webhook, cron schedule, Slack mention, CLI command, or API/SDK call). -2. **Orchestration** - What decides what to run and tracks it (Oz orchestrator or your own system). +2. **Orchestration** - What decides what to run and tracks it ({VARS.WARP_AUTOMATION_PLATFORM} orchestrator or your own system). 3. **Execution** - Where the agent actually runs (Warp-hosted environment, your infrastructure, or your existing CI/orchestrator). -4. **Visibility** - How the team monitors and intervenes (Oz dashboard, session sharing, APIs/SDKs). +4. **Visibility** - How the team monitors and intervenes ({VARS.DASHBOARD}, session sharing, APIs/SDKs). {/* TODO: Insert system architecture diagram once received from design team */} @@ -34,7 +35,7 @@ Warp-hosted is the default deployment model. Agents run on Warp-managed infrastr ### How it works * Agents execute in **isolated Docker containers** on Warp-hosted infrastructure (GCP). -* The Oz orchestrator manages agent lifecycle - provisioning, execution, monitoring, and cleanup. +* The {VARS.WARP_AUTOMATION_PLATFORM} orchestrator manages agent lifecycle - provisioning, execution, monitoring, and cleanup. * Environments are ephemeral and destroyed after each run. ### Triggers @@ -75,9 +76,9 @@ Self-hosted deployments use a split architecture: * You control scheduling, scaling, and environment setup. * Warp provides cloud connectivity, shared context, visibility, and session sharing. -**Managed** - Run the `oz-agent-worker` daemon to let the Oz platform orchestrate agents in isolated Docker containers on your infrastructure. +**Managed** - Run the `oz-agent-worker` daemon to let Warp orchestrate agents in isolated Docker containers on your infrastructure. -* The worker process connects to Oz via WebSocket and receives tasks automatically. +* The worker process connects to the {VARS.WARP_AUTOMATION_PLATFORM} via WebSocket and receives tasks automatically. * Agents run in isolated Docker containers managed by the worker. * You get the same orchestration capabilities as Warp-hosted, but execution stays on your infrastructure. @@ -94,7 +95,7 @@ Self-hosted agents require **outbound-only** network access. No inbound network * Compliance or security requirements prevent using Warp-hosted compute. * Source code and execution must stay within your network boundary. -* You want Oz orchestration and visibility without sending code to Warp's infrastructure. +* You want {VARS.WARP_AUTOMATION_PLATFORM} orchestration and visibility without sending code to Warp's infrastructure. ## Hybrid deployments @@ -104,7 +105,7 @@ Organizations can combine Warp-hosted and self-hosted execution to balance conve * Route sensitive workloads (e.g., production code, regulated data) to self-hosted agents. * Route less sensitive workloads (e.g., open-source tooling, internal utilities) to Warp-hosted agents. -* Both execution modes share the same Oz dashboard, session sharing, and API/SDK visibility. +* Both execution modes share the same {VARS.DASHBOARD}, session sharing, and API/SDK visibility. ### Example configurations @@ -151,7 +152,7 @@ Consider the following when selecting a deployment model: ## Related resources -* [Deployment Patterns](/platform/deployment-patterns/) - Detailed patterns for CLI-only, Oz-hosted, and self-hosted setups +* [Deployment Patterns](/platform/deployment-patterns/) - Detailed patterns for CLI-only, {VARS.WARP_AUTOMATION_PLATFORM}-hosted, and self-hosted setups * [Security overview](/enterprise/security-and-compliance/security-overview/) - Data handling, encryption, and compliance details * [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) - Route inference through your own cloud infrastructure * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure agent policies and security settings diff --git a/src/content/docs/enterprise/enterprise-features/byollm-aws-bedrock.mdx b/src/content/docs/enterprise/enterprise-features/byollm-aws-bedrock.mdx index 4bb536c70..b285f4b23 100644 --- a/src/content/docs/enterprise/enterprise-features/byollm-aws-bedrock.mdx +++ b/src/content/docs/enterprise/enterprise-features/byollm-aws-bedrock.mdx @@ -6,6 +6,7 @@ description: >- Route Warp Agent inference through your AWS account with Bedrock BYOLLM, IAM credentials, and AWS-billed inference. --- +import { VARS } from '@data/vars'; Warp's **AWS Bedrock** BYOLLM integration routes agent inference through your own AWS account using **Amazon Bedrock**. Your team keeps using Warp's agents as usual, while eligible requests execute against Claude models hosted in your AWS account, billed to your AWS account and governed by your IAM controls. @@ -248,7 +249,7 @@ This applies the OIDC role only to runs from a specific named agent. To safely test BYOLLM, configure it on a single named agent first. Misconfigurations scoped to one agent only affect that agent's runs, not the whole team. ::: -In the Oz web app: +In the {VARS.WEB_APP}: 1. [Create a new agent](/platform/oz-web-app/#creating-a-new-agent) or edit an existing one. 2. In the agent form, expand the **AWS Bedrock** section. diff --git a/src/content/docs/enterprise/getting-started/getting-started-developers.mdx b/src/content/docs/enterprise/getting-started/getting-started-developers.mdx index 3ef3eb557..f434a7084 100644 --- a/src/content/docs/enterprise/getting-started/getting-started-developers.mdx +++ b/src/content/docs/enterprise/getting-started/getting-started-developers.mdx @@ -4,10 +4,11 @@ description: >- Download Warp, log in to your team, and start using agents, Codebase Context, and collaborative features to accelerate your development workflow. --- +import { VARS } from '@data/vars'; This guide helps developers get up and running with their team in Warp. You'll learn how to download Warp, log in with your organization's SSO, and configure key features like Codebase Context, Warp Drive, and Agent Profiles to accelerate your work across the entire SDLC (all while staying in your terminal). -When you use agents in Warp, you're working with **Warp's built-in agents**. Oz is Warp's programmable platform for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. Oz provides the orchestration, tracking, and control plane that makes scaling agent workflows seamless. +When you use agents in Warp, you're working with **Warp's built-in agents**. The {VARS.WARP_AUTOMATION_PLATFORM} is Warp's programmable system for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. The {VARS.WARP_AUTOMATION_PLATFORM} provides the orchestration, tracking, and control plane for scaling agent workflows. :::note New to Warp Enterprise? Try the [Enterprise quickstart](/enterprise/getting-started/quickstart/) for a 10-minute walkthrough of SSO login, Warp setup, and running your first agent. diff --git a/src/content/docs/enterprise/getting-started/quickstart.mdx b/src/content/docs/enterprise/getting-started/quickstart.mdx index 073248e76..3142c8644 100644 --- a/src/content/docs/enterprise/getting-started/quickstart.mdx +++ b/src/content/docs/enterprise/getting-started/quickstart.mdx @@ -6,6 +6,7 @@ description: >- sidebar: label: "Quickstart" --- +import { VARS } from '@data/vars'; This quickstart walks you through the essentials: logging in via SSO, setting up Warp, and running your first agent. You can complete this in under 10 minutes. @@ -34,7 +35,7 @@ If you have an existing Warp account from before your organization enabled SSO, ## 3. Configure and run your first agent -When you use agents in Warp, you're working with **Warp's built-in agents**. Oz is Warp's programmable platform for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. +When you use Agent Mode in Warp, you're working with the Warp Agent, Warp's built-in agent. The {VARS.WARP_AUTOMATION_PLATFORM} is Warp's programmable system for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. ### Index your codebase @@ -51,14 +52,14 @@ Start a conversation right in the terminal. Try the following prompt: Explain the architecture of this project ``` -Oz reads your codebase, understands its structure, and responds with a context-aware explanation. +The Warp Agent reads your codebase, understands its structure, and responds with a context-aware explanation. ### Try more prompts * **Write code** - "Add input validation to the signup form" * **Debug** - "Why is this test failing?" (paste the error output) * **Explore** - "What patterns does this repo use for error handling?" -* **Plan** - Use `/plan` to have Oz create a structured task plan for complex features +* **Plan** - Use `/plan` to have the Warp Agent create a structured task plan for complex features ## 4. Run a cloud agent @@ -76,7 +77,7 @@ From the Warp app terminal input, run the command: ``` This launches an interactive flow that guides you through environment setup. -**Option 2: Oz web app** +**Option 2: {VARS.WEB_APP}** Go to the [Environments page](https://app.warp.dev/environments) and click **Create Environment**. @@ -88,7 +89,7 @@ Once your environment is ready, use the following command to launch a cloud agen oz agent run-cloud --env my-env --prompt "Review the open PRs in this repo" ``` -Monitor and steer cloud agents from the Oz dashboard or directly in Warp. +Monitor and steer your agents from the {VARS.DASHBOARD} or directly in Warp. ## Next steps diff --git a/src/content/docs/enterprise/index.mdx b/src/content/docs/enterprise/index.mdx index c9e69b85f..c2945eebf 100644 --- a/src/content/docs/enterprise/index.mdx +++ b/src/content/docs/enterprise/index.mdx @@ -4,13 +4,15 @@ description: >- Warp Enterprise provides the security, control, and collaboration features organizations need to deploy Warp across their engineering teams at scale. --- +import { VARS } from '@data/vars'; Warp Enterprise is built for organizations that want to accelerate software development with agents while maintaining security, compliance, and administrative control. It brings Warp's **Agentic Development Environment** to your entire engineering organization with the governance features IT and security teams require. -Warp has two core products: +Warp has three products: * **Warp Terminal** - A modern terminal designed for agentic development where developers run commands, collaborate with agents, and orchestrate autonomous work from the command line. -* **Oz** - Warp's programmable platform for running and coordinating agents at scale. Oz powers all agents in Warp, whether they run locally or in the cloud, and provides the orchestration, tracking, and control plane for scalable agent workflows. +* **{VARS.WARP_AUTOMATION_PLATFORM}** - Warp's programmable system for running and coordinating agents at scale. The {VARS.WARP_AUTOMATION_PLATFORM} powers all agents in Warp, whether they run locally or in the cloud, and provides the orchestration, tracking, and control plane for scalable agent workflows. +* [**Warp Factories**](/factories/) - Warp's product for building and operating software factories, where cloud agents triage, spec, implement, review, and verify work, and humans approve key decisions. ## Who Warp Enterprise is for @@ -46,10 +48,10 @@ Warp Enterprise serves three primary audiences: ### Agent capabilities * **State-of-the-art agents** - Multi-model agents with full terminal access, code editing, and autonomous task execution * **Cloud agents** - Run agents in the cloud for unlimited parallelization, background automation, and long-running workflows. Perfect for PR reviews, scheduled tasks, and distributed work across multiple repositories -* **Integrated control plane** - Launch, orchestrate, and manage local, cloud, and autonomous agents from a unified interface. Track all agent activity across your team from the Oz dashboard +* **Integrated control plane** - Launch, orchestrate, and manage local, cloud, and autonomous agents from a unified interface. Track all agent activity across your team from the {VARS.DASHBOARD} * **Agent Profiles** - Customize agent behavior, models, autonomy levels, and permissions * **Rules and guardrails** - Enforce coding standards, tech stack preferences, and security practices through team-wide or project-specific rules -* **Multi-agent support** - Support for all major models and CLI coding agents (Oz, Claude Code, Codex, Copilot) +* **Multi-agent support** - Support for all major models and CLI coding agents ({VARS.WARP_AUTOMATION_PLATFORM}, Claude Code, Codex, Copilot) ## What this section covers diff --git a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx index d2eb2c1bf..eb531dd0c 100644 --- a/src/content/docs/enterprise/security-and-compliance/security-overview.mdx +++ b/src/content/docs/enterprise/security-and-compliance/security-overview.mdx @@ -5,6 +5,7 @@ description: >- compliance certifications to ensure your organization's requirements are met. --- +import { VARS } from '@data/vars'; Warp builds security and compliance into its core, keeping **developers in control** while enabling powerful agent workflows. This overview explains how Warp handles your data, what security controls are available, and how Warp meets enterprise security standards. @@ -31,7 +32,7 @@ How data collection works by plan: * **Business and Enterprise** - Team admins can enforce data collection settings for the entire team. Data collection is **disabled by default**. :::note -Some product features — including cloud conversations and Oz runs — require storing conversation data to function. This data is stored to power the product experience and is separate from analytics or telemetry data collection. +Some product features — including cloud conversations and {VARS.PLATFORM_RUN}s — require storing conversation data to function. This data is stored to power the product experience and is separate from analytics or telemetry data collection. ::: Some models carry provider-specific data retention requirements and are therefore not covered by ZDR. For Enterprise teams, these models are **off by default**; a workspace admin must explicitly enable them in the [Admin Panel](/enterprise/team-management/admin-panel/#models-settings). @@ -131,7 +132,7 @@ Self-hosted deployments use a split architecture: Two deployment modes are available: * **Unmanaged** - Use `oz agent run` to run agents in your existing orchestrator or CI environment. Supports Linux, macOS, and Windows with no Docker dependency. -* **Managed** - Run the `oz-agent-worker` daemon to let the Oz platform orchestrate agents in isolated Docker containers on your infrastructure. +* **Managed** - Run the `oz-agent-worker` daemon to let Warp orchestrate agents in isolated Docker containers on your infrastructure. Agent runs are fully tracked and steerable in both modes. No inbound network access is required. diff --git a/src/content/docs/enterprise/team-management/admin-panel.mdx b/src/content/docs/enterprise/team-management/admin-panel.mdx index 67aed5140..0e250dec8 100644 --- a/src/content/docs/enterprise/team-management/admin-panel.mdx +++ b/src/content/docs/enterprise/team-management/admin-panel.mdx @@ -7,6 +7,7 @@ description: >- sidebar: label: "Admin panel" --- +import { VARS } from '@data/vars'; The Admin Panel provides administrators with centralized control over team settings in Warp. Configure agent behavior, security policies, codebase indexing, and collaboration features for your entire organization from a single interface. @@ -268,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 Oz by Warp GitHub App, and it tells Warp which team owns runs started from the [GitHub integration](/platform/integrations/github/) when someone mentions `@oz-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](/reference/cli/api-keys/) clone repositories and open pull requests using the Oz by Warp 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: @@ -284,7 +285,7 @@ To configure: The organizations and repository access shown here reflect the Oz by Warp GitHub App installation scope, which is configured in [GitHub settings](https://github.com/settings/installations). To change which repositories the app can access, edit the installation directly in GitHub. :::note -This setting controls which GitHub App installation agent API key runs authenticate with, and which GitHub organizations can start [GitHub integration](/platform/integrations/github/) runs for this team. Runs from an `@oz-agent` mention also authenticate with the installation's GitHub App token, so their repository access comes from the app installation rather than the person who wrote the mention. Runs triggered from a personal API key, Slack, Linear, or the Warp app continue to use that user's own GitHub authorization. For more details, see [Team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). +This setting controls which GitHub App installation agent API key runs authenticate with, and which GitHub organizations can start [GitHub integration](/platform/integrations/github/) runs for this team. Runs from an `@warp-agent` mention also authenticate with the installation's GitHub App token, so their repository access comes from the app installation rather than the person who wrote the mention. Runs triggered from a personal API key, Slack, Linear, or the Warp app continue to use that user's own GitHub authorization. For more details, see [Team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). ::: ## Multi-admin functionality diff --git a/src/content/docs/factories/automation-filters.mdx b/src/content/docs/factories/automation-filters.mdx new file mode 100644 index 000000000..a81800254 --- /dev/null +++ b/src/content/docs/factories/automation-filters.mdx @@ -0,0 +1,80 @@ +--- +title: Automation filters +description: >- + Automation filters decide which events from connected tools start factory + runs: matching rules, per-source filters, and what filters don't control. +sidebar: + label: Automation filters +--- + +Automation filters decide which events from your connected tools start factory work. Every trigger on a [factory automation](/factories/connect-your-factory/) carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them. + +## How matching works + +An event starts an automation only when it matches the trigger's provider, its event type, and every filter set on that trigger: + +* **Every filter must match.** A trigger that sets both a team and a label matches only events carrying both. +* **Within one filter, any value matches.** A **Labels** filter listing `bug` and `regression` matches an issue with either label. +* **A filter you leave empty matches everything.** A trigger with no filters at all starts work for every event of its type. + +One event can match more than one automation, and each match starts its own run. If a single action starts duplicate runs, narrow or remove one of the overlapping triggers. + +## Filters route work; they don't restrict access + +Filters decide when work starts, not what a running agent can reach. Access comes from what you authorize on each provider — the GitHub App installation, the GitLab bot's project membership, the Slack app's authorization, the Linear OAuth scope, or the Jira app installation. Tightening a filter never shrinks that access, and removing one never widens it. To change what an integration can reach, change what you authorize for that provider. + +Filters are still your main control over who starts runs. On GitHub and GitLab, the event author doesn't need to be a Warp team member, so use author, member, and branch filters to decide whose activity starts work. Slack mentions and direct messages additionally require a Slack account linked to a member of the factory's Warp team. + +## What each source can filter on + +Every source filters on where the event happened — a repository, project, conversation, or team. The remaining filters vary by source and event type: + +| Source | Filters | +| --- | --- | +| [Slack](/factories/integrations/slack/) | Conversations, authors or members, keywords, emoji, and reacted-message authors | +| [GitHub](/factories/integrations/github/) | Repository, branches, base branches, paths, labels, authors, assignees, mentioned users or teams, reviewers, review states, workflows, and conclusions | +| [GitLab](/factories/integrations/gitlab/) | Project, actions, and base branch | +| [Linear](/factories/integrations/linear/) | Teams, labels, project, workflow state, assignee, mentioned user, and, for comment events, a specific issue | +| [Jira](/factories/integrations/jira/) | Jira projects and assignment keywords | + +Each integration guide lists which filters appear on which event types. + +## Edit filters on an automation + +1. In the factory's dashboard, open **Automations**, then create an automation or edit an existing one. +2. Under **Triggers**, open a trigger and set the filters shown for its event. Click **More filters** for the event-specific options. +3. Click **Save**. To confirm the routing works, send a matching test event, such as opening a test issue, and check that a work item starts in the factory dashboard. + +Review the default automations Warp creates when you connect a provider, too: their filters are starting points, not fixed rules. + +## Filters in definitions as code + +In a [factory definition](/factories/factory-as-code/), each entry under an automation's `triggers` takes an optional `filter` whose keys mirror the filters in the automation editor: + +```markdown title="automations/labeled-issue/automation.md" +--- +enabled: true +agent: foreman +triggers: + - provider: github + event: issue_labeled + filter: + repos: [acme/payments-service] + labels: [factory-ready] +--- + +Review the labeled issue and decide the next required stage. +``` + +The same matching rules apply: every key must match, any listed value within a key matches, and an omitted key matches everything. Each integration guide shows the keys its provider accepts. + +## Troubleshooting + +* **A matching event doesn't start work** - Confirm the automation is enabled and the trigger's event type matches, then check every filter; a single mismatch prevents routing. Each integration guide's troubleshooting section covers provider-specific causes, such as app installation coverage. + +## Related pages + +* [Connect your factory](/factories/connect-your-factory/) - Choose the sources that route work into the factory. +* [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/) integration guides - Per-source setup, events, and filter details. +* [Definitions as code](/factories/factory-as-code/) - Manage automations, triggers, and filters as version-controlled files. +* [Factory dashboard](/factories/factory-dashboard/) - Create and edit automations in the factory's **Automations** view. diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx new file mode 100644 index 000000000..38178a948 --- /dev/null +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -0,0 +1,89 @@ +--- +title: Connect your factory +description: >- + Route work into your factory from Slack, GitHub, GitLab, Linear, Jira, local + agents, direct runs, and schedules. +sidebar: + label: "Connect your factory" +--- + +Connect your factory to the tools where your team already discusses, tracks, and reviews work. Wherever work starts, the factory keeps the original context — the thread, issue, or pull request — and posts results back to the same place. + +## Choose a source + +Pick the sources that match where work starts for your team. You can connect more than one. + +| Source | Best for | Where follow-ups continue | +| --- | --- | --- | +| [Slack](/factories/integrations/slack/) | Chat and support requests | The Slack thread or DM | +| [GitHub](/factories/integrations/github/) | Issues, pull requests, reviews, and CI | The issue, pull request, or review thread | +| [GitLab](/factories/integrations/gitlab/) | Merge request activity and bot mentions | The merge request thread | +| [Linear](/factories/integrations/linear/) | Planned issues | The Linear issue and its agent session | +| [Jira](/factories/integrations/jira/) | Work items assigned to Warp | The Jira agent session | +| [Factory MCP](/factories/factory-mcp/) | Exchanging work with a local coding agent, in both directions | The factory work item | +| Direct runs and schedules | One-off or recurring work | The factory work item | + +## Connect a source + +1. Pick the factory you want to connect. If you don't have one yet, follow the [Warp Factories quickstart](/factories/quickstart/). +2. Connect the source: install the provider integration, set up the [Factory MCP](/factories/factory-mcp/), or create a schedule. Each integration guide below walks through authorization; grant only the access the factory needs. +3. Tell the factory how to respond. Provider connections come with default automations that decide which events start work and which agent handles them; review their [filters](/factories/automation-filters/) and run settings. Schedules and direct runs skip this step. +4. Send a test request, such as mentioning the factory in Slack or assigning it an issue, and confirm it picks up the work and replies at the source. + +## How work reaches your factory + +```mermaid +flowchart LR + Event["Event from a
connected tool"] --> Automation["Matching
automation"] + Schedule["Schedule"] --> Automation + Automation --> Foreman["Foreman agent"] + Direct["Direct request"] --> Foreman + Foreman --> Work["Work item"] + Work --> Results["Results posted
back to the source"] +``` + +An event from a connected tool starts the automation whose filters match it, such as a specific repository, channel, or label. Schedules start their automation on a timer, and direct requests go straight to the factory. + +Every request then lands with the foreman agent, the factory's orchestrator. The foreman turns the request into a work item, determines which stage the work needs next, and dispatches a specialized agent for each stage: triage to scope the request, spec when the design needs agreement, implementation to write the code, and review to check it. Between stages it relays questions and progress back to the source, and it pauses wherever a decision belongs to a human, such as approving a spec or merging a pull request. See [how Warp Factories work](/factories/how-factories-work/) for the full lifecycle. + +## Review the default automations + +When you create a factory through the setup wizard, Warp adds default automations for each tool you connect, so common requests work immediately: + +* **GitHub** - Starts work when the factory is mentioned or assigned, and follows up when pull requests close or merge, completing a linked tracker issue when it can. See the [GitHub integration guide](/factories/integrations/github/). +* **GitLab** - Starts work when someone mentions the factory's bot in a merge request comment. See the [GitLab integration guide](/factories/integrations/gitlab/). +* **Jira** - Starts work when someone assigns or mentions Warp on a work item in one of the Jira projects you selected. See the [Jira integration guide](/factories/integrations/jira/). +* **Linear** - Starts work when a new agent session arrives from one of the Linear teams you selected. See the [Linear integration guide](/factories/integrations/linear/). +* **Slack** - Starts work from mentions and messages, as described in the [Slack integration guide](/factories/integrations/slack/). + +These defaults are starting points. Review each automation's filters, agent, and run settings, and adjust them to match your workflow. + +## Integration guides + +* [Slack](/factories/integrations/slack/) - Route chat requests, direct messages, and thread follow-ups through a dedicated factory app. +* [GitHub](/factories/integrations/github/) - Route repository events with issue, pull request, review, or CI context. +* [GitLab](/factories/integrations/gitlab/) - Route merge request events and bot mentions through a per-factory service account. +* [Linear](/factories/integrations/linear/) - Route planned issues through issue activity and agent sessions. +* [Jira](/factories/integrations/jira/) - Route Jira work items assigned to Warp into factory work. + +## Factory MCP + +The Factory MCP connects local coding agents and other MCP clients to your factory, and it works in both directions: send work to the factory, or take work over from it — pull a task down to your machine, iterate on it locally, and hand it back to the same work item. See the [Factory MCP guide](/factories/factory-mcp/). + +## Direct runs and schedules + +Not every task starts in an external tool: + +* Start a direct factory run for one-off work: describe the task and the foreman agent takes it from there. +* Create a scheduled automation for recurring work such as maintenance or reports. + +See the [triggers overview](/platform/triggers/) for how schedules and other triggers work across the platform. + +## Good to know + +* **Follow-ups continue the same work item** - Replying in the same Slack thread, GitHub issue or pull request, Linear issue, or Jira agent session adds to the existing work item instead of starting a new one. Repeated event deliveries from a provider don't create duplicate work either. +* **One issue tracker per factory** - A factory can use [Linear](/factories/integrations/linear/) or [Jira](/factories/integrations/jira/), or no tracker at all, but not both at once. The setup wizard currently offers Linear; to use Jira, connect it after setup or in your [factory definition](/factories/factory-as-code/). +* **Filters route work; they don't restrict access** - Choosing which requests start work is separate from what a running agent can reach. See [automation filters](/factories/automation-filters/#filters-route-work-they-dont-restrict-access). +* **The factory hands off at the pull request** - It pushes branches and opens pull requests, then waits for a person. See [where your team stays in charge](/factories/how-factories-work/#where-your-team-stays-in-charge). + +Next, customize which agents receive work and how it's routed with [factory definitions as code](/factories/factory-as-code/). diff --git a/src/content/docs/factories/factory-agents.mdx b/src/content/docs/factories/factory-agents.mdx new file mode 100644 index 000000000..2a9a00f4e --- /dev/null +++ b/src/content/docs/factories/factory-agents.mdx @@ -0,0 +1,105 @@ +--- +title: Factory agents +description: >- + Every factory has a team of default agents: a foreman that coordinates the + work, plus triage, spec, implement, and review agents. +sidebar: + label: "Factory agents" +--- + +Every factory has a **foreman**, the one agent you talk to from whichever tool a request starts in. Around it sit four default agents, one for each part of the software development lifecycle: triage scopes the request, spec writes the plan, implement writes the code, and review checks it. Together they take a work item from the moment it reaches your factory to a pull request ready for a person to review. + +## The default agents + +Every factory gets a foreman, and you choose one to four of the others to go with it. These defaults are a starting point — you can [add custom agents and automations](#add-custom-agents-and-automations) for work they don't cover. + +| Agent | What it does | What it produces | +| --- | --- | --- | +| Foreman | Coordinates the work and talks to the requester | Decisions, questions, status updates, and the final handoff | +| Triage | Investigates the request and establishes scope | Evidence, issue context, complexity, and open questions | +| Spec | Turns requirements into a concrete plan with validation criteria | Product and technical specs in a draft pull request | +| Implement | Makes and validates the code change | Code, tests, validation results, and visual evidence | +| Review | Checks the finished change with fresh eyes | Findings and a recommendation | + +These are responsibilities, not a fixed pipeline. A small, well-understood change can skip the spec stage entirely, and review can send work back to implementation for another pass. By default, work that goes through the spec stage needs a human to approve the spec before implementation starts. + +For the complete lifecycle, see [how Warp Factories work](/factories/how-factories-work/). + +## Foreman + +The **foreman agent** runs the factory floor. It decides which agent a work item needs next, hands the work over, and keeps the requester informed. It's the only default agent that talks to the requester directly: when another agent needs a human answer, the foreman asks the question and routes the answer back. For revisions and follow-ups, the foreman goes back to the same agent and continues its existing conversation instead of starting a new one, so no context is lost. + +When the work is done, the foreman presents the final pull request and its supporting evidence, then marks the work item complete. Complete means the work was handed to a human, not that the change was merged or deployed. Merging stays with your team. + +## Triage, spec, implement, and review + +### Triage + +Triage researches the codebase and related issues first, and reproduces a problem only when research can't establish the cause. Its report — context, scope, complexity, open questions — is what the foreman uses to decide whether to ask the requester for clarification, request a spec, or go straight to implementation. + +### Spec + +Spec works through the foreman to pin down requirements, then writes product and technical specifications in a draft pull request with criteria for validating the change. The implement agent later continues that pull request. By default, the foreman waits for a person to approve the spec before implementation starts; change that in the foreman's instructions. + +### Implement + +Implement continues the spec's branch and draft pull request rather than starting over. It adds tests, runs the repository's validation, and, when [computer use](/agents/capabilities/computer-use/) is available, captures visual evidence of user-facing changes. If review finds problems, implement revises. It never merges. + +### Review + +Review comes to the change with fresh eyes, hunting for unmet requirements, broken conventions, missing or failing tests, security issues, and evidence that doesn't hold up. It reruns or extends validation where the evidence is thin, then recommends one of three things to the foreman: accept, revise, or ask a person to decide. The recommendation is advice — review doesn't approve or merge the pull request. + +## Built-in skills + +Every default agent comes with GitHub skills, and the foreman also comes with a Slack skill. The issue tracker you choose during setup adds to that baseline: choosing Linear or Jira gives the agents that tracker's skill and instructions for working with it. If you don't choose a tracker, the agents get only the baseline. + +## Configure agent behavior + +Use the agent editor in the [factory dashboard](/factories/factory-dashboard/) to change an agent's description, model, runner, host, MCP servers, secrets, and instructions. + +You can also manage the whole factory as version-controlled code, with [factory definition files](/factories/factory-as-code/) in a Git repository, where changes get the same review, history, and rollback as any other code. A few agent settings can only be set in the files, such as harness and credential strategy. Where the repository lives determines how the two editing paths work together: + +* **Warp-managed repository** - Edit agents in the agent editor, or edit the definition files directly in the factory dashboard's **Factory definition** tab, whichever fits the change. Both write to the same files, so the editor and the code always agree. +* **A GitHub repository your team owns** - The files are the only way to change the factory. Edits go through pull requests, and the file-owned settings in the factory dashboard are read-only. + +Factory setup doesn't choose models for you. To change the model an agent uses, edit that agent. + +## Choose models and harnesses per agent + +Each agent can run on its own model and harness. Supported harnesses include the Warp Agent harness, Claude Code, and Codex, and any agent can use any of them. A foreman running on Claude Code or Codex can still dispatch the factory's other agents, and the runs it starts are still tracked as its children. + +:::note +Third-party harnesses require a Build plan or higher; on the Free plan every agent runs on the Warp Agent harness. See [harnesses](/platform/harnesses/#plan-requirements). +::: + +Default model IDs change over time, so choose based on what each agent has to do well: + +| Agent | What to optimize for | +| --- | --- | +| Foreman | Orchestration, instruction following, and long-running conversations | +| Triage | Research, evidence gathering, and working with connected tools | +| Spec | Synthesizing requirements, technical reasoning, and precise writing | +| Implement | Coding strength, with a harness that fits your repositories and toolchain | +| Review | A different model or harness from the implement agent, so the two don't share blind spots | + +See [model choice for agents](/agents/inference/model-choice/) and [harnesses for cloud agents](/platform/harnesses/) for available options. Define reusable procedures with [skills](/agents/capabilities/skills/), and scope each agent's external access through [MCP servers](/platform/mcp/) and [cloud agent secrets](/platform/secrets/). + +## Add custom agents and automations + +Add custom agents for jobs the default agents don't handle, such as documentation, security analysis, migrations, or release checks. A custom agent doesn't have to be a required step for every work item. + +Automations start a chosen agent on a schedule or when an event fires. They're one more way for work to enter your factory; the foreman still coordinates whatever they start. For all the ways to route work into a factory, see [connect your factory](/factories/connect-your-factory/). + +## Human decision points and permissions + +| Decision | Default behavior | What enforces it | +| --- | --- | --- | +| Spec approval | The foreman asks a human to clarify ambiguity and approve every spec | Workflow policy in the foreman's instructions, which your team can change | +| Merging | Agents never merge; the foreman hands the finished pull request to a human | Your repository's permissions decide who can approve and merge | +| Runtime access | Each agent reaches only the repositories, secrets, and MCP servers in its configuration | Platform configuration and the permissions of the connected providers | + +The first two rows are conventions: they live in the foreman's instructions and your repository settings, and your team can change them. Access is different. What an agent can reach comes from its configuration and the permissions of the connected providers, never from its instructions — changing what an agent is told to do doesn't change what it's able to do. + +So enforce with the real controls: branch protection and repository permissions decide who merges, and each agent's configuration decides what it can reach. + +Next, capture these choices in [factory definitions as code](/factories/factory-as-code/). diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx new file mode 100644 index 000000000..aad227ac0 --- /dev/null +++ b/src/content/docs/factories/factory-as-code.mdx @@ -0,0 +1,396 @@ +--- +title: Factory definition syntax +description: >- + Look up every file and key in a factory definition: factory.yaml, agents, + automations, runners, and skills. +sidebar: + label: "Definitions as code" +--- +import { VARS } from '@data/vars'; + +Every factory is defined by files: a `factory.yaml` plus directories of agents, automations, and runners, versioned in a Git repository. The files are the source of truth — when they change, Warp updates the factory to match. This page describes every file and key in a definition. + +Definition files are YAML and Markdown. Keys are case-sensitive. + +## Where the definition lives + +You choose who hosts the definition repository when you create a factory: + +* **Warp-managed (default)** - Warp hosts the repository for you. You edit the factory in the [{VARS.FACTORY_WEB_APP}](/factories/factory-dashboard/), and every change is validated, committed to the files, and applied in one step. You never interact with the repository directly, and the definition can't end up in an invalid state. +* **GitHub** - The definition lives in a repository you own. The repository is the only way to change the factory: the web app shows the configuration read-only and links back to the files. Open a pull request, and any change merged to the production branch (`main` by default) updates the factory. See [Pull request checks](#pull-request-checks-for-github-backed-factories). + +Both modes use the same files, so everything on this page applies to either. You can also link a GitHub repository to a Warp-managed factory later. + +Definition files describe how the factory is configured, not what it is doing: work items, runs, and metrics live in the web app and are never written to the files. + +## Directory structure + +Each resource takes its name from its path: `agents/reviewer/agent.md` defines an agent named `reviewer`. + +```text +factory.yaml +agents/ + foreman/ + agent.md + skills/ + incident-triage/ + SKILL.md + reviewer/ + agent.md +automations/ + labeled-issue/ + automation.md +runners/ + linux-build.yaml +skills/ + repository-conventions/ + SKILL.md +``` + +Only `factory.yaml` and at least one agent are required. For a complete working definition, see the [example factory definition](#example-factory-definition) below. + +## `factory.yaml` + +The factory's root document. It names the factory, scopes it to repositories, and sets the execution defaults every agent inherits. + +```yaml title="factory.yaml" +schemaVersion: v1alpha1 +name: payments-factory +repositories: + - owner: acme + name: payments-service +agentDefaults: + model: auto +``` + +### `schemaVersion` + +Required. The definition schema version. The only supported value is `v1alpha1`. + +### `name` + +Required. The factory's name. + +### `description` + +Optional. What the factory is for. + +### `alias` + +Optional. The handle used to @-mention the factory's foreman on connected platforms like Slack and Linear; the factory dashboard labels this field **Foreman name**. Up to 60 characters: letters, numbers, spaces, `.`, `_`, and `-`. Must be unique across your workspace (compared case-insensitively). + +### `credentialStrategy` + +Optional. Whose credentials the factory's runs execute with: `EXECUTOR` (the principal executing the run, the default) or `CREATOR` (the user who created the run). Agents can override it per role. + +### `repositories` + +Required. The repositories the factory works in, as `owner` and `name` pairs. On a GitLab-backed factory these are the projects you selected under the connected group. + +```yaml +repositories: + - owner: acme + name: payments-service + - owner: acme + name: payments-docs +``` + +### `secrets` + +Optional. Names of [managed secrets](/platform/secrets/) granted to every agent in the factory, in addition to anything individual agents declare. + +### `mcpServers` + +Optional. [MCP servers](/platform/mcp/) granted to every agent, keyed by the name the agent sees. Each entry references a Warp-managed MCP server by `warpId`. + +```yaml +mcpServers: + sentry: + warpId: SENTRY_MCP_SERVER_ID +``` + +### `cloudProviders` + +Optional. Cloud-provider identity federation for agent runs. `gcp` accepts `projectNumber` (quote it so YAML keeps it a string), `workloadIdentityFederationPoolId`, `workloadIdentityFederationProviderId`, and an optional `serviceAccountEmail`. `aws` accepts `roleArn`. + +```yaml +cloudProviders: + aws: + roleArn: arn:aws:iam::123456789012:role/warp-factory +``` + +### `integrations` + +Optional. The integration providers attached to the factory. `type` accepts `slack`, `linear`, or `jira`. Declare at most one issue tracker: `linear` and `jira` are mutually exclusive, and omitting a tracker is also valid. GitHub is not declared here; repository access comes from `repositories` and the connected GitHub App. + +```yaml +integrations: + - type: slack + - type: linear +``` + +### `agentDefaults` + +Required. The execution defaults every agent inherits. Declare exactly one of `model` or `harness`; the other keys are optional. An agent that sets one of these keys for itself overrides the default. + +```yaml +agentDefaults: + model: auto + runner: linux-build + environmentId: PAYMENTS_ENVIRONMENT_ID +``` + +### `agentDefaults.model` + +The model that runs execute with, as a `model_id` from [model choice for agents](/agents/inference/model-choice/). `model` is shorthand for running on the Warp Agent harness: + +```yaml +model: auto +``` + +is equivalent to: + +```yaml +harness: + type: oz + model: auto +``` + +`model` and `harness` are mutually exclusive everywhere they appear. + +### `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` (alias `claude-code`), `codex`, or `gemini` — the values the definition schema validates. For what each harness does and which ones your team can run, see [supported harnesses](/platform/harnesses/). + +```yaml +harness: + type: codex + model: gpt-5.3-codex + reasoningLevel: high + auth: + source: managedSecret + secretName: CODEX_API_KEY +``` + +For a third-party harness, `auth` sets where credentials come from: `source: managedSecret` reads the [managed secret](/platform/secrets/) named by `secretName`, and `source: workerEnvironment` reads them from your self-hosted worker's environment (and requires a self-hosted `workerHost`). The `oz` harness supplies its own credentials and takes no `auth` or `reasoningLevel`. + +### `agentDefaults.runner` + +The name of a runner defined under [`runners/`](#runnersnameyaml) that provides the compute for runs. + +### `agentDefaults.environmentId` + +The ID of an existing [environment](/platform/environments/) that runs execute in. Most factories never set this: leave it out, and Warp manages the workspace from the factory's repositories. + +### `agentDefaults.secrets` + +Managed secrets for agents that don't declare their own. An agent that declares `secrets` replaces this list rather than adding to it; factory-wide [`secrets`](#secrets) always apply. + +### `agentDefaults.mcpServers` + +MCP servers for agents that don't declare their own, in the same form as [`mcpServers`](#mcpservers). Like secrets, an agent that declares its own map replaces this one, and factory-wide servers always apply. + +### `agentDefaults.workerHost` + +Where runs execute: `warp` for Warp-hosted compute, or the ID of a connected [self-hosted worker](/platform/self-hosting/). + +## `agents//agent.md` + +One file per agent. The YAML frontmatter configures how the agent runs, and the Markdown body is the agent's prompt: the durable instructions for its role. The agent's name comes from its directory. + +```markdown title="agents/reviewer/agent.md" +--- +description: Reviews factory-produced pull requests +agentType: REVIEW +--- + +Review each pull request against the repository's standards. Request +changes when tests are missing; never approve your own edits. +``` + +The frontmatter accepts: + +* `description` - Optional. What the agent does. +* [`agentType`](#agenttype) - Optional. The agent's role. +* `credentialStrategy` - Optional. Overrides the factory-level [`credentialStrategy`](#credentialstrategy) for this agent's runs. +* `model` or `harness`, `runner`, `environmentId`, `secrets`, `mcpServers`, `workerHost` - Optional. The same keys as [`agentDefaults`](#agentdefaults); a key declared here overrides the default for this agent. + +### `agentType` + +The agent's role: `CUSTOM` (the default), `FOREMAN` (alias `MAIN`), `TRIAGE`, `SPEC`, `IMPLEMENT`, `REVIEW`, or `VERIFY`. Every definition declares exactly one foreman — the factory's entry point and the default target for automations. See [factory agents](/factories/factory-agents/) for what each role does. + +## `automations//automation.md` + +One file per automation. The frontmatter declares when runs start and how they execute, and the Markdown body is the prompt each run starts with. The automation's name comes from its directory. + +```markdown title="automations/labeled-issue/automation.md" +--- +agent: foreman +triggers: + - provider: github + event: issue_labeled + filter: + repos: [acme/payments-service] + labels: [factory-ready] +--- + +Review the labeled issue and decide the next required stage. Return +unresolved product questions to a human. +``` + +### `enabled` + +Optional. Turns the automation on or off. Defaults to `true`. + +### `agent` + +Optional. The name of the agent that handles this automation's runs. Defaults to the foreman. + +### `triggers` + +Required. One or more events that start runs. Each trigger declares a `provider` and an `event`, an optional `filter`, and, for schedules, a `schedule`. + +The providers and their events: + +* `github` - `issue_created`, `issue_labeled`, `issue_assigned`, `issue_mentioned`, `pull_request_opened`, `pull_request_closed`, `pull_request_merged`, `pull_request_labeled`, `pull_request_assigned`, `pull_request_mentioned`, `pull_request_ready`, `pull_request_reopened`, `pull_request_synchronized`, `pull_request_review_requested`, `pull_request_review_submitted`, `push`, `check_suite_completed`, `check_run_rerequested`, `check_suite_rerequested`, `workflow_run_completed` +* `gitlab` - `merge_request`, `bot_mentioned` +* `linear` - `issue_created`, `issue_labeled`, `issue_assigned`, `issue_state_changed`, `comment_created`, `agent_session_created` +* `jira` - `issue_created`, `issue_labeled`, `status_changed`, `agent_session_created` +* `slack` - `app_mention`, `message_posted`, `message_dm`, `message_im`, `message_mpim`, `member_joined_channel`, `reaction_added` +* `schedule` - `cron_fired` +* `factory` - `work_item_stage_changed` + +Slack, Linear, and Jira triggers require the matching [integration](/platform/integrations/) to be connected. GitHub triggers work through the factory's `repositories`, and GitLab triggers through the group connected to your workspace — see the [GitLab integration](/factories/integrations/gitlab/). + +### `triggers[].filter` + +Optional. Narrows which events start runs. The keys a filter accepts depend on the provider and event: for example `repos`, `labels`, and `authors` for GitHub events, or `channels`, `users`, and `keywords` for Slack messages. Filter keys combine with AND, an omitted key matches everything, and each key takes a list that matches any of its values (or an `in`/`not_in` object to include or exclude). Slack and Linear filters take names (channels, users, teams, projects, states), and Warp resolves them to IDs when it applies the change. + +### `triggers[].schedule` + +Declares a cron schedule inline on a `schedule` / `cron_fired` trigger: a five-field cron expression or a descriptor like `@daily` or `@every 1h`, always interpreted in UTC. An optional `name` distinguishes multiple schedules on one automation. + +```yaml +triggers: + - provider: schedule + event: cron_fired + schedule: + name: weekday-mornings + cron: "0 9 * * 1-5" +``` + +### Execution overrides + +An automation may also declare `model` or `harness`, `runner`, `environmentId`, `secrets`, `mcpServers`, and `workerHost` (the same keys as [`agentDefaults`](#agentdefaults)) to override the target agent's settings for the runs it starts. + +## `runners/.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. + +```yaml title="runners/linux-build.yaml" +description: Linux runner for payments builds and tests +setupCommands: + - corepack enable +instanceShape: + vcpus: 4 + memoryGb: 8 +platform: + os: linux + arch: x86_64 + linux: + dockerImage: ubuntu:22.04 +``` + +### `setupCommands` + +Optional. Shell commands run in order while the sandbox is prepared. + +### `instanceShape` + +Optional. The compute size, as `vcpus` and `memoryGb`. Omit it to take the workspace default. + +### `platform` + +The operating system and architecture. `os` is `linux` (the default) or `macos`, and `arch` is `x86_64` (the default on Linux) or `aarch64` (the only option on macOS). Linux runners require `linux.dockerImage`, the container image the sandbox boots, so every Linux runner declares a `platform` section. macOS runners accept an optional `mac.version` (`"14"`, `"15"`, `"26"`, or `"27"`; quote it, and it defaults to `"26"`). + +## Skills + +A skill is a directory containing a `SKILL.md`, not a YAML key. Skills under `skills/` are available to every agent in the factory; skills under `agents//skills/` are available only to that agent. See [Skills for agents](/agents/capabilities/skills/). + +## Example factory definition + +A complete, working definition: one repository, a foreman, an automation triggered by a GitHub label, and a Linux runner. `PAYMENTS_ENVIRONMENT_ID` and `SENTRY_MCP_SERVER_ID` stand in for the IDs of an existing environment and MCP server. + +```yaml title="factory.yaml" +schemaVersion: v1alpha1 +name: payments-factory +description: Processes approved work for the payments service +alias: payments +repositories: + - owner: acme + name: payments-service +agentDefaults: + model: auto + runner: linux-build + environmentId: PAYMENTS_ENVIRONMENT_ID +``` + +```markdown title="agents/foreman/agent.md" +--- +description: Routes approved payments work through the factory +agentType: FOREMAN +secrets: + - SENTRY_AUTH_TOKEN +mcpServers: + sentry: + warpId: SENTRY_MCP_SERVER_ID +--- + +Own each work item from intake through human handoff. + +Confirm the request is ready before dispatching implementation. Require +repository validation and independent review before marking work complete. +``` + +```markdown title="automations/labeled-issue/automation.md" +--- +enabled: true +agent: foreman +triggers: + - provider: github + event: issue_labeled + filter: + repos: [acme/payments-service] + labels: [factory-ready] +--- + +Review the labeled issue and decide the next required stage. Preserve the +issue's acceptance criteria and return unresolved product questions to a human. +``` + +```yaml title="runners/linux-build.yaml" +description: Linux runner for payments builds and tests +setupCommands: + - corepack enable +instanceShape: + vcpus: 4 + memoryGb: 8 +platform: + os: linux + arch: x86_64 + linux: + dockerImage: ubuntu:22.04 +``` + +## Pull request checks for GitHub-backed factories + +When your definition lives in GitHub, Warp validates every change before it takes effect: + +* Every pull request that targets the production branch gets a **warp/factory-config** check. The check annotates invalid fields and unresolvable references with the file and line that caused them, and summarizes what the change would apply. +* When a change lands on the production branch, Warp applies it as a whole. A definition that fails validation never partially applies: the factory keeps running on its last valid definition until the branch is fixed. + +Warp-managed factories skip all of this. Every edit in the web app is validated when you save it, so the definition can't become invalid. + +## Machine-readable schema + +Warp publishes the definition schema as JSON Schema documents, generated from the same parser that validates your files. Fetch the supported versions from `https://app.warp.dev/api/v1/factory-files/schemas` and the `v1alpha1` documents from `https://app.warp.dev/api/v1/factory-files/schemas/v1alpha1`. Both endpoints are unauthenticated, so editors and agents can validate a definition without a Warp login. diff --git a/src/content/docs/factories/factory-dashboard.mdx b/src/content/docs/factories/factory-dashboard.mdx new file mode 100644 index 000000000..0579e7d5d --- /dev/null +++ b/src/content/docs/factories/factory-dashboard.mdx @@ -0,0 +1,109 @@ +--- +title: Factory dashboard +description: >- + Track work items, inspect runs, read factory metrics, and manage agents, + automations, and settings from the factory dashboard. +sidebar: + label: "Factory dashboard" +--- + +The factory dashboard is the web app for operating a single factory. Use it to track the work your agents are doing, inspect the runs and pull requests they produce, and manage the agents, automations, and settings the factory owns. + +:::note +"Factory dashboard" names the whole surface. **Dashboard**, in bold, is one page inside it: the metrics page you land on when you open a factory. +::: + +## Pages at a glance + +Select a factory in the sidebar to open its pages. **Runs**, **MCPs and apps**, **Secrets**, and **Integrations** sit above the factory list and cover your whole team, not a single factory. + +| Page | What it shows | What you do there | +| --- | --- | --- | +| **Dashboard** | The factory's metrics: autonomy, PR cycle time, cost, and run volume | Compare periods and find work worth investigating | +| **Activity** | Work items grouped by stage | Search, filter, open, and stop work items | +| **Agents** | The factory's agents | Create and edit agents | +| **Automations** | Triggers that start runs | Create, edit, and delete automations | +| **Runs** | The factory's individual agent runs | Start, stop, and score runs | +| **Scorers** | Scorer definitions and results | Define rubrics and review classifications | +| **Self-improvement** | Pull requests filed to fix Scorer-detected failures | Review fix PRs and open the runs behind them | +| **Benchmarks** | Benchmark suites and their runs | Compare harness, model, and runner configurations | +| **Factory definition** | The factory's definition files | Browse and edit a Warp-managed definition | +| **Settings** | Configuration the factory owns | Change identity, repos, runners, and the integrations the factory can access | + +A factory opens on its **Dashboard** page. **Factory definition** appears only on Warp-managed factories, since a factory whose definition lives in your own repository is edited there instead. + +## Track work items on Activity + +**Activity** shows the factory's work items grouped by stage: Triage, Planning, Building, and Reviewing. Finished work items move to two terminal stages, Complete and Cancelled. + +By default, Activity shows only work items you created, and only the four active stages. Change the **Created by** filter to see a teammate's work, and add a **Stage** filter for **Complete** or **Cancelled** to see finished work. + +Click a work item to open its detail pane, which includes the prompt that started it, the ticket or thread it came from, the pull requests it produced, and its cost. **View agent** opens the agent's session, **Event history** lists the runs behind the work item, and **Stop task** cancels the current run. + +:::caution +**Stop task** takes effect immediately, with no confirmation prompt. +::: + +## Inspect runs + +A run is a single agent execution. A work item on **Activity** tracks one piece of work through the factory's stages and can span several runs as different agents pick it up. The team-level **Runs** page lists every run you have access to; a factory's **Runs** page lists only runs from that factory's agents. + +Click **New** on a factory's **Runs** page to send a prompt to the factory's foreman agent. Open a run to see its timeline and cost, plus a **Sub-agents** tab for an orchestrator run's child runs. From there you can view the agent's full session, stop or score the run, or turn it into a benchmark task. + +:::note +Run pages don't include a chat input, but you can still steer a run: **View session** opens its [shared agent session](/platform/viewing-cloud-agent-runs/), where you follow the agent in real time and send follow-up instructions while the run's sandbox is active. After it shuts down, the same button opens the conversation transcript. +::: + +## Read metrics on the Dashboard page + +**Dashboard** is the factory's landing page. It summarizes the factory over a date range you choose: + +* **Autonomy** - The share of the factory's merged PRs that needed no human input beyond an approving review and the merge itself. +* **PR cycle time** - The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with a median for each stage. +* **Cost per PR** - The median cost of PRs opened in the range. Treat it as a lower-bound estimate: it can miss some run usage and does not match billing. See [Measure and improve a factory](/factories/measure-and-improve/) for its limitations. + +The page also charts opened versus merged PRs and a breakdown of runs, and the **Cost per PR** card expands to list the most expensive PRs in the range. When Scorers are set up, Scorer cards summarize recent classification results. + +## Manage agents and automations + +**Agents** lists the factory's agents. Create agents and edit their instructions, model or harness, runner, host, secrets, and MCP servers. **Automations** defines the triggers that start runs: a schedule (including custom cron expressions) or a GitHub, Linear, Slack, or Jira event. + +The automation editor doesn't change execution settings; an automation only overrides them through [execution overrides in the definition files](/factories/factory-as-code/#execution-overrides). When the factory's definition lives in an external repository, Agents, Automations, and Scorers are read-only; make changes there through pull requests. + +## Edit definitions in the Factory definition tab + +**Factory definition** is the factory dashboard's view of the definition files that [definitions as code](/factories/factory-as-code/) describes in full. Where the definition lives decides what you get: + +* **Warp-managed** - Browse and edit the definition files. Saving validates the definition and commits all changes together. +* **Managed in GitHub** - The tab doesn't appear. Edit the definition through pull requests in your repository, and **Settings** links back to it. +* **Live-managed** - The factory is managed through the API, so there are no definition files to browse. + +When an agent proposes a change to a Warp-managed definition, its work item on **Activity** links to a review of the branch inside the factory dashboard. From there, comment on the diff, use **Request changes** to send feedback back to the agent, or **Approve & merge**. + +## Score and benchmark + +A Scorer is an LLM judge that classifies completed runs against a rubric you define, scoped to the agents you choose and sampled at a rate you set. Each Scorer has a **Self-improvement** toggle: when it's on, the factory periodically triages the runs that Scorer marks as failing and files fixes for recurring issues. The **Self-improvement** page tracks the pull requests those fixes open, linking each one to the run that produced it. + +**Benchmarks** compares harness, model, and runner configurations against a fixed set of tasks with success criteria. Benchmark results are only as reliable as the Scorers behind them, so read them alongside [Measure and improve a factory](/factories/measure-and-improve/). + +## Change factory settings + +**Settings** holds the configuration the factory owns: + +* **Identity** - The factory's name, avatar, and [**Foreman name**](/factories/factory-as-code/#alias), the handle your team @-mentions. +* **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/#configure-and-review-self-improvement) uses to analyze failed runs. +* **Runners** - The compute the factory's runs execute on. +* **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 + +* [How Warp Factories work](/factories/how-factories-work/) - The lifecycle behind Activity's stages and where humans stay in the loop. +* [Definitions as code](/factories/factory-as-code/) - Define agents, automations, runners, and source ownership in code. +* [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure it. +* [Measure and improve a factory](/factories/measure-and-improve/) - Configure the Scorers and benchmarks behind the **Dashboard** page. +* [Troubleshooting Warp Factories](/factories/troubleshooting/) - Fixes for setup problems, work that doesn't start, and stuck runs. diff --git a/src/content/docs/factories/factory-mcp.mdx b/src/content/docs/factories/factory-mcp.mdx new file mode 100644 index 000000000..f16cc3766 --- /dev/null +++ b/src/content/docs/factories/factory-mcp.mdx @@ -0,0 +1,130 @@ +--- +title: Factory MCP +description: >- + Connect any coding agent to your team's factories to send in work, continue + tasks locally, and hand results back. +sidebar: + label: "Factory MCP" +--- + +Factory MCP is a hosted Model Context Protocol (MCP) server that connects coding agents to your team's factories, in both directions: the agent you already work with — in Warp or in any MCP-capable tool — can send work to a factory, or take work over from one by pulling a task down, continuing it locally, and handing the result back. + +The factory keeps a single record of each task throughout. Whether a change happens in the cloud or on your machine, it lands on the same task with the same history and conversation. A task is the factory's work item: the same unit of work that appears in the factory dashboard's [Activity view](/factories/factory-dashboard/#track-work-items-on-activity). + +## What you can use it for + +* **Send work in** - Turn anything from your local session into a factory task: a bug you found, review feedback, or a half-finished change. +* **Continue a task locally** - Pull a task's context into your own checkout, work with your own tools, and return the result to the same task. +* **Stay in sync** - List and search tasks, read a task's conversation, and message its [foreman](/factories/factory-agents/), the agent that orchestrates each task inside the factory. +* **Create a factory** - Set up a new factory when you know the team, repositories, and source-control details. + +Factory MCP is one of several ways work enters a factory, alongside Slack, GitHub, GitLab, Linear, and Jira. See [connect your factory](/factories/connect-your-factory/) for all intake paths and [how Warp Factories work](/factories/how-factories-work/) for how tasks move through a factory. + +## Connect and authenticate + +### In Warp + +There is nothing to configure. When your account has access, Warp connects agent sessions to Factory MCP and handles authentication for you. + +### In other MCP clients + +Factory MCP is a streamable HTTP server at `https://app.warp.dev/api/v1/mcp/factory`. Point any MCP client that supports remote servers at that URL; on first connect, the client opens a browser so you can sign in and approve access. + +With Claude Code: + +```bash +claude mcp add --transport http warp-factory https://app.warp.dev/api/v1/mcp/factory +``` + +In clients that use the `mcpServers` JSON format, such as Cursor: + +```json +{ + "mcpServers": { + "warp-factory": { + "url": "https://app.warp.dev/api/v1/mcp/factory" + } + } +} +``` + +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. + +For unattended automation, skip the browser flow and authenticate with a [Warp API key](/reference/cli/api-keys/) instead. Create the key for a least-privilege cloud agent rather than your personal account, and pass it as a bearer token: + +```json +{ + "mcpServers": { + "warp-factory": { + "url": "https://app.warp.dev/api/v1/mcp/factory", + "headers": { + "Authorization": "Bearer YOUR_API_KEY" + } + } + } +} +``` + +:::caution +Factory MCP has no read-only or per-factory scopes: a connected client acts with the full permissions of the account or agent it authenticates as. Store API keys in your client's secret storage, never in a repository. +::: + +## How it works + +Factory MCP exposes a small set of tools that your agent calls on your behalf. You don't need to learn them to use it: the server publishes its own usage guidance and tool schemas, so agents pick up the correct workflow on their own. Prompts like these are enough: + +* "Send this bug to the factory, including my branch." +* "What's the status of the checkout-flow task?" +* "Pull down ENG-123 so we can finish it here." + +The rest of this page describes what happens behind those prompts. + +## Send new work to a factory + +To create a task, your agent calls `send_task` with the target factory, a title, and a note. The note is what the foreman starts from, so a good one states the goal, the relevant context and constraints, and any work already done. The foreman takes it from there and reports progress on the task's conversation. + +If the new task builds on local changes, push the branch or open a pull request first and reference it in the note, so the factory can see that work. + +## Pick up a task and work on it locally + +1. **Find the task.** Your agent locates it with `list_tasks` or `search_task`, or resolves a reference you give it with `get_task`: a task or run URL, a GitHub pull request, a Slack permalink, a Linear or Jira issue, or a branch name. +2. **Pull down the context.** Calling `get_task` with `start_working=true` returns the task's status, run history, and suggested Git commands for setting up an isolated [worktree](/code/git-worktrees/) in a local clone. Factory MCP never modifies your files; your agent runs the setup itself. +3. **Coordinate while you work.** `message_foreman` sends progress, questions, and blockers to the task's foreman, and `get_conversation` reads the replies. Messaging keeps the factory informed but doesn't move the task or hand anything back. +4. **Commit and push.** Validate the change, then push the branch. The factory can't see uncommitted or unpushed work. +5. **Hand the task back.** Your agent calls `send_task` with the task's ID, the pushed branch or pull request URL, and a note covering what changed, what was validated, and what remains. The work returns to the same task, and the foreman decides the next step. + +:::caution +Picking up a task doesn't claim, lock, or pause it, and the factory may keep running its own work on it in the meantime. Check the task's active runs and tell the foreman you're picking it up, so you don't end up with duplicate changes. +::: + +When nothing remains for the factory to do, `complete_task` closes the task out. Handing work back doesn't complete a task by itself. + +## Get notified when a task needs you + +Sending work to a factory means you're no longer watching it. To be notified when a task needs attention or finishes, ask for a notification when sending or returning work: your agent calls `list_notification_routes` to see the destinations available to you in that factory, such as a Slack DM or a Linear issue, and passes your choice to `send_task`. Delivery is best-effort, so treat notifications as a convenience rather than a guarantee. + +## Tool reference + +Your MCP client fetches the full input schemas from the server, and tool results include links that open the corresponding task or run in the factory's [factory dashboard](/factories/factory-dashboard/). + +| Tool | What it does | +| --- | --- | +| `list_factories` | Lists the factories you can access. | +| `create_factory` | Creates a factory for a team, with its repositories and source-control details. | +| `list_tasks` | Lists the tasks in one factory, with filters such as creator, stage, and date. | +| `search_task` | Searches task titles across all factories you can access. | +| `get_task` | Reads a task's status, run history, and outputs. Accepts a task ID or a reference such as a URL, issue, pull request, or branch. With `start_working=true`, also returns local setup guidance. | +| `message_foreman` | Sends a message to a task's foreman. | +| `get_conversation` | Reads a task's foreman conversation. | +| `send_task` | Creates a new task, or hands work back to an existing one. | +| `list_notification_routes` | Lists the notification destinations available to you in a factory. | +| `complete_task` | Marks a task complete. | + +## Related pages + +* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory, including the Slack, GitHub, GitLab, Linear, and Jira integrations. +* [Factory agents](/factories/factory-agents/) - The foreman and the other agents that carry out a factory's tasks. +* [How Warp Factories work](/factories/how-factories-work/) - The task lifecycle and the agents that move work through it. +* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send it its first work item. +* [Model Context Protocol in Warp](/agents/capabilities/mcp/) - How MCP servers work in the Warp app, with a catalog of popular MCP servers you can add to Warp directly. +* [Handoff between local and cloud agents](/platform/handoff/) - Move workspaces and conversations between local and cloud outside a factory. diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx new file mode 100644 index 000000000..94c03c724 --- /dev/null +++ b/src/content/docs/factories/how-factories-work.mdx @@ -0,0 +1,66 @@ +--- +title: How Warp Factories work +description: >- + A factory's foreman routes each work item through triage, specification, + implementation, and review, with humans making the key decisions. +sidebar: + label: "How Factories work" +--- + +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 for a person to review. You talk to one agent — the **foreman** — from whichever tool a request starts in, and it dispatches the factory's other agents, each owning one part of the software development lifecycle. + +A **work item** is one unit of that engineering work, such as an issue, support request, pull request, or Factory MCP task. It keeps its identity from intake to handoff, however many agents contribute to it along the way. + +## How a work item moves through the factory + +The foreman coordinates every work item. It routes work between the factory's agents, passes each one the context it needs, and continues existing agent conversations instead of starting new ones. See [factory agents](/factories/factory-agents/) for what each agent does. + +Not every work item needs every stage. The foreman picks the shortest path that still meets your quality policy: it skips stages when the work is already well defined, starts partway through when enough context exists, and sends work back to an earlier agent when revisions are needed. + +### Stages + +The diagram below shows the default path through a factory's stages. + +```mermaid +flowchart LR + Intake[Intake] --> Foreman[Foreman] + Foreman --> Triage[Triage] + Triage --> Decision{Specification needed?} + Decision -->|Yes| Spec[Specify] + Decision -->|No| Implement[Implement] + Spec --> Approval["Human review
(default policy)"] + Approval --> Implement + Implement --> Review[Review and verify] + Review --> Revision{Revision needed?} + Revision -->|Yes| Implement + Revision -->|No| Handoff["Human handoff
(default policy)"] + Handoff --> Complete[Complete] +``` + +* **Intake** - A work item enters from a [connected integration](/factories/connect-your-factory/), an automation, a direct run, or the [Factory MCP](/factories/factory-mcp/). It keeps its source context as it moves through later stages. +* **Triage** - The triage agent researches the request, reproduces the problem when needed, and defines the scope and complexity of the change. The foreman skips this stage when the request is already well bounded. +* **Specification** - The specification agent defines product behavior, technical constraints, and validation criteria. The foreman skips this stage for localized changes. +* **Implementation** - The implementation agent makes the code change on a branch and opens a pull request with test and visual evidence. +* **Review and verification** - The review agent checks the change against the requirements, tests, and security expectations, then sends findings back to implementation. Its verdict is advisory. +* **Human handoff** - The factory presents the result, its evidence, and any findings. A person decides what happens next. +* **Complete or Cancelled** - The work item ends when the factory finishes its work, or stops early if someone cancels it. + +In the [factory dashboard](/factories/factory-dashboard/), the **Activity** view is where you find, filter, and stop work items. It groups these stages under its own names — Triage, Planning (specification), Building (implementation), and Reviewing — and each agent's run within a work item is an ordinary [cloud agent run](/platform/) you can watch and steer. + +## Where your team stays in charge + +A factory is built to pause where the call belongs to a person. By default, that's three places: + +* **Approving the spec** - When work goes through the spec stage, implementation waits until a person signs off on the plan. +* **Answering questions** - When requirements are unclear or a review finding is ambiguous, the foreman asks instead of guessing. +* **Merging** - The factory opens the pull request and hands it off. Whether and when it merges is your team's call. + +The first two are workflow policy, written into the foreman's instructions; edit them to change when the factory checks in. Merging is enforced by your repository, so if you require human-only merges, use branch protection and repository permissions. + +## How the factory improves itself + +Your factory is self-improving, and you define what "better" means. [Scorers](/factories/measure-and-improve/) grade completed runs against criteria you write, and [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) groups the failures they flag into follow-up runs that propose fixes — to the application code or to the factory's own definition. Every proposal arrives as a change for your review; nothing is adopted on its own. + +The factory's definition is open to the same loop. Anyone on the team, or an agent, can propose changes to its instructions, skills, models, or other [definition files](/factories/factory-as-code/), and definitions stored in GitHub go through pull request review and [configuration checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) before a change reaches the production branch. + +See [measure and improve](/factories/measure-and-improve/) for the evaluation workflow, or [build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent/) to apply the same pattern to a standalone agent. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx new file mode 100644 index 000000000..a7de7b785 --- /dev/null +++ b/src/content/docs/factories/index.mdx @@ -0,0 +1,67 @@ +--- +title: Warp Factories overview +description: >- + Warp Factories runs cloud software factories where specialized agents move + engineering work from intake to a reviewed pull request. +sidebar: + label: "Overview" +--- +import { VARS } from '@data/vars'; + +Warp Factories lets engineering teams define and operate **software factories**: cloud workflows where specialized agents move engineering work from intake to a reviewed pull request. The factory does the repetitive work; your team stays in the loop at the points that matter, approving specs when needed and merging every pull request. + +:::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. +::: + +## What is a software factory? + +A software factory automates the software development lifecycle. It takes a **work item**, such as an issue, ticket, or triggered task, and moves 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. It connects 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. + +## Who benefits from Warp Factories + +Warp Factories is designed for engineering teams with repeatable work that extends beyond one coding session, such as: + +* **Backlog work** - Process issues with a consistent triage and delivery policy. +* **Operational requests** - Fix defects reported through support channels. +* **Code maintenance** - Review incoming pull requests or maintain services across repositories. + +## What you get with Warp Factories + +* **Coordinated specialist agents** - A team of [factory agents](/factories/factory-agents/) handles each work item. A coordinating foreman routes it through the triage, spec, implement, and review agents, skipping stages that don't apply. You can add custom agents and automations to handle work the defaults don't cover. +* **Definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, skills, and MCP servers, so factory changes get the same review, history, and rollback as code changes. +* **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 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/) grade completed work, and [Self-improvement](/factories/measure-and-improve/#configure-and-review-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, scope secrets, and (if eligible) store transcripts, artifacts, and run attachments in their own S3 or GCS buckets. See [infrastructure and security](/factories/infrastructure-and-security/) for the available controls. + +## How Warp Factories relates to other Warp products + +| 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, 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: + +* **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. + +A standalone [cloud agent](/platform/) remains the right tool for a single task or a one-trigger automation. Reach for a factory when the work is a standing, multi-stage process your team wants to route, measure, and improve in one place. + +## Next steps + +* [**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. +* [**Meet the factory agents**](/factories/factory-agents/) - See what each agent does and how to configure its model, harness, and instructions. +* **Adapt the system** - [Define the factory as code](/factories/factory-as-code/) and [connect its work sources](/factories/connect-your-factory/). diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx new file mode 100644 index 000000000..158836c1c --- /dev/null +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -0,0 +1,111 @@ +--- +title: Warp Factories infrastructure and security +description: >- + Warp Factories gives you control over inference, hosting, and run data so + you own your factory's infrastructure and outputs. +sidebar: + label: "Infrastructure & security" +--- + +Warp Factories runs on the infrastructure your team chooses. You decide where a factory runs code, which model providers serve its inference requests, where run data such as transcripts and artifacts is stored, and which credentials each agent receives. Warp coordinates the work the same way regardless of these choices. + +## Control plane and execution plane + +Every factory splits responsibilities across two planes: + +* **Control plane** - Warp coordinates runs, identity and configuration, observability, integrations, storage, and inference routing. +* **Execution plane** - A Warp-hosted sandbox or a managed self-hosted worker checks out code, runs setup, invokes tools, builds the project, and executes commands. + +```mermaid +flowchart LR + I["Integrations and triggers"] --> C["Warp control plane
coordination · identity/config
observability · inference routing"] + C --> H["Warp-hosted sandbox"] + C -->|"task, config, and scoped
runtime credentials"| S["Managed self-hosted worker"] + H -->|"results, transcripts,
artifacts, telemetry"| C + S -->|"results, transcripts, attachments,
artifacts, and telemetry
can contain code context"| C + C --> P["Warp-managed or
customer-configured inference"] + C --> D["Warp or supported
customer-owned 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. + +## Runners + +A runner defines the compute a factory's agents work on: the operating system and architecture, the sandbox image, and the instance shape (vCPUs and memory). It's the infrastructure choice you make for a factory. The workspace itself — repositories, setup commands, and secrets — comes from the factory's [definition](/factories/factory-as-code/), and Warp keeps it in step for you. See the [runner reference](/platform/runners/) for the available compute options. + +Runners are declared as `runners/*.yaml` files in the definition, and you can define more than one — a Linux runner with more cores and memory for builds, a macOS runner for platform-specific work. Every agent inherits the factory's default (`agentDefaults.runner`), and any agent or automation can name its own `runner` instead, so the foreman can send implementation to a macOS runner while every other agent stays on Linux. + +The **Runners** section of a factory's **Settings** page in the [factory dashboard](/factories/factory-dashboard/) shows each runner's operating system and architecture, setup commands, size, and whether it's the default. Where you edit runners depends on where the factory's source lives: + +* **Externally managed source** - The `runners/*.yaml` files in the connected repository are the source of truth, and edits open in that repository. +* **Warp-managed source** - Authorized users create and edit runner files directly in the factory dashboard. + +Your team's plan sets the default instance shape (vCPUs and memory) for Warp-hosted runners. The same maximum shape applies on every plan, and Warp rejects hosted shapes above it. Enterprise teams that need more can request a higher maximum. Managed self-hosted runners are exempt from the hosted maximum because your team supplies the compute. + +## Choose an execution host + +A factory runs its work on one of two execution hosts: Warp-hosted compute or a managed self-hosted worker. + +| Decision area | Warp-hosted | Managed self-hosted | +| --- | --- | --- | +| **Compute** | Warp provisions the sandbox | Your team provisions the worker | +| **Checkout and commands** | Run on Warp-managed compute | Run on your infrastructure | +| **Control plane** | Runs through Warp | Runs through Warp | +| **Network** | Warp manages sandbox connectivity | The worker connects outbound to Warp; no inbound firewall port | +| **Private services** | Must be reachable from the hosted sandbox | Reachable through the worker's network access | +| **Operations** | Warp manages capacity and lifecycle | Your team manages capacity, isolation, updates, and availability | + +To route factory work to a managed self-hosted worker (an Enterprise feature): + +1. **Deploy a worker** - Review the [self-hosting requirements](/platform/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. + +Unmanaged self-hosted agents and other CLI agents can't serve as a factory's execution host, but they can exchange work with a factory through [Factory MCP](/factories/factory-mcp/). + +## Choose execution, inference, and storage independently + +Execution, inference, and storage are independent choices: each moves one boundary and leaves the rest of the run flow with Warp. + +| Team choice | What it changes | What stays with Warp | +| --- | --- | --- | +| **Execution**: Warp-hosted or managed self-hosted | Where checkout, commands, and the sandbox filesystem run | Coordination, configuration, observability, and inference routing | +| **Inference**: Warp-managed or customer-supplied | The provider account, model routing, billing, and provider-side retention | Run coordination and inference routing | +| **Storage**: Warp or customer-owned | Where supported transcripts, artifacts, and run attachments persist | Orchestration, the write path, and other factory and control-plane state | + +:::note +Managed self-hosted execution, customer-supplied inference, and customer-owned storage all require an Enterprise plan. +::: + +Factory runs execute as [cloud agents](/platform/), so customer-supplied inference is limited to providers that support cloud agents. See [team-managed model keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) and [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) for the supported providers. When you supply the provider, provider-side retention follows your provider account and contract; Warp can't configure or enforce it for you. The [security overview](/enterprise/security-and-compliance/security-overview/) covers Warp's broader data handling. + +For storage, Enterprise teams can keep the supported data classes above (transcripts, artifacts, and run attachments) in a customer-owned Amazon S3 or Google Cloud Storage bucket. Warp enables customer-owned storage for your team and writes the applicable data to the bucket you configure; your team owns the bucket's access and lifecycle policies. Customer-owned storage doesn't move all factory state into your account: configuration, run metadata, and other control-plane state stay with Warp. + +## Credential boundaries + +A factory handles four kinds of credentials, each with its own boundary: + +| Credential | Used for | Boundary | +| --- | --- | --- | +| **Inference credentials** | Model provider requests | Used only at the inference boundary; never injected into the sandbox | +| **Execution secrets** | APIs, package registries, and tools an agent uses | Delivered from an explicit per-agent allowlist; factory agents that don't act as a specific user receive no managed secrets by default | +| **Harness authentication** | Third-party harnesses such as Claude Code or Codex | Configured separately from the agent's secret allowlist | +| **Repository identity** | Checking out code and pushing changes | Runs act with the creating user's authorization (changes are attributed to them) or as the agent itself for unattended work; set by the definition's [`credentialStrategy`](/factories/factory-as-code/#credentialstrategy) | + +Scope each credential to the resources and actions its agent needs. Warp redacts known secret values at output boundaries, but redaction is a backstop, not a substitute for narrow external permissions and rotation. See [cloud agent secrets](/platform/secrets/), [harness authentication](/platform/harnesses/authentication/), [secret redaction](/support-and-community/privacy-and-security/secret-redaction/), and [team identity](/platform/team-access-billing-and-identity/) for the underlying controls. + +## Governance and metering + +Factories use your existing [team roles](/enterprise/team-management/roles-and-permissions/): Team Owners and Admins control factory definitions, runners, secrets, and provider configuration. Warp Factories doesn't add a factory-specific approval role, so who reviews specifications and who approves merges stays a workflow and repository policy decision. Treat factory-definition changes as operational code: review them like any other change, and keep merge access with the people responsible for shipping. + +Warp meters hosted compute, Warp-provided inference, and platform services. Managed self-hosted execution moves compute costs to your own infrastructure, and customer-supplied inference bills model usage through your provider account. Platform services consume credits regardless of these choices. See [platform credits](/support-and-community/plans-and-billing/platform-credits/) for details. + +## Deployment checklist + +1. **Classify the workload** - Identify the repositories, data, internal services, and regulated systems the factory can reach. +2. **Choose execution** - Decide where checkout, commands, and the sandbox filesystem must run. +3. **Configure the factory and its runners** - Set the repositories, setup commands, and secrets in the factory's definition, and choose each runner's operating system, architecture, image, and compute. +4. **Choose inference and storage** - Select provider routing and where supported run data persists. +5. **Scope credentials** - Set each agent's secret allowlist, harness authentication, and repository identity. +6. **Set review gates** - Decide where humans review specifications and pull requests, and enforce those gates in workflow and repository policy. +7. **Validate operations** - Test network egress, isolation, rotation, redaction, capacity, observability, and metering before increasing volume. diff --git a/src/content/docs/factories/integrations/github.mdx b/src/content/docs/factories/integrations/github.mdx new file mode 100644 index 000000000..e94961723 --- /dev/null +++ b/src/content/docs/factories/integrations/github.mdx @@ -0,0 +1,132 @@ +--- +title: Connect GitHub to your factory +description: >- + Connect GitHub to your factory so issues, pull requests, reviews, and CI + events start factory work and results post back to GitHub. +sidebar: + label: "GitHub" +--- +import { VARS } from '@data/vars'; + +When you connect a factory to GitHub, repository activity starts work in your factory. Issues, pull requests, reviews, and CI events can all trigger automations, and the factory posts results back to GitHub as comments, branches, and pull requests. + +## Prerequisites + +* **The Warp GitHub App** - Follow the [GitHub integration setup](/platform/integrations/github/) if you haven't already. One installation serves both the platform integration and factories. +* **A factory with GitHub repositories** - The app must have access to at least one of the factory's repositories. + +## Connect GitHub to a factory + +1. In the {VARS.FACTORY_WEB_APP} at platform.warp.dev, click **+** next to **Factories** to open the setup wizard, then choose **I want to use repos from GitHub** under **Connect your code host**. +2. Under **Select your repos**, choose the repositories to provide code and context for the factory. + +That's all the setup GitHub needs. A new factory arrives with two automations already switched on, so it responds to GitHub activity right away: + +* **Mentions and assignments** - Start work. See [Mention the factory](#mention-the-factory) below. +* **Pull request merges** - Close out work. Any work items linked to the pull request move to their tracker's completed state. Closing without merging does nothing. + +To confirm the connection works, mention the factory on a test issue and check that a work item starts in the factory's [dashboard](/factories/factory-dashboard/). + +## Add a custom automation + +The defaults cover mentions, assignments, and pull request completion. To start work from any other GitHub activity, such as a failed CI run or a review request, add an automation with a **GitHub** trigger for that event, then narrow it with the filters below. [Automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. + +## Supported triggers + + ++++ + + + + + + + + + +
TriggerSupported activity
IssuesCreated, labeled, assigned, or agent mentioned
Pull requestsOpened, marked ready, reopened, updated with commits, assigned, labeled, mentioned, closed, or merged
ReviewsReview requested or review submitted
Code and CIPush, a completed check suite or workflow run, or a re-run of a Warp check
+ +Re-running a check starts work only for checks Warp itself created. GitHub doesn't send re-run events for other providers' checks, so those can't trigger a factory. + +### Automation filters + +Every trigger names the repository it watches. The remaining filters appear only on the event types they apply to: + +| Filter | Matches | Appears on | +| --- | --- | --- | +| **Branches** | The pushed branch, or a CI run's head branch | Push and CI triggers | +| **Base branches** | The branch the pull request targets | Pull request triggers | +| **Paths** | The files the change touches | Push and pull request triggers | +| **Labels** | Labels on the issue or pull request | Issue, pull request, review submitted, and CI triggers | +| **Authors** | Who opened the issue or pull request | Issue, pull request, and CI triggers | +| **Assignees** | Who the issue or pull request is assigned to | Issue and pull request triggers | +| **Mentioned users or teams** | Which user or team is @mentioned | Mention and review submitted triggers | +| **Reviewers** and **Reviewer teams** | Who review was requested from | Review requested triggers | +| **Review states** | Whether the review approved, requested changes, or commented | Review submitted triggers | +| **Workflows** | The GitHub Actions workflow, by name | Workflow run triggers | +| **Conclusions** | The run's result: success, failure, cancelled, and so on | Check suite and workflow run triggers | + +On check suite and workflow run triggers, **Labels** and **Authors** match the pull request linked to the run rather than the run itself. + +Use filters to route work precisely. For example, send failed runs of a specific workflow to a CI-repair automation. + +## Mention the factory + +Handing an issue or pull request to a factory takes two things: + +1. **Add the factory's label.** Each factory has one, named `factory:` followed by its [**Foreman name**](/factories/factory-dashboard/#change-factory-settings). For example, a factory whose foreman is named `payments` uses `factory:payments`. Warp creates the label in every connected repository, so it's already in the list. +2. **Mention or assign @warp-factory**, in the body or in any new comment. + +The factory picks up the request and replies in the same thread. + +Both halves matter, because **@warp-factory** is the account every factory listens through. The label is what decides which of your factories answers, so a mention without one doesn't start work. + +Only new content counts as a mention. Edits to existing comments, mentions inside code blocks, and mentions from bots are ignored. + +You can change what the factory answers to. The handle and the label are the starting filters on its mentions automation: edit them to respond to a different handle, such as your own `@org/team` slug, or remove the label filter so that any mention in the factory's repositories starts work. + +## How the factory responds on GitHub + +The factory posts progress comments in the originating issue, pull request, or review thread, with links to the run and to any branches or pull requests it creates. Events without a comment surface, such as a push or a workflow run, report their results on the work item instead. + +New activity on an issue, pull request, or review thread the factory is already working on continues that work item instead of starting a new one. + +Issues and pull requests the factory opens carry its label, the same one you use to mention it. Warp adds the label to each repository you connect and removes it when you disconnect one or delete the factory, so you never create or clean it up by hand. If a label is ever left behind, delete it like any other GitHub label. + +Branches and pull requests the factory creates follow the repository's normal rules — branch protection, required reviews, and merge requirements all still apply. + +## Permissions + +Runs authenticate with the GitHub App installation, not with the account of the person whose activity triggered them: + +* **The app installation decides what agents can reach.** Agents get exactly the repositories and permissions the installation grants, so change the installation to change access — [automation filters](/factories/automation-filters/) only change when work starts. +* **Anyone who can create matching activity can start work.** The event author doesn't need to be a Warp team member. Use author, label, and branch filters to control what starts runs. + +For the full credential model, see [Permissions and identity](/platform/integrations/github/#permissions-and-identity) on the GitHub integration page. + +## Factory-definition pull request checks + +If the factory's [definition is managed as code](/factories/factory-as-code/) in a GitHub repository, Warp reviews changes to it the way CI reviews code. Open a pull request that touches the definition files and a **warp/factory-config** check runs: it passes with a summary of what the change does, or fails with the specific fields to fix. Require the check in branch protection to stop an invalid definition from merging. + +These checks validate the factory's configuration files only. They don't create work items, and pull requests that don't touch the factory directory don't get the check. + +## Troubleshooting + +### A GitHub event doesn't start work + +Confirm the app installation covers the event's repository, the repository belongs to the factory, and the automation includes that event. Then check each filter; a label, author, branch, workflow, conclusion, or state mismatch prevents routing. + +### Filter options don't load + +Select a repository first. If the automation editor shows **Connect GitHub**, complete the account connection and retry. You can enter a value manually when suggestions are unavailable. + +### An agent can't push a branch or open a pull request + +Check that the installation still covers the target repository and grants the required write permissions. Automation filters don't affect GitHub authorization. + +### A factory-definition check doesn't appear + +The check runs only for factories whose [definition is managed as code](/factories/factory-as-code/) in a GitHub repository. Confirm the pull request targets the branch the factory runs from, that it changes files in the factory's definition directory, and that the GitHub App covers the repository. diff --git a/src/content/docs/factories/integrations/gitlab.mdx b/src/content/docs/factories/integrations/gitlab.mdx new file mode 100644 index 000000000..6a98e194a --- /dev/null +++ b/src/content/docs/factories/integrations/gitlab.mdx @@ -0,0 +1,136 @@ +--- +title: Connect GitLab to your factory +description: >- + Connect GitLab to your factory so merge request events and bot mentions start + factory work and results post back as comments and merge requests. +sidebar: + label: "GitLab" +--- +import { VARS } from '@data/vars'; + +When you connect a factory to GitLab, project activity starts work in your factory. Merge request events and bot mentions trigger automations, and the factory posts results back to GitLab as comments, branches, and merge requests. + +## Prerequisites + +* **GitLab.com** - The integration supports GitLab.com only, not self-managed GitLab instances. To use a self-managed instance with standalone cloud agents instead, see the [GitLab access token setup](/platform/integrations/gitlab/). +* **A top-level GitLab group you own** - Connecting GitLab links one top-level group to your Warp workspace, one-to-one. Creating the link requires the Owner role on the group and workspace admin permissions in Warp. +* **A paid GitLab plan (Premium or Ultimate)** - Warp provisions [service accounts](https://docs.gitlab.com/user/profile/service_accounts/) in your group and installs a [group webhook](https://docs.gitlab.com/user/project/integrations/webhooks/#group-webhooks). Group webhooks are available only on Premium and Ultimate plans. On the Free tier, GitLab can't deliver the webhook events that trigger runs: factory credentials still work, but nothing starts work from GitLab. + +## Your factory's GitLab identity + +Each factory gets its own GitLab service account — its bot. The bot is the factory's identity on GitLab: its username is the handle you mention, runs act as it, and the projects it belongs to are exactly the ones you select for the factory. Warp creates and retires these accounts for you. + +## Connect GitLab to a factory + +When you create a factory, choose **I want to use repos from GitLab** as the code host, then: + +1. **Connect a top-level group.** Warp links it to your Warp workspace and sets up event delivery from it. A group already connected to your workspace is selected for you. +2. **Select the projects the factory works in.** Anything under the connected group is available, including projects in subgroups. + +That's the setup. A GitLab factory starts with one default automation, **gitlab-bot-mentions**, so mentioning the bot in a merge request comment starts work right away. To confirm it, do exactly that: comment on a merge request in one of the selected projects, mention the bot, and watch for a work item in the factory's [dashboard](/factories/factory-dashboard/). + +To start work from merge request events as well, add a **Merge request** trigger to an automation; [automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. + +## Supported triggers + + ++++ + + + + + + + +
TriggerFires when
Merge requestA merge request is opened, updated, closed, reopened, merged, or approved
Bot mentionedA new comment mentions the factory's bot username
+ +### Automation filters + +| Filter | Matches | Appears on | +| --- | --- | --- | +| **Project** | The GitLab project the event came from | Both triggers | +| **Actions** | What happened to the merge request, such as opened, updated, or merged | Merge request | +| **Base branch** | The branch the merge request targets | Merge request | + +The **Bot mentioned** trigger always listens for the factory's own bot. You can't point it at a different username. + +## Mention the factory + +Each GitLab factory has its own bot account, so the mention itself routes the request. There is no shared handle or routing label to apply. To mention the factory: + +1. Open a merge request in one of the factory's projects. +2. Post a comment that mentions the factory's bot username and includes an instruction. + +The **gitlab-bot-mentions** automation starts a work item, and the factory replies in the same thread. To find the bot's username, check that automation's trigger in the [factory dashboard](/factories/factory-dashboard/). + +Mentions count only in new comments. Edits and activity from Warp's own service accounts never trigger work, so a factory can't re-trigger itself or a sibling factory. + +## How the factory responds on GitLab + +The factory acts on GitLab as its bot account: + +* **Replies in the thread it was mentioned in** - Its comments link back to the run session and the factory work item. New comments on the same merge request continue that work item instead of starting a new one. +* **Pushes branches and opens draft merge requests** - Branches are named `factory/`, and merge requests open as drafts that the factory marks ready when the work is done. Commits and comments attribute to the bot's GitLab profile. +* **Labels what it touches** - Merge requests and issues the factory opens or adopts carry its own label, named `factory:` followed by the factory's [**Foreman name**](/factories/factory-dashboard/#change-factory-settings). +* **Posts review feedback as comments** - A review lands as a summary note plus inline discussions on the diff. When a later revision addresses a finding, the factory replies in that discussion and resolves it. + +The factory never merges or approves a merge request, and your project's protection and approval rules apply to everything the bot does. + +## Permissions + +Runs authenticate as the factory's bot account, not as the person whose activity triggered them: + +* **The bot's project membership decides what runs can reach.** A run can reach the projects the factory selected, with the bot's Developer role, and nothing else. To change what it can reach, change the factory's projects — [automation filters](/factories/automation-filters/) only change when work starts. +* **Anyone who can create matching activity can start work.** The commenter doesn't need to be a Warp team member. Use project, action, and base-branch filters to control what starts runs. + +Disconnecting GitLab from your workspace retires every factory bot along with it. + +## Definitions as code + +If the factory's [definition is managed as code](/factories/factory-as-code/), declare GitLab triggers in an automation file: + +```markdown title="automations/gitlab-merge-requests/automation.md" +--- +enabled: true +agent: foreman +triggers: + - provider: gitlab + event: merge_request + filter: + repos: [my-group/my-app] + actions: [open] +--- + +Triage newly opened merge requests and post an initial review. +``` + +A `bot_mentioned` trigger takes only a `repos` filter. Leave `mentioned` out, since the bot username isn't yours to set. + +A GitLab-backed factory can still be managed as code, but the definition itself lives either in Warp or in a GitHub repository — GitLab is not yet available as a definition host. See [where the definition lives](/factories/factory-as-code/#where-the-definition-lives). + +## Troubleshooting + +### A mention doesn't start work + +Confirm the mention is in a new comment rather than an edit, the username matches the factory's bot exactly, the project is one of the factory's selected projects, and the **gitlab-bot-mentions** automation is enabled. + +### A merge request event doesn't start work + +Confirm an enabled automation includes the **Merge request** trigger and check its project, action, and base-branch filters. Activity authored by Warp's own service accounts is always ignored. + +### Nothing starts work even though GitLab is connected + +Your GitLab plan may not include [group webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/#group-webhooks), which are a GitLab Premium and Ultimate feature (see [Prerequisites](#prerequisites)). Upgrade your GitLab plan to let GitLab trigger runs. + +### The bot can't push a branch or open a merge request + +Confirm the target project is one of the factory's selected projects and the operation is permitted for the Developer role. Pushes to protected branches follow the project's protection rules. + +### Your group isn't listed when connecting + +Only top-level groups you own appear, and a group already connected to another Warp workspace can't be connected again. If you don't own the group, ask an owner to establish the connection in Warp. + +For the other ways to route work into a factory, see [Connect your factory](/factories/connect-your-factory/). diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx new file mode 100644 index 000000000..791b7c1a8 --- /dev/null +++ b/src/content/docs/factories/integrations/jira.mdx @@ -0,0 +1,86 @@ +--- +title: Connect Jira to your factory +description: >- + Connect Jira Cloud to your factory so work items assigned to Warp start + factory runs and return results in Jira. +sidebar: + label: Jira +--- +import { VARS } from '@data/vars'; + +Connect Jira Cloud to your factory so your team can start factory work without leaving Jira. When someone assigns or mentions **Warp** on a work item, Jira starts an agent session, a factory automation routes the request to the agent you chose, and the same session shows progress and the final result. + +## Prerequisites + +* **Jira Cloud** - The integration supports Jira Cloud only, not Jira Server or Data Center. +* **A Jira site admin** - Installing the Warp app on a Jira site and connecting it to a Warp workspace requires site admin permissions. +* **A factory** - You need a factory in the connected workspace and permission to edit its [definition](/factories/factory-as-code/). +* **The Warp agent in Jira** - The **Warp** agent must be available on your Jira site so people can assign or mention it on work items. Jira lists it among Atlassian's Rovo agents. + +## Connect Jira and add an automation + +1. **Install the Warp app on your Jira site and connect it to your Warp workspace.** The [Jira integration setup](/platform/integrations/jira/#setup) walks through both. Once connected, every factory in the workspace can use it. (That page's `warp-agent` label flow starts standalone cloud agent runs; factories skip the label and use an automation instead.) + +2. **Connect Jira to this factory.** A workspace connection makes Jira available to your factories, but each one opts in separately: in the factory's **Settings**, connect **Jira** and select the projects that should trigger it. + +3. **Point an automation at Jira.** In the factory's dashboard, open **Automations** and add a trigger for **Jira** > **Agent session created**. Use **Projects** and, optionally, **Keywords** to scope which sessions start a run, and choose the agent that handles them. + + If you picked Jira projects when you created the factory, that automation already exists — edit it rather than adding a second one. + + To set this up in code instead, declare the `jira` integration in the factory's `factory.yaml` (`integrations: [{type: jira}]`), then add a file under `automations/`, such as `automations/jira-assignment/automation.md`, with an `agent_session_created` trigger: + + ```markdown title="automations/jira-assignment/automation.md" + --- + enabled: true + agent: foreman + triggers: + - provider: jira + event: agent_session_created + filter: + project_keys: [ENG] + keywords: [investigate, fix] + --- + + Handle the Jira assignment and return a concise result. + ``` + + With this automation, the agent named `foreman` handles sessions for work items in the `ENG` project whose assignment text contains `investigate` or `fix`. Commit and push the files to apply them; see [definitions as code](/factories/factory-as-code/) for the full syntax. + +4. **Test it.** Assign or mention **Warp** on a work item and include an instruction. Jira starts an agent session, and the run appears under the matching automation in your factory. + +## Filter which sessions start runs + +All Jira work reaches the factory through a single event, `agent_session_created`, which fires when someone assigns or mentions **Warp** on a work item. A session starts a run only when it matches an enabled automation. Use the trigger's `filter` to narrow what matches: + +* **`project_keys`** - Match work items in these Jira projects. +* **`keywords`** - Match assignment text that contains any of these words. Matching is case-insensitive. + +A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. For the matching rules shared by every source, see [automation filters](/factories/automation-filters/). + +:::caution +A Jira event is offered to every automation in the connected workspace, so another team's automation with a broader filter can start its own run on the same work item. Filters decide what *your* automation picks up, not who else can see the event. See [automation filters](/factories/automation-filters/#filters-route-work-they-dont-restrict-access). +::: + +## What happens during a run + +The agent runs in the cloud and starts with the assignment text and the work item it came from. When the factory declares Jira as an integration, the agent can also read the work item's details, comments, and available workflow transitions. + +Jira shows the task's status as it progresses: submitted, working, waiting for input, completed, failed, or cancelled. For more than status updates, open the run under the matching automation in your factory: [cloud agent session sharing](/platform/viewing-cloud-agent-runs/) shows the full run, including every command, log, and output, in real time or after the run finishes. + +Replies in the same agent session continue the same run, even after the agent finishes a turn, so you can answer questions or add direction mid-task. + +When the run finishes, the result appears in the agent session. The agent doesn't comment on the work item unless you ask it to. The agent can act in Jira when asked: update the work item, post or edit comments, change workflow status, add or remove labels, or reassign it. State the actions you want in the automation instructions or the assignment; Jira permissions and valid workflow transitions apply to everything the agent does. + +## Permissions + +* **A connected Jira user becomes the run's creator, not its agent** - [Connect your Jira account to Warp](/platform/integrations/jira/#connecting-your-jira-account-to-warp) so a session you start is attributed to you; an unconnected account gets a prompt to connect instead of a run starting. Either way, the run executes as the agent selected by the automation, not as that Jira user. +* **Jira access doesn't include code access** - Connecting Jira lets agents read and update Jira work items, nothing more. Repository access comes from the factory itself. + +## Troubleshooting + +* **Warp is unavailable in Jira** - Confirm the Warp app is installed on the Jira Cloud site. On the app's **Configure** page, click **Connect to Warp** if the installation isn't connected to a workspace. +* **No run starts** - Confirm an enabled `agent_session_created` automation exists, its agent is available, and its project and keyword filters match the assignment. +* **The session shows no result** - Open the matching automation's run to see whether the agent is still working, waiting for input, or failed. +* **A Jira update fails** - Confirm the app can access the work item's project and that the requested action or workflow transition is valid. + +For the other ways to route work into a factory, see [Connect your factory](/factories/connect-your-factory/). diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx new file mode 100644 index 000000000..5a54ff617 --- /dev/null +++ b/src/content/docs/factories/integrations/linear.mdx @@ -0,0 +1,77 @@ +--- +title: Connect Linear to your factory +description: >- + Connect Linear to your factory so planned issues flow in automatically and + progress flows back to the issue. +sidebar: + label: "Linear" +--- + +Connect Linear to your factory so your team can send it issues without leaving Linear. Assign an issue to the factory or tag it in a comment, and the factory picks it up with the issue's full context, then keeps the issue updated as the work moves through [its stages](/factories/how-factories-work/). + +When the factory needs an answer, reply in Linear, or open the live run to steer the agent directly. + +## Prerequisites + +* **A factory** - Create a factory with the agents and repositories needed to handle Linear work. +* **A Linear workspace** - Use a Linear account that can authorize the Warp app for the workspace. +* **A linked Warp account (agent sessions only)** - Anyone who starts a Linear agent session must link their Linear user to their Warp account. If Warp can't identify the session creator, Linear shows an authentication prompt instead of starting work. +* **Code host access** - Configure repository access separately through the factory's [GitHub connection](/platform/integrations/github/). The factory needs it to change code or create a pull request. + +For workspace-level installation, reconnection, and removal steps, see the [Linear integration setup guide](/platform/integrations/linear/). + +## Connect Linear + +You connect Linear either while creating a factory, at the **Connect your issue trackers** step, or afterward from the factory's **Settings**. Either way you do the same two things: + +1. **Authorize Warp for your Linear workspace.** This is Linear's own OAuth flow, and it's only needed once per workspace. +2. **Choose which Linear teams trigger this factory.** + +Warp then adds a default automation that routes new [agent sessions](#route-agent-sessions) from those teams to your factory. Issue and comment activity doesn't start work until you [add triggers](#configure-linear-triggers) for it. + +## Route agent sessions + +When someone mentions, assigns, or delegates the Warp app on an issue, Linear starts an agent session. The default automation created when you connected Linear routes new sessions from your selected teams to the factory, so assigning an issue or tagging the factory in a comment is enough to start work. If a session doesn't match any automation, the [Linear integration](/platform/integrations/linear/) handles it with its default behavior. + +Replies in an existing session continue that run rather than starting a new one. To narrow which sessions reach the factory, such as by creator or keyword, edit the `agent_session_created` trigger in the factory's [definition files](/factories/factory-as-code/); session routing isn't editable from the automation editor. + +## Configure Linear triggers + +Agent sessions cover explicit requests. To start work automatically from issue and comment activity too, add an automation with a **Linear** trigger for one of these events: **Issue created**, **Issue labeled**, **Issue state changed**, **Issue assigned**, or **Comment created**. [Automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. + +Every Linear trigger filters on teams and labels, and **More filters** adds project, workflow state, assignee, mentioned user, and, for comment events, a specific issue. For example, a trigger can require that an issue belongs to one team, enters a chosen workflow state, and carries a release label. + +## Supported events and outputs + +Each event determines the context the agent receives and the updates the factory sends back. + +| Linear event | What the agent receives | What the factory sends back | +| --- | --- | --- | +| Issue created, labeled, state changed, or assigned | The issue's title, description, team, project, labels, workflow state, and assignee | Work item progress, issue state or delegate changes, and links to results | +| Comment created | The new comment and its issue's context | An acknowledgment, progress updates, and responses | +| Agent session created | The request that mentioned, assigned, or delegated the Warp app | Live progress in the session, plus links to the run and any pull request | +| Reply in an agent session | The new message and the session history | Continued work in the same session, not a separate work item | + +## Follow-up events on the same issue + +Once a Linear issue is linked to a factory work item, later matching events on that issue continue the same work item instead of creating a new one. + +:::caution +One comment can match two routes: a comment that creates an agent session can also match a **Comment created** trigger. If both point at your factory, a single action starts two runs. Scope your automations so one path owns each kind of request. +::: + +## What the factory can do in Linear + +In an agent session, the factory posts its plan, actions, and results as it works. It can also attach a GitHub pull request to the issue, update the issue's workflow state or delegate, link back to the run, and acknowledge comments it acts on. Its own Linear activity never triggers automations, so a factory can't set itself off in a loop. + +Only agent sessions require a linked Warp account. Issue and comment events from unlinked users still start work, but Warp may not record who requested it. + +Connecting Linear doesn't grant repository access. Branches and pull requests use the factory's code-host credentials, and the pull request still waits for a person to review and merge. + +## Troubleshooting + +* **An agent session shows an authentication prompt** - Complete the prompt to link your Linear user to your Warp account, then retry the request. +* **Teams or filters don't load** - Reconnect Linear by following the [Linear integration setup guide](/platform/integrations/linear/), then confirm the connection can access the workspace and team you expect. +* **An event doesn't start work** - Confirm the automation is enabled, the event type matches, and every filter matches the issue's current values or the state change. +* **One action starts multiple runs** - Look for overlapping agent-session and comment triggers, then narrow or remove one. +* **No pull request appears** - Check the factory's code-host credentials and repository access. Linear authorization alone doesn't allow code changes. diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx new file mode 100644 index 000000000..5f6505776 --- /dev/null +++ b/src/content/docs/factories/integrations/slack.mdx @@ -0,0 +1,79 @@ +--- +title: Connect Slack to your factory +description: >- + Connect Slack to your factory so your team can start work with mentions, + direct messages, and automations, and get results back in the same thread. +sidebar: + label: "Slack" +--- + +Connect a factory to Slack so your team can send it work without leaving their conversations. Mention the factory in a channel or send it a direct message, and it picks up the request with the conversation as context, then posts progress and results back into the same thread. + +Each factory appears in Slack as its own app, carrying the factory's name and avatar. A channel can host several factories, and you choose which one to mention. + +## Prerequisites + +* **Permission to install Slack apps** - You need it in the target workspace, and workspace policy can require an administrator to approve the app before it installs. +* **Permission to update the factory** - Connecting Slack changes the factory's configuration. + +## Connect the factory + +Select Slack while creating a factory and Warp installs its app for you. If the install can't finish on its own — usually because your workspace requires administrator approval — click **Add to Slack** in factory setup to complete it. + +Then invite the app to each channel it should listen in. Private channels always need an invitation. + +To check that it worked, mention the app in one of those channels. It reacts with 👀 to show it picked up the request. + +## Start and continue work from Slack + +| Slack activity | Context used by the factory | Slack output | +| -------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| Mention the app in a channel or thread | The triggering message, available thread history, and supported attachments | An acknowledgment, progress updates, a final summary, and links to the run, issue, or pull request when available | +| Send the app a direct message | The direct-message conversation and supported attachments | An acknowledgment, progress updates, and links to results when available | +| Reply in an existing factory thread | The existing work item and your reply | A follow-up on the existing work item instead of new work | +| Slack activity matches an automation | The event details plus the automation's agent and instructions | A factory run, with results posted back to the source conversation when supported | + +A plain reply in a thread continues work only if that thread already has a factory work item; to start new work in a channel, mention the app. You can attach files to a request or a follow-up. The factory includes the files it supports, and a file it can't include doesn't stop the text of your request from going through. + +## Who can start work + +To start work with a mention or direct message, your Slack account must be linked to an active member of the factory's Warp team. If it isn't, the app prompts you to connect an account instead of starting work. + +Work started by an automation runs as the factory agent you chose for it, not as whoever triggered it. + +## Configure factory automations for Slack + +Use a factory automation to start work from Slack activity automatically, without anyone mentioning the app, such as on every message in a triage channel or on a specific emoji reaction. Add a **Slack** trigger to an automation and pick one of these events; [automation filters](/factories/automation-filters/#edit-filters-on-an-automation) covers the steps. + +- **App mentioned** - Filter by joined conversations, authors, and keywords. +- **Direct message received** - Filter by direct-message conversations, authors, and keywords. +- **Message posted in channel** - Filter by joined conversations, authors, and keywords. +- **Reaction added** - Filter by conversations, reactors, keywords, emoji, and reacted-message authors. +- **Member joined channel** - Filter by conversations and members. + +The **Conversations** picker only shows conversations the factory's app has joined. If a channel is missing, invite the app to it; for direct messages, send the app a DM first. Then refresh the automation editor. + +A single Slack message can match more than one automation. For example, if one automation triggers on **App mentioned** and another triggers on **Message posted in channel** in the same channel, a channel message that mentions the app starts two separate runs, one for each automation. To avoid duplicate runs, don't point both triggers at the same channel. + +## Follow work and review outputs + +The Slack thread where work started is also where you follow it: the factory posts progress and the final response there. Reply in the thread to add information or attachments while work is active, or to pick the same work item back up later. + +For an overview of the factory's work items, open the app's **Home** tab in Slack. It groups them by the same stages as the factory dashboard's [Activity view](/factories/factory-dashboard/#track-work-items-on-activity) (Triage, Planning, Building, Reviewing, Completed, and Cancelled), offers stage and date filters, and links each work item back to its Slack thread, factory run, issue, or pull request when available. + +Work that starts in Slack still ends at a pull request for a person to review — see [how Warp Factories work](/factories/how-factories-work/). + +## Troubleshooting and reconnection + +- **The app doesn't acknowledge a request** - Confirm Slack is connected for that factory, that you mentioned the right factory's app, and that the app is in the channel. +- **A channel is missing from an automation** - Invite the app to that channel, then reload the **Conversations** picker. +- **Installation is pending** - Ask a Slack workspace administrator to approve the app, then finish the installation. +- **Two runs start for one mention** - Remove or narrow overlapping app-mention and channel-message triggers. + +To disconnect Slack, either delete the factory — which removes its Slack app along with it — or [remove the app from your Slack workspace](https://slack.com/help/articles/360003125231-Remove-apps-and-custom-integrations-from-your-workspace), which stops new Slack requests reaching that factory. To reconnect afterward, click **Add to Slack** in factory setup again. + +To route work into the factory from other tools, see [Connect your factory](/factories/connect-your-factory/). + +## Privacy + +The factory's app reads messages only where it's mentioned, directly messaged, or subscribed by an automation you configured. Message content and supported attachments are used to run the factory's work, and your Slack profile email is used to map you to your Warp account. Data is handled per the [Warp Privacy Policy](https://www.warp.dev/privacy). diff --git a/src/content/docs/factories/measure-and-improve.mdx b/src/content/docs/factories/measure-and-improve.mdx new file mode 100644 index 000000000..357b31ec0 --- /dev/null +++ b/src/content/docs/factories/measure-and-improve.mdx @@ -0,0 +1,107 @@ +--- +title: Measure and improve a factory +description: >- + Measure factory activity and costs, evaluate completed conversations, compare + agent configurations, and turn failures into follow-up work. +sidebar: + label: "Measure and improve" +--- + +Warp Factories tracks what your factory produces and how well it performs, so you can spot a problem, test a fix, and decide whether to keep it. + +| Feature | What it tells you | +| --- | --- | +| Dashboard metrics | How much work the factory produced, and what it cost. | +| Scorers | Whether completed conversations meet criteria you define. | +| Benchmarks | How different configurations perform on the same tasks. | +| Self-improvement | Which repeated failures get investigated and turned into follow-up work. | + +## Read metrics on the Dashboard page + +The **Dashboard** page shows activity, cost, autonomy, and evaluation results: + +| Metric | What it shows | +| --- | --- | +| **Total runs** | All agent runs, with breakdowns by agent type, status, source, model, and more. | +| **PRs opened** | Pull requests created from factory work. | +| **PRs merged** | Pull requests that merged. | +| **Autonomy** | The share of the factory's merged PRs that needed no human input beyond an approving review and the merge itself. | +| **PR cycle time** | The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with a median for each stage. | +| **Cost per PR** | An estimate of credits spent per pull request. | +| **Most expensive PRs** | The highest-cost pull requests. | +| **Scorer cards** | Results from your Scorers. | +| **Self-improvement PRs** | The three newest Self-improvement pull requests, regardless of the selected date range. | + +**Cost per PR** is an estimate, not a billing figure: it counts recorded credits and can undercount actual usage. + +:::caution +**PRs merged**, **Autonomy**, **PR cycle time**, and the detail in **Most expensive PRs** require the GitHub App and only cover activity from after you install it. +::: + +Use the **Dashboard** page to pick which runs to investigate, not to conclude what caused a change. **Total runs** includes evaluation, benchmark, and Self-improvement runs, so a higher run count with a flat PR count could mean harder tasks, retries, or measurement activity. + +## Configure Scorers + +A **Scorer** uses an LLM judge to classify completed conversations against criteria you write, such as "did the agent run the tests before opening a PR?" Scorers classify conversations rather than grading them on a numeric scale. Keep each Scorer focused on one question so its failures point to a specific fix. + +Configure these fields: + +* **Agent(s) to evaluate** - The agents this Scorer applies to. Select at least one. +* **Judge instructions** - The criteria the judge checks for. +* **Judge model** - The model that acts as the judge. +* **Classifications** - The labels the judge can assign, each with a score. +* **Pass threshold** - The score a conversation needs to pass. +* **Sample rate** - The share of the selected agents' completed conversations to evaluate. + +While the sample rate is above 0, scoring runs automatically: shortly after a sampled conversation completes, the judge evaluates it and records a classification, a score, and its reasoning. To stop automatic scoring, set the sample rate to 0. + +You can also score any single conversation on demand, which is useful for testing new judge instructions before raising the sample rate. Scoring a conversation again replaces its previous result from that Scorer. + +Changing **Pass threshold** updates how past scores display as pass or fail; the recorded results don't change. + +## Compare configurations with benchmarks + +A benchmark compares configurations of a single agent on the same fixed tasks, so you can test a model, harness, or runner change before adopting it. A benchmark suite includes: + +* **Agent** - The agent whose configurations you compare. +* **Tasks** - Fixed prompts with success criteria. +* **Configurations** - The harness, model, and runner combinations to test. +* **Scorers** - Your classification Scorers, applied to every trial. +* **Repetitions** - The number of trials per task and configuration. + +You can create a benchmark task from a completed run's detail pane, and Warp copies the run's input into the task. Add success criteria before you launch. + +Every benchmark also runs **Correctness**, a built-in Scorer that marks each trial as pass or fail against the task's success criteria. Results show pass rates, cost, and quality for each configuration, with per-task detail. Warp doesn't combine these signals into one score or pick a winner; you weigh the results and decide. Benchmark credit totals don't include model usage, so the true cost is higher. + +## Configure and review Self-improvement + +Turn on **Self-improvement** for each Scorer whose failures you want investigated automatically. Self-improvement groups related failures and files follow-up tasks as ordinary agent runs. A follow-up run can propose changes to application code. It can also improve the factory itself: when you manage your factory as [definitions as code](/factories/factory-as-code/), its prompts, skills, and configuration are version-controlled files, so a follow-up run can open a pull request against the factory definition the same way it would against application code. Nothing is adopted without your review. + +Each Self-improvement pull request includes a **Regressions addressed** section that links the failing runs and Scorer results behind it, so you can trace the change back to its evidence. + +## Run a practical improvement loop + +Change one measurable thing at a time: + +```mermaid +flowchart LR + Define[Define a Scorer] --> Baseline[Collect a baseline] + Baseline --> Inspect[Inspect failures] + Inspect --> Benchmark[Benchmark a candidate] + Benchmark --> Adopt[Review and adopt] + Adopt --> Monitor[Keep monitoring] + Monitor --> Inspect + Inspect -.->|Repeated failures| Improve[Self-improvement] + Improve -.-> Adopt +``` + +1. **Define a Scorer.** Pick one agent and one failure mode you can observe. Write the judge instructions and classifications, then score a few conversations manually and compare the judge's results against your own review. +2. **Collect a baseline.** Let automatic scoring run until results reflect normal work. Record the Scorer settings, date range, and relevant costs. +3. **Inspect failures.** Read the judge's reasoning and the underlying conversations. Look for causes like missing context, unclear instructions, or missing tools. Turn on Self-improvement when the same failure keeps repeating. +4. **Benchmark a candidate.** Compare configurations of that agent on the same tasks, with enough repetitions to trust the difference. +5. **Review and adopt.** If the evidence supports the change, make it. Review Self-improvement pull requests with the same standards as human-authored ones. +6. **Keep monitoring.** Leave the Scorer active and compare new results against your baseline. Revise the Scorer, or set its sample rate to 0, when its criteria no longer match what your team needs. + +## Next step + +Record an adopted change in [factory definitions as code](/factories/factory-as-code/) so your team can review the factory configuration. diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx new file mode 100644 index 000000000..9220124fa --- /dev/null +++ b/src/content/docs/factories/quickstart.mdx @@ -0,0 +1,99 @@ +--- +title: Warp Factories quickstart +description: >- + Set up a factory, connect your repositories, and take your first work item + from prompt to pull request in about 10 minutes. +sidebar: + label: "Quickstart" +--- +import { VARS } from '@data/vars'; + +A factory is a team of cloud agents that turns your team's requests into pull requests. You talk to one agent, the **foreman**, from whichever tool the request starts in, such as Slack, an issue tracker, or a code host. The foreman dispatches the factory's other agents, each owning one part of the software development lifecycle. People stay in the loop at the points that matter: approving specs when needed and merging pull requests. + +In this quickstart, you will create a factory and take one small work item from prompt to pull request in about 10 minutes. + +## What you'll decide + +Warp walks you through factory setup; your job is to decide four things: + +* **Which code the factory works on** - The code host and the set of repositories. +* **What it's called** - The factory's name, and the alias your team @-mentions to reach it. +* **Which agents it runs** - The agents the foreman can dispatch. +* **Where work comes from** - Optionally, a chat tool and an issue tracker. + +Every one of these is editable afterward, so pick something reasonable and keep moving. + +## Prerequisites + +* **Warp Factories access** - Warp Factories is in Early Access. [Request access](https://www.warp.dev/factories/request-access) if your team doesn't have it yet. +* **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. + +## Set up your factory + +_~5 minutes_ + +Sign in to the {VARS.FACTORY_WEB_APP} at platform.warp.dev and start a new factory. Setup asks you for the following. + +You can also skip the wizard: ask an agent connected to the [Factory MCP](/factories/factory-mcp/) to create the factory with its `create_factory` tool, giving it the team, the repositories, and a name. That covers the first two steps below; choose the agents and connect your tools afterward in the factory's dashboard. + +### Connect a code host and choose repositories + +Authorize GitHub or GitLab, then select the repositories the factory works in. + +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. + +### Name your factory + +Name the factory, and give it an [alias](/factories/factory-as-code/#alias): the handle your team @-mentions to reach it from connected tools like Slack and Linear, so keep it short and recognizable. In setup, the alias is the **Foreman name** field, and Warp derives it from the factory name if you don't set one. + +### Design your factory + +Every factory has a **foreman**: the one agent you talk to, no matter where the request starts. Around it, the factory is composed of four default agents, one for each part of the software development lifecycle, and this step is where you choose which of them your factory runs: + +| Agent | What it does | +| --- | --- | +| **Triage** | Accepts work from issue trackers and establishes scope | +| **Spec** | Iterates with your team to produce a spec | +| **Code** | Implements the change and opens the pull request | +| **Review** | Inspects the result and reports findings | + +All four start enabled and a factory needs at least one, so this step is about turning off what you don't want yet. Leave **Code** on so this quickstart can end in a pull request. You can add your own agents and automations later. + +See [factory agents](/factories/factory-agents/) for what each agent does in depth; the **Code** toggle is that page's Implement agent. + +### Optionally connect Slack and an issue tracker + +Setup offers to connect a chat tool and an issue tracker, so teammates can hand work to the factory from where they already work. Skip both if you want to finish quickly; [connect your factory](/factories/connect-your-factory/) covers adding them later. + +Warp then creates the factory and opens its [dashboard](/factories/factory-dashboard/). + +## Send your first work item + +_~5 minutes_ + +Send the request from the tool your team already works in. 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. + +1. Describe one small, verifiable change and send it: + + ```text title="Example first request" + Add a "Local development" section to README.md that summarizes the setup + steps from CONTRIBUTING.md. Keep the change to that one file, run the + 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. + +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 details in the factory's [dashboard](/factories/factory-dashboard/): + + * **Runs** - The foreman's run and the child runs it dispatches. + * **Activity** - The work item as it moves through its stages. Open it for the event history and pull request artifacts. + +3. When the Code 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. + +## 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. +* [**Troubleshooting**](/factories/troubleshooting/) - Fixes for common issues during setup and your first runs. diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx new file mode 100644 index 000000000..634d83d47 --- /dev/null +++ b/src/content/docs/factories/troubleshooting.mdx @@ -0,0 +1,94 @@ +--- +title: Troubleshooting Warp Factories +description: >- + Fix factory setup problems, events that don't start work, and runs that + stall or need stopping. +sidebar: + label: "Troubleshooting" +--- +import { VARS } from '@data/vars'; + +This page covers the problems teams hit most often when setting up a factory and running their first work through it. Each entry names the symptom you'd see in the {VARS.FACTORY_WEB_APP}. + +## Setting up a factory + +### You don't have access to Warp Factories + +**Cause:** Warp Factories is in Early Access and enabled per team. + +**Fix:** [Request access](https://www.warp.dev/factories/request-access) for your team. If a teammate already has it, ask a team admin to confirm you're on that team. + +### A repository doesn't appear in the picker + +**Cause:** The code host connection doesn't cover the repository. + +**Fix:** + +1. Confirm the connection includes the repository and the intended organization or group. See the [GitHub](/factories/integrations/github/) and [GitLab](/factories/integrations/gitlab/) integration guides for how each connection is scoped. +2. If you can't update it yourself, ask a GitHub organization owner, a GitLab group owner, or a Warp team admin to extend the connection. + +### Setup stops at an agent limit + +**Cause:** Your team's plan limits how many factory agents it can run. + +**Fix:** + +1. Ask a team admin to confirm the team's capacity. +2. If the team needs more agents, [contact sales](https://www.warp.dev/contact-sales). + +## Work isn't starting + +### An event that should start work doesn't + +**Cause:** Nearly always an automation that doesn't match the event, rather than a broken connection. + +**Fix:** + +1. Confirm the automation is enabled and its trigger's event type matches what happened. +2. Check every filter on the trigger. Filters combine with AND, so a single mismatched repository, label, author, or state stops the routing. See [automation filters](/factories/automation-filters/#troubleshooting). +3. Confirm the source is connected to *this* factory. Connecting a provider to your workspace doesn't attach it to every factory in that workspace. + +Then check the causes specific to where the work came from: + +| Source | Common causes | +| --- | --- | +| [Slack](/factories/integrations/slack/#troubleshooting-and-reconnection) | The app isn't in the channel, installation is pending admin approval, or your Slack account isn't linked to a Warp team member | +| [GitHub](/factories/integrations/github/#troubleshooting) | The app installation doesn't cover the repository, or the factory's routing label is missing | +| [GitLab](/factories/integrations/gitlab/#troubleshooting) | The mention was an edit rather than a new comment, or your plan doesn't include the group webhooks that deliver events | +| [Linear](/factories/integrations/linear/#troubleshooting) | The agent session needs a linked Warp account, or teams and filters don't match | +| [Jira](/factories/integrations/jira/#troubleshooting) | The Warp app isn't connected to your workspace, or project and keyword filters don't match | + +### One action starts two runs + +**Cause:** Two automations match the same event — commonly an app-mention trigger and a channel-message trigger pointed at the same place. + +**Fix:** Narrow or remove one of the overlapping triggers so a single path owns each kind of request. See [how matching works](/factories/automation-filters/#how-matching-works). + +## Runs and work items + +### You need to stop a run + +**Fix:** Open **Activity** in your factory's [dashboard](/factories/factory-dashboard/), select the work item, and click **Stop task**. It takes effect immediately, with no confirmation prompt. + +### A work item looks stuck + +**Cause:** The factory is often waiting on a person rather than failing. By default it pauses for spec approval, for answers to clarifying questions, and at the pull request. + +**Fix:** + +1. Open the work item on **Activity** and read its event history to see which agent ran last. +2. Use **View agent** to open that agent's session, where a question waiting on a human is visible and answerable. +3. If the run is still active, you can steer it directly. See [cloud agent session sharing](/platform/viewing-cloud-agent-runs/). + +### No pull request appears + +**Cause:** The factory can't push, or the work never reached implementation. + +**Fix:** Confirm that the **Code** agent is enabled on the factory, that the code host connection still grants write access to the target repository, and that the work item actually reached the implementation stage. Branch protection rules apply to everything the factory pushes. + +## Related pages + +* [**Warp Factories quickstart**](/factories/quickstart/) - Create a factory and submit your first work item. +* [**Connect your factory**](/factories/connect-your-factory/) - Route work in from Slack threads, Linear issues, and other intake paths. +* [**Automation filters**](/factories/automation-filters/) - The matching rules that decide which events start work. +* [**Factory dashboard**](/factories/factory-dashboard/) - Where to watch work items, runs, and their outputs. diff --git a/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx b/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx index 1a77b6f79..874c72340 100644 --- a/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx +++ b/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx @@ -5,6 +5,7 @@ description: >- notifications — or switch from Claude Code to Warp's Agent Mode as your primary coding agent. --- +import { VARS } from '@data/vars'; Claude Code is different from the other sources in this section: it's not a terminal emulator, it's a CLI agent that runs inside any terminal. Warp is an agentic development environment with a built-in [code editor](/code/code-editor/), [Code Review](/code/code-review/), [team collaboration](/knowledge-and-collaboration/warp-drive/), and [MCP](/agents/capabilities/mcp/) support — so you have two paths to choose from: @@ -75,7 +76,7 @@ Warp's Agent also pulls context from several other explicit sources: * **Tight terminal integration.** Agent Mode runs inside Warp and sees the full state of your terminal session — open files, command history, environment variables — without needing you to paste context. * **Parallel agents.** Warp runs multiple agent conversations across tabs simultaneously, each with its own state, which you can track in the Agent Management Panel. * **Code Review built in.** Agent-generated diffs open in Warp's [Code Review](/code/code-review/) panel, not the terminal. -* **Cloud orchestration.** Long-running or scheduled agent work can be offloaded to [Oz](/platform/). +* **Cloud orchestration.** Long-running or scheduled agent work can be offloaded to the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/). ## Warp-native equivalents diff --git a/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx index 9f84609a5..b8cfe8284 100644 --- a/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx +++ b/src/content/docs/guides/agent-workflows/build-a-self-improving-agent.mdx @@ -11,6 +11,7 @@ tags: - "cloud-agents" - "schedules" --- +import { VARS } from '@data/vars'; A self-improving agent is the outer loop of the [software factory](/guides/agent-workflows/set-up-a-software-factory) you've built in the previous guides. It watches how maintainers correct the inner-loop agents — relabeled issues, edited comments, changed code — and opens a pull request to improve the skill files that drive those agents. Every correction from a teammate becomes a proposed improvement to the factory. @@ -24,7 +25,7 @@ The outer loop proposes improvements; it doesn't apply them silently. Every chan * A working inner loop with at least one agent running ([set up your software factory](/guides/agent-workflows/set-up-a-software-factory)) * A Warp account ([sign up at warp.dev](https://www.warp.dev)) -* An Oz cloud environment with access to your repository ([create one](/platform/environments)) +* A cloud environment with access to your repository ([create one](/platform/environments)) ## Why principles beat rules @@ -83,7 +84,7 @@ The [`update-triage`](https://github.com/warpdotdev/oz-for-oss/blob/main/.agents Weekly is a good starting cadence: it processes the previous week's corrections and opens PRs for review at the start of the week. -1. Create a scheduled cloud agent from the Oz CLI: +1. Create a scheduled cloud agent from the {VARS.WARP_AGENT_CLI}: ```bash oz schedule create \ @@ -93,9 +94,9 @@ Weekly is a good starting cadence: it processes the previous week's corrections --cron "0 9 * * 1" ``` - Or, from the Oz web app: open **Agents** > **Schedules**, click **New schedule**, and set the skill, environment, and cron expression. + Or, from the {VARS.WEB_APP}: open **Agents** > **Schedules**, click **New schedule**, and set the skill, environment, and cron expression. -2. Replace `YOUR_ENVIRONMENT_SLUG` with the slug of your Oz environment. +2. Replace `YOUR_ENVIRONMENT_SLUG` with the slug of your {VARS.WARP_AUTOMATION_PLATFORM} environment. See [Scheduled agents](/platform/triggers/scheduled-agents) for the full reference. @@ -119,9 +120,9 @@ Over time, the companion skill accumulates a clear description of how your team ## Next steps -* [What is a software factory?](/platform/software-factory) — How the outer improvement loop fits into the full factory model. +* [Self-improvement in Warp Factories](/factories/measure-and-improve/#configure-and-review-self-improvement) — The managed version of this outer loop, run inside a factory. * [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) — The inner loop the outer loop improves. -* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop to Oz for team-wide visibility. +* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop to the {VARS.WARP_AUTOMATION_PLATFORM} for team-wide visibility. * [Scheduled agents](/platform/triggers/scheduled-agents) — Full reference for running cloud agents on a cadence. * [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation including all outer-loop skills. -* [Skills](/agents/capabilities/skills) — How skill files work in Warp and Oz. +* [Skills](/agents/capabilities/skills) — How skill files work in Warp and the {VARS.WARP_AUTOMATION_PLATFORM}. 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 0e768b31d..49520840f 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 @@ -9,15 +9,16 @@ tags: - "cloud-agents" - "software-factory" --- +import { VARS } from '@data/vars'; -Learn how to use Oz to build a triage agent that reviews each new GitHub issue for clarity, applies labels, and flags open questions before implementation begins. After completing the steps in this guide, you will have a working triage skill deployed as a GitHub Action. This is the first agent in your [software factory](/platform/software-factory). +Learn how to use the {VARS.WARP_AUTOMATION_PLATFORM} to build a triage agent that reviews each new GitHub issue for clarity, applies labels, and flags open questions before implementation begins. After completing the steps in this guide, you will have a working triage skill deployed as a GitHub Action. This is the first agent in your [software factory](/factories/). ## Prerequisites * A Warp account ([sign up at warp.dev](https://www.warp.dev)) * A GitHub repository with Issues enabled -* An Oz cloud environment with access to your repository ([create one](/platform/environments#create-an-environment-with-guided-setup-recommended)) -* A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/reference/cli/api-keys#from-the-oz-web-app-recommended)) +* A cloud environment with access to your repository ([create one](/platform/environments#create-an-environment-with-guided-setup-recommended)) +* A Warp API key added to your CI secrets as `WARP_API_KEY` ([create one](/reference/cli/api-keys#from-the-web-app-recommended)) ## 1. Define your triage criteria @@ -59,7 +60,7 @@ The [`bootstrap-issue-config`](https://github.com/warpdotdev/oz-for-oss/blob/mai ## 3. Test the triage agent locally -Before deploying to GitHub Actions, test the triage agent against a real issue using the Oz CLI: +Before deploying to GitHub Actions, test the triage agent against a real issue using the {VARS.WARP_AGENT_CLI}: ```bash oz agent run \ @@ -70,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 [Oz CLI reference](/reference/cli/). +For the full reference of `oz agent run` flags, see the [{VARS.WARP_AGENT_CLI} reference](/reference/cli/). ## 4. Deploy with GitHub Actions @@ -106,7 +107,7 @@ jobs: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` -2. Replace `YOUR_OZ_ENVIRONMENT_SLUG` with the slug of the Oz environment you created in the prerequisites. +2. Replace `YOUR_OZ_ENVIRONMENT_SLUG` with the slug of the {VARS.WARP_AUTOMATION_PLATFORM} environment you created in the prerequisites. 3. Add `WARP_API_KEY` to your repository's GitHub Actions secrets under **Settings** > **Secrets and variables** > **Actions**. @@ -114,13 +115,13 @@ See [GitHub Actions integration](/platform/integrations/github-actions) for the ## 5. Review and improve -Watch the first few runs in the [Oz web app](https://oz.warp.dev) to verify the agent is labeling and commenting correctly. When you disagree with the agent, e.g., when you relabel an issue or edit a comment, note the pattern. Patterns you see repeatedly are signals to update your skill file. +Watch the first few runs in the {VARS.WEB_APP} to verify the agent is labeling and commenting correctly. When you disagree with the agent, e.g., when you relabel an issue or edit a comment, note the pattern. Patterns you see repeatedly are signals to update your skill file. Add repo-specific context without forking the core skill by creating a `triage-issue-local` companion skill. This file specializes the base skill for your repository (your label taxonomy, ownership map, and definition of readiness) while keeping the shared skill stable. See the [docs repo example](https://github.com/warpdotdev/docs/blob/main/.agents/skills/triage-issue-local/SKILL.md) for the companion skill pattern. ## Next steps -* [What is a software factory?](/platform/software-factory) — How the triage agent fits into the full development loop. +* [Warp Factories overview](/factories/) — The managed product where a triage role like this scopes every incoming work item. * [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Add the spec role once your backlog is well-triaged. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Automate skill improvement based on your corrections. * [GitHub Actions integration](/platform/integrations/github-actions) — Full documentation for `warpdotdev/oz-agent-action`. diff --git a/src/content/docs/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs.mdx b/src/content/docs/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs.mdx index c0ce86c12..519b57dad 100644 --- a/src/content/docs/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs.mdx +++ b/src/content/docs/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs.mdx @@ -10,6 +10,7 @@ tags: - "code-review" - "session-sharing" --- +import { VARS } from '@data/vars'; When an agent helps prepare a pull request, reviewers need the execution context behind the diff: the original prompt, plan, commands, validation results, code changes, and decisions that still need human review. @@ -18,7 +19,7 @@ Add a Warp session or cloud agent run link to the PR description or a PR comment Use these Warp docs and surfaces to collect the right context: * [Agent Session Sharing](/agents/local-agents/session-sharing/) for local Warp agents or third-party CLI agents running in Warp. -* [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) for cloud agent runs started from Slack, Linear, GitHub Actions, schedules, the Oz CLI, or the API. +* [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) for cloud agent runs started from Slack, Linear, GitHub Actions, schedules, the {VARS.WARP_AGENT_CLI}, or the API. * The [Code Review panel](/code/code-review/) and [Interactive Code Review](/agents/local-agents/interactive-code-review/) to inspect and refine the actual code diff before or after you share the PR. ## What to include in the PR @@ -71,7 +72,7 @@ See [Agent Session Sharing](/agents/local-agents/session-sharing/) for the full If the agent ran in the cloud, use the cloud run session link: -1. Open the run from the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app or the [Runs page in the Oz web app](/platform/oz-web-app/#runs). +1. Open the run 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). 2. Confirm the session shows the run context reviewers need. 3. Copy the cloud agent session link. 4. Paste the link into the PR description or a PR comment. @@ -101,7 +102,7 @@ Reviewers should not have to read an entire transcript to understand what happen * Any failed commands and how they were resolved. * Any assumptions the agent made. -If the PR came from an automated workflow, include the trigger source too. For example: Slack thread, Linear issue, GitHub Actions workflow, scheduled agent, Oz CLI command, or API call. +If the PR came from an automated workflow, include the trigger source too. For example: Slack thread, Linear issue, GitHub Actions workflow, scheduled agent, {VARS.WARP_AGENT_CLI} command, or API call. ## 4. Watch for sensitive context before sharing 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 c02d63e18..a7a3ff042 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 @@ -11,12 +11,13 @@ tags: --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; Use multiple coding agents, including Warp Agent, Claude Code, Codex, and other CLI agents, when work can be split into independent tasks, reviewed from separate branches, or delegated to cloud agents while you keep working locally. In Warp, you can coordinate agents in three ways: * **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. -* **Oz cloud orchestration** - use `/orchestrate`, `/plan`, the Oz CLI, the Oz web app, or the Oz API 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.API_SDK_NAME} 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. @@ -35,7 +36,7 @@ Plan on about 15 minutes for the local setup. Cloud orchestration takes longer o | Split by file or subsystem | A feature spans independent modules that can be changed in parallel. | Assign each agent a worktree, branch, file boundary, and validation command. | | Builder plus reviewer | One agent implements while another reviews, writes tests, or checks edge cases. | Put the reviewer in a read-only or review-focused tab, or use a separate branch for test-only changes. | | Cloud fan-out | The work is large, slow, or can run away from your laptop. | Use [Multi-agent orchestration](/platform/orchestration/) or [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) to spawn cloud children. | -| Repeatable fleet workflow | You want the same agent pattern on every PR, issue, schedule, or release. | Use a cloud agent with a trigger, skill, or API workflow, then inspect parent and child runs in the [Oz web app](/platform/oz-web-app/). | +| Repeatable fleet workflow | You want the same agent pattern on every PR, issue, schedule, or release. | Use a cloud agent with a trigger, skill, or API workflow, then inspect parent and child runs in the [{VARS.WEB_APP}](/platform/oz-web-app/). | ## Plan the split before launching agents @@ -216,8 +217,8 @@ 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 Oz CLI, the Oz web app, or the Oz API. See [Running orchestrated agents](/platform/orchestration/multi-agent-runs/) for launch options. -4. Inspect parent and child runs from the [Oz web app](/platform/oz-web-app/) or the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app. +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. +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: @@ -254,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 Oz CLI, the Oz web app, or the Oz API +* [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} * [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 5d5b35ee8..0b77b3580 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 @@ -2,7 +2,7 @@ title: How to run unattended agents description: >- Start unattended cloud agents from schedules, Slack, Linear, GitHub, GitHub - Actions, the Oz CLI, or the Oz API, then inspect every run. + Actions, the {{WARP_AGENT_CLI}}, or the {{WARP_AUTOMATION_PLATFORM}} API, then inspect every run. sidebar: label: "Run unattended agents" featured: true @@ -11,10 +11,11 @@ tags: - "cloud-agents" - "schedules" --- +import { VARS } from '@data/vars'; -Warp cloud agents can run unattended from schedules, team tools, CI, the Oz CLI, or the API. Use them when you want an agent to keep working after you leave your terminal, react to external events, or run recurring maintenance without a human starting each run. +Warp cloud agents can run unattended from schedules, team tools, CI, the {VARS.WARP_AGENT_CLI}, or the API. Use them when you want an agent to keep working after you leave your terminal, react to external events, or run recurring maintenance without a human starting each run. -Every unattended workflow creates a cloud agent run that your team can inspect later. Open runs from the [Runs page in the Oz web app](/platform/oz-web-app/#runs), the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app, or the session link posted back to the tool that triggered the agent. +Every unattended workflow creates a cloud agent run that your team can inspect later. Open runs from the [Runs page in the {VARS.WEB_APP}](/platform/oz-web-app/#runs), the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app, or the session link posted back to the tool that triggered the agent. ## Choose a trigger @@ -22,13 +23,13 @@ Use this table to decide where an unattended agent should start. | Trigger | Use it when | Where to configure | Where to inspect | | ------- | ----------- | ------------------ | ---------------- | -| Scheduled agents | Work should run on a predictable cadence, like weekly triage, nightly dependency checks, or monthly cleanup. | [Scheduled Agents](/platform/triggers/scheduled-agents/) or the [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/) | Oz web app Runs page, Agent Management Panel in the Warp app, schedule history, and cloud agent session links | -| Slack | A teammate should delegate work from a Slack message or thread. | [Slack integration](/platform/integrations/slack/) | Slack thread updates, Oz web app Runs page, Agent Management Panel in the Warp app, and the shared run session | -| Linear | An issue, comment, or assignment should start the agent. | [Linear integration](/platform/integrations/linear/) | Linear issue updates, Oz web app Runs page, Agent Management Panel in the Warp app, and the shared run session | -| GitHub | Someone should delegate work by mentioning `@oz-agent` on an issue, pull request, or review comment. | [GitHub integration](/platform/integrations/github/) | GitHub thread comments, Oz 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, Oz web app, and cloud agent runs | -| Oz CLI | You want to start a named cloud run from a terminal, script, or local automation. | [Oz CLI](/reference/cli/#running-agents-remotely-oz-agent-run-cloud) | CLI output, Oz web app Runs page, Agent Management Panel in the Warp app, and cloud agent session links | -| Oz API or SDK | Your internal system should create, query, or monitor runs programmatically. | [Oz API and SDK](/reference/api-and-sdk/) | Your system, API results, Oz web app, and run sessions | +| Scheduled agents | Work should run on a predictable cadence, like weekly triage, nightly dependency checks, or monthly cleanup. | [Scheduled Agents](/platform/triggers/scheduled-agents/) or the [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/) | {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, schedule history, and cloud agent session links | +| Slack | A teammate should delegate work from a Slack message or thread. | [Slack integration](/platform/integrations/slack/) | Slack thread updates, {VARS.WEB_APP} Runs page, Agent Management Panel in the Warp app, and the shared run session | +| 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 | ## Choose a workflow pattern @@ -57,7 +58,7 @@ The agent posts progress updates back to the source thread or issue and provides ### Delegate work from a GitHub thread -Use the [GitHub integration](/platform/integrations/github/) when the task starts from an issue, a pull request, or a review comment. Mention `@oz-agent` in the thread and the agent picks up that context, replies in place, and reports any pull request it opens. This fits: +Use the [GitHub integration](/platform/integrations/github/) when the task starts from an issue, a pull request, or a review comment. Mention `@warp-agent` in the thread and the agent picks up that context, replies in place, and reports any pull request it opens. This fits: * asking for a fix from a review comment without leaving the diff * turning a bug report issue into a pull request @@ -72,7 +73,7 @@ Use [GitHub Actions](/platform/integrations/github-actions/) when the trigger sh For example: * review a PR when it opens -* respond to an `@oz-agent` comment +* respond to an `@warp-agent` comment * summarize issues on a schedule * attempt a fix when CI fails * suggest fixes for review comments @@ -81,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 [Oz CLI](/reference/cli/#running-agents-remotely-oz-agent-run-cloud) for scripts and terminal workflows. Use the [Oz API and SDK](/reference/api-and-sdk/) when another service should create or monitor runs. This is useful for: +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: * internal dashboards * custom webhooks @@ -108,10 +109,10 @@ If the agent can change code or infrastructure, keep the instructions narrow and Unattended does not mean invisible. Use these surfaces to review what happened: -* [Oz web app](/platform/oz-web-app/) - View runs, schedules, run metadata, and session transcripts from a browser or mobile device. +* [{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. -* [Oz API and SDK](/reference/api-and-sdk/) - Query runs and build internal monitoring around status, runtime, or outcomes. +* [{VARS.API_SDK_NAME}](/reference/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. @@ -129,8 +130,8 @@ Start with one narrow workflow before deploying many unattended agents: ## Next steps -* [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/) - Create your first recurring agent in the Oz web app. +* [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/) - Create your first recurring agent in the {VARS.WEB_APP}. * [Integrations quickstart](/platform/integrations/quickstart/) - Trigger agents from Slack or Linear. -* [GitHub integration](/platform/integrations/github/) - Set up `@oz-agent` mentions on issues and pull requests. +* [GitHub integration](/platform/integrations/github/) - Set up `@warp-agent` mentions on issues and pull requests. * [GitHub Actions quickstart](/platform/integrations/quickstart-github-actions/) - Add an agent to a PR review workflow. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Inspect and share unattended run sessions. 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 dd11c370d..9d6a8bb3e 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 @@ -1,7 +1,7 @@ --- title: Run a software factory in the cloud description: >- - Set up the Oz-native production path for your software factory with cloud + Set up the {{WARP_AUTOMATION_PLATFORM}}-native production path for your software factory with cloud environments, secrets, triggers, and audit trails. sidebar: label: "Run a software factory in the cloud" @@ -11,8 +11,9 @@ tags: - "software-factory" - "orchestration" --- +import { VARS } from '@data/vars'; -The GitHub Actions approach in [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) gets the four-agent loop working. This guide covers the Oz-native production setup for teams running the factory at scale: cloud environments, secrets and permissions, triggers, and observability. +The GitHub Actions approach in [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) gets the four-agent loop working. This guide covers the {VARS.WARP_AUTOMATION_PLATFORM}-native production setup for teams running the factory at scale: cloud environments, secrets and permissions, triggers, and observability. To run the same loop as a managed product instead, see [Warp Factories](/factories/). ## Prerequisites @@ -21,20 +22,20 @@ The GitHub Actions approach in [Set up your software factory](/guides/agent-work ## Why cloud agents, not cloud computers -A common approach to cloud-based agents is to spin up a persistent virtual machine, or "cloud computer", that the agent logs into and uses like a developer's laptop. Oz uses a different model where each agent run is a short-lived, scoped execution with its own environment and permissions, similar to a cloud function rather than a long-running server. +A common approach to cloud-based agents is to spin up a persistent virtual machine, or "cloud computer", that the agent logs into and uses like a developer's laptop. The {VARS.WARP_AUTOMATION_PLATFORM} uses a different model where each agent run is a short-lived, scoped execution with its own environment and permissions, similar to a cloud function rather than a long-running server. The practical difference: * **Per-agent permissions** — Your triage agent only needs to read issues and post comments. Your implementation agent needs to push branches and open PRs. Each agent gets exactly the permissions it needs, not a single shared credential that everything uses. * **Audit trails** — Every cloud agent run is logged separately. You can see exactly what the triage agent did versus what the implementation agent did, when it ran, and what it produced. -* **Team visibility** — Any teammate can open a run in the Oz web app to inspect the session transcript, steer a stuck agent, or pick up where the agent left off. +* **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 Oz-hosted, CLI-based, and self-hosted execution patterns. +See [Deployment patterns](/platform/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 -An Oz environment is a Docker-based sandbox with your repository, secrets, and any tools the agents need. If you don't already have one from the previous guides, create one now: run [`/create-environment`](warp://action/create_environment) in Warp and Oz detects your stack, suggests a Docker image, and creates the environment automatically. +A cloud environment is a Docker-based sandbox with your repository, secrets, and any tools the agents need. If you don't already have one from the previous guides, create one now: run [`/create-environment`](warp://action/create_environment) in Warp and the {VARS.WARP_AUTOMATION_PLATFORM} detects your stack, suggests a Docker image, and creates the environment automatically. For repositories that need specific toolchains or dependencies, [`warpdotdev/oz-dev-environments`](https://github.com/warpdotdev/oz-dev-environments) has prebuilt Docker images for common stacks. @@ -61,41 +62,41 @@ Use fine-grained personal access tokens or separate GitHub App installations to ## 3. Configure triggers -With GitHub Actions, your factory already has event-based triggers. Oz also provides first-party integrations that handle triggering without GitHub Actions boilerplate: +With GitHub Actions, your factory already has event-based triggers. The {VARS.WARP_AUTOMATION_PLATFORM} also provides first-party integrations that handle triggering without GitHub Actions boilerplate: * **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). -* **Oz API and SDK** — For custom triggers — webhooks, internal dashboards, other events — use the [Oz API and SDK](/reference/api-and-sdk) to start runs programmatically. +* **{VARS.API_SDK_NAME}** — For custom triggers — webhooks, internal dashboards, other events — use the [{VARS.API_SDK_NAME}](/reference/api-and-sdk) to start runs programmatically. ## 4. Monitor factory runs -Every cloud agent run in your factory appears in the Oz dashboard with: +Every cloud agent run in your factory appears in the {VARS.DASHBOARD} with: * A session transcript showing every action the agent took * Artifacts: PRs, branches, plans, and reports the agent produced * Status history: queued, in progress, succeeded, or failed with error details * A session sharing link any teammate can open to inspect or steer the run -Open runs from [oz.warp.dev](https://oz.warp.dev) or from the **Agent Management Panel** in the Warp app. Include the session link in PR descriptions so reviewers can see exactly how the agent built the change — see [Attach agent context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs). +Open runs from {VARS.WEB_APP_URL} or from the **Agent Management Panel** in the Warp app. Include the session link in PR descriptions so reviewers can see exactly how the agent built the change — see [Attach agent context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs). See [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs) for the full reference. ## 5. Use multi-agent orchestration for large backlogs -When a sprint starts and you want to process many issues in parallel, Oz can fan out to child agents — one per issue — from a single parent run. The parent coordinates; the children execute in parallel, each with their own environment, prompt, and permissions. +When a sprint starts and you want to process many issues in parallel, the {VARS.WARP_AUTOMATION_PLATFORM} can fan out to child agents — one per issue — from a single parent run. The parent coordinates; the children execute in parallel, each with their own environment, prompt, and permissions. See [Multi-agent orchestration](/platform/orchestration) for fan-out, sharding, and result aggregation patterns. ## Productivity tips * **Start with one agent role in the cloud** — Get the triage agent running as a cloud run before moving all four roles. Confirm that the environment, secrets, and permissions work correctly before expanding. -* **Add session links to PR descriptions** — When the implementation agent opens a PR, include the Oz run link so reviewers get the full context. See [Attach agent context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs) for a template. -* **Monitor credit usage** — Cloud agent runs consume credits. Monitor usage in the Oz web app and adjust run scope if needed. See [Credits](/support-and-community/plans-and-billing/credits). +* **Add session links to PR descriptions** — When the implementation agent opens a PR, include the {VARS.PLATFORM_RUN} link so reviewers get the full context. See [Attach agent context to GitHub PRs](/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs) for a template. +* **Monitor credit usage** — Cloud agent runs consume credits. Monitor usage in the {VARS.WEB_APP} and adjust run scope if needed. See [Credits](/support-and-community/plans-and-billing/credits). ## Next steps -* [What is a software factory?](/platform/software-factory) — The conceptual overview of the full loop. +* [Warp Factories overview](/factories/) — The managed product that runs this same loop end to end. * [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. diff --git a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx index 37e9c2844..42dd7765e 100644 --- a/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx +++ b/src/content/docs/guides/agent-workflows/set-up-a-software-factory.mdx @@ -9,13 +9,14 @@ tags: - "software-factory" - "cloud-agents" --- +import { VARS } from '@data/vars'; -This guide adds the implementation and reviewer agents to the [triage](/guides/agent-workflows/build-a-triage-agent) and [spec](/guides/agent-workflows/write-product-and-tech-specs-with-agents) agents you set up previously, then connects all four into a software factory using GitHub labels as the state machine. Issues flow automatically from triage to a reviewable pull request. +This guide adds the implementation and reviewer agents to the [triage](/guides/agent-workflows/build-a-triage-agent) and [spec](/guides/agent-workflows/write-product-and-tech-specs-with-agents) agents you set up previously, then connects all four into a software factory using GitHub labels as the state machine. Issues flow automatically from triage to a reviewable pull request. To run this same loop as a managed product instead of wiring it yourself, see [Warp Factories](/factories/). ## Prerequisites * A working [triage agent](/guides/agent-workflows/build-a-triage-agent) and [spec agent](/guides/agent-workflows/write-product-and-tech-specs-with-agents), each deployed individually -* An Oz cloud environment with access to your repository ([create one](/platform/environments)) +* A cloud environment with access to your repository ([create one](/platform/environments)) * `warpdotdev/oz-agent-action` installed (see [GitHub Actions integration](/platform/integrations/github-actions)) ## How the loop works @@ -156,13 +157,13 @@ The reviewer agent surfaces issues and inconsistencies; the human makes the fina * **Validate before the reviewer runs** — After the implementation agent opens a PR, run `/validate-changes-match-specs` to check the diff against `PRODUCT.md` and `TECH.md`. This catches any misalignments before the reviewer agent posts comments. The skill is available from [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills). * **Start with triage only** — Get your triage agent running well before adding spec and implementation. A groomed, labeled backlog is immediately useful to every developer on the team. -* **Use `@oz-agent` for one-off requests** — Teammates can mention `@oz-agent` in an issue comment to kick off an agent run directly, bypassing the label workflow for urgent requests. -* **Monitor runs in the Oz web app** — Every cloud agent run appears in the [Oz web app](https://oz.warp.dev) with a session link. Use it to inspect what each agent did, steer a stuck run, or hand work back to a local session. +* **Use `@warp-agent` for one-off requests** — Teammates can mention `@warp-agent` in an issue comment to kick off an agent run directly, bypassing the label workflow for urgent requests. +* **Monitor runs in the {VARS.WEB_APP}** — Every cloud agent run appears in the {VARS.WEB_APP} with a session link. Use it to inspect what each agent did, steer a stuck run, or hand work back to a local session. ## Next steps -* [What is a software factory?](/platform/software-factory) — The conceptual overview of the full loop. -* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop into a managed Oz deployment. +* [Warp Factories overview](/factories/) — The managed product that runs this same intake-to-review loop, without the workflow wiring. +* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop into a managed {VARS.WARP_AUTOMATION_PLATFORM} deployment. * [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. * [Review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code) — The human review workflow for agent-generated PRs. * [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) — The complete reference implementation. diff --git a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx index ed8f5e13a..ad3140496 100644 --- a/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx +++ b/src/content/docs/guides/agent-workflows/write-product-and-tech-specs-with-agents.mdx @@ -8,6 +8,7 @@ tags: - "agents" - "software-factory" --- +import { VARS } from '@data/vars'; Once your [triage agent](/guides/agent-workflows/build-a-triage-agent) is labeling issues as `ready-to-spec`, use agents to turn those issues into two spec files: a product spec that describes what the feature should do from the user's perspective, and a tech spec that describes how to implement it. @@ -71,8 +72,8 @@ A tech spec defines how the feature will be implemented, including architecture ## Next steps -* [What is a software factory?](/platform/software-factory) — How specs fit into the full development loop. +* [Warp Factories overview](/factories/) — The managed product where a spec stage gates implementation the same way. * [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) — Connect the spec role to implementation and review. * [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) — The full set of shared skills including `write-product-spec`, `write-tech-spec`, and `validate-changes-match-specs`. * [Planning](/agents/capabilities/planning) — Warp's built-in planning feature for smaller tasks. -* [Skills](/agents/capabilities/skills) — How skill files work in Warp and Oz. +* [Skills](/agents/capabilities/skills) — How skill files work in Warp and the {VARS.WARP_AUTOMATION_PLATFORM}. diff --git a/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx b/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx index f81d51a5c..75407b869 100644 --- a/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx +++ b/src/content/docs/guides/configuration/how-to-set-up-self-serve-data-analytics-with-skills.mdx @@ -10,6 +10,7 @@ tags: --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; Self-serve data analytics means anyone on your team can ask a data question and get a trustworthy answer, without pinging the data team. This guide sets up that workflow using two community Skills that chain together: one resolves vague questions to the right BigQuery tables, and the other structures deep-dive analyses into reproducible folders. Plan on about 10 minutes for initial setup, plus time to customize the model index for your warehouse. @@ -179,7 +180,7 @@ The `analysis-artifacts` Skill is largely stack-agnostic. It structures outputs, You installed two community Skills, customized the model index for your warehouse, and ran both a simple lookup and a full deep-dive analysis. -**Extend to Slack.** Wire the same two Skills into a cloud agent configured with your dbt repo, and your teammates can ask data questions by @-mentioning Oz in a Slack channel, without opening a terminal. The agent clones the repo, picks up the Skills from `.agents/skills/`, and replies in-thread. See the [Slack integration docs](https://docs.warp.dev/platform/integrations/slack/) and [Skills as Agents](https://docs.warp.dev/platform/skills-as-agents/) for setup. +**Extend to Slack.** Wire the same two Skills into a cloud agent configured with your dbt repo, and your teammates can ask data questions by tagging @warp in a Slack channel, without opening a terminal. The agent clones the repo, picks up the Skills from `.agents/skills/`, and replies in-thread. See the [Slack integration docs](https://docs.warp.dev/platform/integrations/slack/) and [Skills as Agents](https://docs.warp.dev/platform/skills-as-agents/) for setup. Explore related guides and features: 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 554c71d15..51a774f9a 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 @@ -10,6 +10,7 @@ tags: featured: true --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; @@ -18,7 +19,7 @@ MCP servers let Warp agents use external tools and data sources through a standa Warp supports MCP in two places: * **Local agents in the Warp app** use MCP servers configured in **Settings** > **Agents** > **MCP servers**, Warp Drive, or file-based config. -* **Cloud agents** use MCP servers passed through the Oz CLI, agent config files, or Warp-shared MCP server UUIDs. +* **Cloud agents** use MCP servers passed through the {VARS.WARP_AGENT_CLI}, agent config files, or Warp-shared MCP server UUIDs. Use this guide to choose the right setup path, then jump to the source docs for exact configuration syntax. @@ -56,8 +57,8 @@ Example workflow: 1. Create or identify the MCP server the cloud agent should use. 2. Store required credentials as [Agent Secrets](/platform/secrets/) instead of hardcoding tokens in config files. 3. Attach the MCP server with `--mcp`, a config file, or a Warp-shared MCP UUID. -4. Run the cloud agent from the Oz CLI, Slack, Linear, GitHub Actions, a schedule, or the API. -5. Inspect the run in the [Oz web app](/platform/oz-web-app/) or [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/). +4. Run the cloud agent from the {VARS.WARP_AGENT_CLI}, Slack, Linear, GitHub Actions, a schedule, or the API. +5. Inspect the run in the [{VARS.WEB_APP}](/platform/oz-web-app/) or [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/). For schema and cloud-specific limitations, see [MCP Servers for cloud agents](/platform/mcp/). @@ -67,7 +68,7 @@ Use shared MCP servers when multiple teammates or workflows need the same tool c For local agents, share the server from the MCP settings page. Warp scrubs sensitive environment values and prompts teammates to provide their own values when they install it. -For cloud agents, reference a Warp-shared MCP server by UUID with the Oz CLI: +For cloud agents, reference a Warp-shared MCP server by UUID with the {VARS.WARP_AGENT_CLI}: ```sh oz mcp list diff --git a/src/content/docs/guides/index.mdx b/src/content/docs/guides/index.mdx index 65b3f41fe..0ab75173f 100644 --- a/src/content/docs/guides/index.mdx +++ b/src/content/docs/guides/index.mdx @@ -10,6 +10,8 @@ import GuidesLanding from '@components/GuidesLanding.astro'; Practical, task-oriented walkthroughs that help you get productive with Warp's coding agents. Each guide walks through a real AI coding workflow with actual prompts, code, and reproducible results. +To turn a one-off workflow into a repeatable process run by a team of cloud agents, see [Warp Factories](/factories/). + :::note **New to Warp?** Start with [Welcome to Warp](/guides/getting-started/welcome-to-warp/), then explore [10 Warp Coding Features You Should Know](/guides/getting-started/10-coding-features-you-should-know/). ::: diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 7e5f2ecc1..8565714d8 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,18 +1,19 @@ --- -title: Getting started with Warp and Oz +title: Getting started with Warp description: >- - Get started with Warp, the Agentic Development Environment, and Oz, the - orchestration platform for cloud agents. + Get started with Warp, the Agentic Development Environment, and the + {{WARP_AUTOMATION_PLATFORM}}, which orchestrates cloud agents at scale. sidebar: - label: Getting started with Warp and Oz + label: Getting started with Warp --- +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 **Oz**, the orchestration platform for running agents locally or in the cloud at scale. +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.
-![Warp, the Agentic Development Environment: Warp (a modern terminal built for coding with agents) and Oz (the orchestration platform for cloud agents)](../../assets/terminal/warp-oz-welcome.png) -
Warp terminal with Oz orchestration.
+![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) +
Warp and Warp Factories in the Agentic Development Environment.
--- @@ -70,15 +71,23 @@ Cloud agents are ideal for work that doesn't need your immediate attention, like ### The platform behind them -**Oz** is Warp's programmable platform 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. +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. -→ [Learn about the Oz platform](/platform/overview/) +→ [Learn about the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) + +--- + +## 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) --- ## How they work together -Warp and Oz provide a unified experience across local and cloud development: +Warp and the {VARS.WARP_AUTOMATION_PLATFORM} provide a unified experience across local and cloud development: * **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. @@ -89,13 +98,13 @@ Warp and Oz provide a unified experience across local and cloud development: ## Multi-model support -Oz is multi-model by design. You can [choose your preferred LLM](/agents/inference/model-choice/) from a curated set of top models. +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. --- ## 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 Oz. +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. @@ -117,4 +126,4 @@ Warp's AI features can be globally disabled in **Settings** > **Agents** > **War * [**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 -* [**Oz Platform**](/platform/overview/): Learn about the CLI, API, SDK, and infrastructure +* [**{VARS.WARP_AUTOMATION_PLATFORM}**](/platform/overview/): Learn about the CLI, API, SDK, and infrastructure diff --git a/src/content/docs/platform/agents.mdx b/src/content/docs/platform/agents.mdx index 2dbad407a..e8e9c21fe 100644 --- a/src/content/docs/platform/agents.mdx +++ b/src/content/docs/platform/agents.mdx @@ -6,10 +6,11 @@ description: >- sidebar: label: "Agents" --- +import { VARS } from '@data/vars'; A **cloud agent** is an agent that runs in Warp's cloud (or on a self-hosted worker) instead of on your local machine. Use a cloud agent when you want to give an automation its own settings, secrets, skills, and permissions instead of having it act as a user on your team. -Every team starts with a default cloud agent, which is what runs when an automation triggers a task with no other configuration. You can optionally create additional cloud agents through the Oz web app's **Agents** page or the public API. See [Managing cloud agents](#managing-cloud-agents) below. +Every team starts with a default cloud agent, which is what runs when an automation triggers a task with no other configuration. You can optionally create additional cloud agents through the {VARS.WEB_APP}'s **Agents** page or the public API. See [Managing cloud agents](#managing-cloud-agents) below. ## How cloud agents get triggered @@ -17,10 +18,10 @@ A run executes as a cloud agent when it's authenticated with an [agent API key]( * **Schedules** — Cron-style recurring runs. See [Scheduled agents](/platform/triggers/scheduled-agents/). * **Integrations** — Slack mentions, Linear issue updates, GitHub Actions workflow steps. See [Integrations](/platform/integrations/). -* **API and SDK** — Programmatic runs from your own backend, scripts, or webhooks via the [Oz API](/reference/api-and-sdk/). -* **CLI** — `oz agent run-cloud` from a developer machine, CI pipeline, or self-hosted worker. See the [Oz CLI](/reference/cli/). +* **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/). -Each run is tracked in the [Oz dashboard](https://oz.warp.dev/runs) with its trigger source, the environment it ran in, and the full transcript. +Each run is tracked in the {VARS.DASHBOARD} with its trigger source, the environment it ran in, and the full transcript. ## Agent API keys @@ -32,7 +33,7 @@ In the CLI and REST API, a cloud agent is represented as a **service account**. ## Managing cloud agents -Use the [Oz web app's Agents page](/platform/oz-web-app/#agents) for day-to-day management. Use the public API when you need to create or update agents from scripts, CI/CD, or internal tooling. Full request and response formats, including error codes, live on the [API Reference](/api) page under the **agent** tag. +Use the [{VARS.WEB_APP}'s Agents page](/platform/oz-web-app/#agents) for day-to-day management. Use the public API when you need to create or update agents from scripts, CI/CD, or internal tooling. Full request and response formats, including error codes, live on the [API Reference](/api) page under the **agent** tag. | Action | Endpoint | What it does | | --- | --- | --- | @@ -56,18 +57,26 @@ When a team is over its plan limit (for example, after downgrading), the extra a ## Where cloud agents appear in the product -* **Agents page** - The Agents page in the [Oz web app](/platform/oz-web-app/) is where teams view, create, edit, and delete cloud agents. +* **Agents page** - The Agents page in the [{VARS.WEB_APP}](/platform/oz-web-app/) is where teams view, create, edit, and delete cloud agents. * **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default: runs execute as the calling user, and pull requests are authored by that person. Picking a cloud agent runs as that agent instead, so with [team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization) configured, pull requests are authored by the **Oz by Warp** GitHub App. Choose a cloud agent for any schedule that opens pull requests. See [Run identity and pull request authorship](/platform/triggers/scheduled-agents-quickstart/#run-identity-and-pull-request-authorship). * **Run filters and detail** - The Runs view lets you filter by cloud agent, and individual run detail pages show which agent executed the run. * **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by cloud agent runs to the team rather than to a person. +## Capabilities + +Cloud agents — and individual runs — can also be granted specific capabilities: + +* [**Skills as agents**](/platform/skills-as-agents/) - Attach a skill directly to a cloud agent, or pass one at run time, so the agent starts from a reusable, version-controlled prompt instead of an ad hoc one. +* [**MCP servers**](/platform/mcp/) - Connect a run to external tools and services (GitHub, dbt, Sentry, or a custom internal service) via Model Context Protocol. +* [**Secrets**](/platform/secrets/) - Store and inject credentials into cloud agent runs without exposing secret values, scoped to a team, a person, or a specific cloud agent. + ## Related pages * [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. -* [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the cloud agent endpoints. +* [{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. -* [Oz web app](/platform/oz-web-app/) - Manage cloud agents and inspect their runs in the web UI. +* [{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/deployment-patterns.mdx b/src/content/docs/platform/deployment-patterns.mdx index f8dfc36e6..8ee707406 100644 --- a/src/content/docs/platform/deployment-patterns.mdx +++ b/src/content/docs/platform/deployment-patterns.mdx @@ -2,7 +2,7 @@ title: Deployment patterns description: >- Common architectures for deploying cloud agents, including CLI-only, - Oz-hosted, and self-hosted execution patterns. + {{WARP_AUTOMATION_PLATFORM}}-hosted, and self-hosted execution patterns. sidebar: label: "Deployment patterns" --- @@ -10,110 +10,110 @@ 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. -#### Quick mental model +## 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 (Oz orchestrator, GitHub Actions, your internal system). -3. **Execution**: where the agent actually runs (your runner, Oz-hosted environment, or self-hosted workers). -4. **Visibility**: how the team monitors and intervenes (Oz dashboard, session sharing, APIs). +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) +## 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 +### 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 +### 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 +### 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 +### 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 +### Minimal setup checklist * A Warp team * A [cloud agent](/platform/agents/) (recommended for automation) -* The Oz CLI installed on the runner / box +* The {VARS.WARP_AGENT_CLI} installed on the runner / box * Any needed credentials (often via secrets + environment variables) --- -### Pattern 2: Oz-hosted agents + Oz orchestration (managed cloud execution) +## Pattern 2: Warp-hosted agents and orchestration (managed cloud execution) -Use this when you want Oz to run agent workloads on Warp-managed infrastructure, typically inside reproducible Docker environments, with built-in lifecycle management. +Use this when you want the {VARS.WARP_AUTOMATION_PLATFORM} to run agent workloads on Warp-managed infrastructure, typically inside reproducible Docker environments, with built-in lifecycle management. ![Warp enterprise SaaS architecture showing customer infrastructure, isolated tenant sandboxes, Warp backend, and LLM providers](../../../assets/agent-platform/cloud-agents-infra.png) -#### What it looks like +### What it looks like * **Trigger**: first-party integrations, cron schedules, API/SDK calls, or on-demand commands -* **Orchestration**: Oz orchestrator -* **Execution**: Oz-hosted environments (Docker-based) -* **Visibility**: Oz dashboard + session sharing + APIs/SDKs +* **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 +### 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 +### 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 +### Example recipe: daily dead-code cleanup -1. Define an Oz [Environment](/platform/environments/) with the repo + toolchain. +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. Oz runs the agent on the cadence. +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 +### Example recipe: crash triage via Sentry webhook -1. Define an Oz Environment with the target repo. +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 Oz orchestrator API/SDK to start a task. +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) +### 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 +### 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 +## Pattern 3: Self-hosted execution -Use this when you need to control where agent execution happens while still using Oz orchestration and visibility. Repositories are cloned and stored only on your infrastructure; orchestration metadata, session transcripts, and LLM inference route through Warp's backend under [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr). +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. @@ -123,7 +123,7 @@ Think of self-hosted execution as **customer-hosted execution with Warp-hosted o Self-hosting has two architectures that differ on **who orchestrates agent runs** (both keep code and execution on your infrastructure): -* **[Managed](/platform/self-hosting/#managed-architecture)** — Oz orchestrates. You run the `oz-agent-worker` daemon; Oz 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. +* **[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: diff --git a/src/content/docs/platform/environments.mdx b/src/content/docs/platform/environments.mdx index 0bd7033ac..70d0dc4ec 100644 --- a/src/content/docs/platform/environments.mdx +++ b/src/content/docs/platform/environments.mdx @@ -6,6 +6,7 @@ description: >- Environments ensure your cloud agents run with consistent toolchains across all triggers. Learn when to use environments and how to configure them. --- +import { VARS } from '@data/vars'; Environments ensure your [cloud agents](/platform/) run with the same toolchain and setup every time, regardless of where they're triggered from. @@ -29,7 +30,7 @@ Don't want to bring your own image? Warp provides [prebuilt dev images](https:// ## About environments -Environments define _how_ an agent runs, not _what_ it does. They're required for [Oz Platform](/platform/overview/) automation (cloud agents, integrations, API runs) but are not required for interactive local usage. +Environments define _how_ an agent runs, not _what_ it does. They're required for automation on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) (cloud agents, integrations, API runs) but are not required for interactive local usage. An environment typically includes: @@ -54,9 +55,9 @@ What an environment is not: * [MCP Servers](/platform/mcp/) – connect agents to external tools and data via MCP. * Per-run context – Trigger-specific data like Slack threads, PR metadata, or CI logs attach to individual tasks, not the environment configuration. -## How environments fit into the Oz Platform +## How environments fit into cloud agent runs -An environment is the runtime layer for automated Oz Platform runs. It defines the container image, repos, and setup steps used when a trigger kicks off an agent task. +An environment is the runtime layer for automated {VARS.WARP_AUTOMATION_PLATFORM} runs. It defines the container image, repos, and setup steps used when a trigger kicks off an agent task. Components in the execution flow: @@ -122,13 +123,13 @@ Choose an environment if any of the following apply: **Example:** -If your team tags @Oz in Slack to fix a failing CI job, an environment ensures every run uses the same Docker image, clones the same repos, and runs the same setup commands. +If your team tags @warp in Slack to fix a failing CI job, an environment ensures every run uses the same Docker image, clones the same repos, and runs the same setup commands. The fix the agent applies matches what runs in CI and what your teammates see when they review the PR. ### Where to configure environments -You can create environments in three ways: from the Oz web app, using the guided setup in Warp, or through the CLI. +You can create environments in three ways: from the {VARS.WEB_APP}, using the guided setup in Warp, or through the CLI. **Before you begin** @@ -146,15 +147,15 @@ Musl-based Docker images (such as Alpine Linux) are not supported. The agent run Create one environment per codebase, then reuse it across triggers like Slack, Linear, and CLI runs. ::: -### Create an environment from the Oz web app +### Create an environment from the web app
![Creating a new environment in the Oz Web App.](../../../assets/agent-platform/oz-web-app-new-environment.png)
The Create environment panel in the Oz web app.
-1. Open the [Environments page in the Oz web app](https://oz.warp.dev/environments) and click **New environment**. -2. Enter a name, select one or more repositories, and enter a **Docker image reference**. Click **Suggest** to have Oz recommend an image based on your repos, or start from one of [Warp's prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). +1. Open the Environments page in the {VARS.WEB_APP} and click **New environment**. +2. Enter a name, select one or more repositories, and enter a **Docker image reference**. Click **Suggest** to have the {VARS.WARP_AUTOMATION_PLATFORM} recommend an image based on your repos, or start from one of [Warp's prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). 3. Optionally, add setup commands, configure cloud provider access (AWS or GCP), or add a description. 4. Click **Create environment**. @@ -216,7 +217,7 @@ Key flags: ## Managing environments -Once created, you can use the [Oz CLI](/reference/cli/) to inspect and update environments. +Once created, you can use the [{VARS.WARP_AGENT_CLI}](/reference/cli/) to inspect and update environments. **List environments** diff --git a/src/content/docs/platform/handoff/cloud-to-cloud.mdx b/src/content/docs/platform/handoff/cloud-to-cloud.mdx index cad8ff257..c1b41171b 100644 --- a/src/content/docs/platform/handoff/cloud-to-cloud.mdx +++ b/src/content/docs/platform/handoff/cloud-to-cloud.mdx @@ -7,6 +7,7 @@ sidebar: label: "Cloud to cloud" --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; Cloud-to-cloud handoff in Warp lets you send follow-up instructions to a finished cloud agent run and continue it in a fresh cloud session. The run keeps the same conversation and restores the prior workspace state, so the agent can pick up where it left off instead of starting over. @@ -17,7 +18,7 @@ Watch this walkthrough to see how cloud-to-cloud handoff continues a cloud agent Use this handoff direction when: * You want to send a follow-up to a cloud agent after its session has ended. -* You want to continue a background cloud agent run, such as a scheduled or integration-triggered run, while preserving it as a single unit of work in the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/platform/oz-web-app/#runs). +* You want to continue a background cloud agent run, such as a scheduled or integration-triggered run, while preserving it as a single unit of work in the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app and the [Runs page in the {VARS.WEB_APP}](/platform/oz-web-app/#runs). ## What carries over @@ -43,7 +44,7 @@ Cloud-to-cloud handoff relies on a snapshot from the prior session. Older cloud To continue an ended cloud run, open the run in Warp and send the next message in the conversation. When the original session has ended, Warp automatically starts a fresh cloud session and restores the prior workspace state. -1. **Open the ended cloud run.** Find it on the [Runs page](https://oz.warp.dev/runs) in the Oz web app or in the conversation panel in the Warp app. +1. **Open the ended cloud run.** Find it on the Runs page in the {VARS.WEB_APP} or in the conversation panel in the Warp app. 2. **Send your follow-up.** Enter the next message in the conversation's input and submit it. The run picks up where it left off, with workspace state restored. @@ -58,9 +59,9 @@ Cloud-to-cloud handoff also works for supported third-party agent runtimes, but ## Inspecting a run that's been handed off -The [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/platform/oz-web-app/#runs) show one row per run, even when the run spans multiple sessions. +The [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app and the [Runs page in the {VARS.WEB_APP}](/platform/oz-web-app/#runs) show one row per run, even when the run spans multiple sessions. -1. Open the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app or the [Runs page in the Oz web app](/platform/oz-web-app/#runs). +1. Open 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). 2. Select the handed-off run. 3. Review the transcript. Each session appears in order, so you can see where one session ended and the next began. diff --git a/src/content/docs/platform/handoff/index.mdx b/src/content/docs/platform/handoff/index.mdx index bd38bd443..82b2b7605 100644 --- a/src/content/docs/platform/handoff/index.mdx +++ b/src/content/docs/platform/handoff/index.mdx @@ -6,6 +6,7 @@ description: >- sidebar: label: "Handoff overview" --- +import { VARS } from '@data/vars'; Handoff moves agent work between local Warp sessions and cloud agent runs without making you restart the task. Depending on the direction, Warp carries over conversation history, workspace changes, and attachments so the receiving agent can continue from the prior session instead of starting from scratch. @@ -38,7 +39,7 @@ flowchart TD Handoff coverage depends on which agent is running the conversation: -* **Cloud to cloud** works for the Warp Agent and the [third-party cloud harnesses currently supported in Oz](/platform/harnesses/): Claude Code and Codex. For Claude Code and Codex runs, click **Continue**, then enter your follow-up prompt. Warp Agent runs use the streamlined follow-up input. +* **Cloud to cloud** works for the Warp Agent and the [third-party cloud harnesses currently supported in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/): Claude Code and Codex. For Claude Code and Codex runs, click **Continue**, then enter your follow-up prompt. Warp Agent runs use the streamlined follow-up input. * **Local to cloud** works for the Warp Agent. It isn't available for third-party CLI agent sessions. ## What carries over @@ -61,8 +62,8 @@ Each direction has a clear motivating workflow. ## Related pages -* [Cloud agents overview](/platform/) - What cloud agents are, when to use them, and how they fit into the Oz Platform. -* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect handoff runs from the Agent Management Panel in the Warp app or the Runs page in the Oz web app alongside local conversations. +* [Cloud agents overview](/platform/) - What cloud agents are, when to use them, and how they fit into the {VARS.WARP_AUTOMATION_PLATFORM}. +* [Managing cloud agents](/platform/managing-cloud-agents/) - Inspect handoff runs from the Agent Management Panel in the Warp app or the Runs page in the {VARS.WEB_APP} alongside local conversations. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`. * [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them. * [Environments](/platform/environments/) - The runtime context a cloud agent runs in after a handoff. diff --git a/src/content/docs/platform/handoff/local-to-cloud.mdx b/src/content/docs/platform/handoff/local-to-cloud.mdx index 9c30c6909..89a2bf42d 100644 --- a/src/content/docs/platform/handoff/local-to-cloud.mdx +++ b/src/content/docs/platform/handoff/local-to-cloud.mdx @@ -7,6 +7,7 @@ sidebar: label: "Local to cloud" --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; Local-to-cloud handoff in Warp promotes an active local Warp Agent conversation into a cloud agent run. Warp forks the conversation, snapshots your uncommitted workspace changes, and sends both to the cloud so the agent can continue the same task with the context and files it needs. @@ -74,7 +75,7 @@ The cloud agent runs with the same model your local conversation was using. Chan After you submit, the cloud agent applies your workspace snapshot and responds to your follow-up. The local conversation is not modified, so you can keep working in it locally or close it. -To check on the new run, open it from the [Runs page](https://oz.warp.dev/runs) in the Oz web app or the conversation panel in the Warp app. +To check on the new run, open it from the Runs page in the {VARS.WEB_APP} or the conversation panel in the Warp app. ## Troubleshooting diff --git a/src/content/docs/platform/handoff/snapshots.mdx b/src/content/docs/platform/handoff/snapshots.mdx index 4f3542c04..5f6600006 100644 --- a/src/content/docs/platform/handoff/snapshots.mdx +++ b/src/content/docs/platform/handoff/snapshots.mdx @@ -7,6 +7,7 @@ description: >- sidebar: label: "Snapshots" --- +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. @@ -230,4 +231,4 @@ Snapshotting is also skipped automatically when cloud conversations are disabled * [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. -* [Oz CLI](/reference/cli/) - Full reference for `oz agent run` and `oz agent run-cloud`. +* [{VARS.WARP_AGENT_CLI}](/reference/cli/) - Full reference for `oz agent run` and `oz agent run-cloud`. diff --git a/src/content/docs/platform/harnesses/authentication.mdx b/src/content/docs/platform/harnesses/authentication.mdx index 7cd5219e1..261368132 100644 --- a/src/content/docs/platform/harnesses/authentication.mdx +++ b/src/content/docs/platform/harnesses/authentication.mdx @@ -1,13 +1,14 @@ --- title: Third-party cloud agent authentication description: >- - Connect your Anthropic or OpenAI credentials to Oz, then launch Claude Code - or Codex as cloud agents from the desktop app, Oz web app, or API. + Connect your Anthropic or OpenAI credentials to the {{WARP_AUTOMATION_PLATFORM}}, then launch Claude Code + or Codex as cloud agents from the desktop app, {{WEB_APP}}, or API. sidebar: label: "Authentication" --- +import { VARS } from '@data/vars'; -Third-party cloud agent authentication in Oz stores provider credentials for cloud runs as Warp-managed secrets. Third-party cloud agents, like [Claude Code](#connecting-claude-code-credentials) and [Codex](#connecting-codex-credentials), call their providers directly, so set up an Anthropic or OpenAI credential once before launching a third-party harness. +Third-party cloud agent authentication in the {VARS.WARP_AUTOMATION_PLATFORM} stores provider credentials for cloud runs as Warp-managed secrets. Third-party cloud agents, like [Claude Code](#connecting-claude-code-credentials) and [Codex](#connecting-codex-credentials), call their providers directly, so set up an Anthropic or OpenAI credential once before launching a third-party harness. Auth secrets can be scoped to a **team** (available to all teammates' runs) or **personal** (only your own runs), like any other Warp-managed secret. @@ -26,24 +27,24 @@ Claude Code is Anthropic's agentic coding tool. For more on Claude Code authenti 3. Navigate to the API keys section, then click **Get API key**. 4. Create a new API key and copy the value. -Oz also supports Bedrock-routed credentials (**Anthropic Bedrock API key** and **Anthropic Bedrock access key**) if your team consumes Anthropic models through AWS. +The {VARS.WARP_AUTOMATION_PLATFORM} also supports Bedrock-routed credentials (**Anthropic Bedrock API key** and **Anthropic Bedrock access key**) if your team consumes Anthropic models through AWS. -### Store API key in Oz +### Store the API key #### Warp desktop app Start a new cloud agent run and choose **Claude Code** from the **Agent harness** dropdown. In the harness auth secret field, add or select your Anthropic credential. -#### Oz web app +#### Web app -Start a [new run](https://oz.warp.dev/runs/new), choose **Claude Code** as the harness, and add a new key in the Claude Code auth secret dialog. +Start a new run, choose **Claude Code** as the harness, and add a new key in the Claude Code auth secret dialog.
![The Oz web app dialog for adding a new Claude Code auth secret.](../../../../assets/agent-platform/claude-code-auth-secret-setup.png)
The Claude Code auth secret dialog.
-#### Oz CLI +#### CLI ```bash oz secret create claude api-key --team @@ -69,17 +70,17 @@ A ChatGPT subscription (Plus, Pro, Team) does not include API access. You need a 4. In the **Create new secret key** dialog, choose the owner, project, and permissions for the key. 5. Click **Create secret key**, then copy the value. -### Store API key in Oz +### Store the API key #### Warp desktop app Start a new cloud agent run and choose **Codex** from the **Agent harness** dropdown. In the harness auth secret field, add or select your OpenAI credential. -#### Oz web app +#### Web app -Start a [new run](https://oz.warp.dev/runs/new), choose **Codex** as the harness, and add a new key in the Codex auth secret dialog. +Start a new run, choose **Codex** as the harness, and add a new key in the Codex auth secret dialog. -#### Oz CLI +#### CLI ```bash oz secret create codex api-key --team @@ -114,7 +115,7 @@ Deleting an auth secret breaks any scheduled or integration-triggered run that r ## Troubleshooting **Claude Code or Codex run fails with an authentication error.**\ -Confirm the run was started with a harness auth secret selected. From the Oz web app's run detail pane, the **Harness auth secret** field shows which secret (if any) was used. Re-launch the run with the correct secret selected, or create one if your team doesn't have one yet. +Confirm the run was started with a harness auth secret selected. From the {VARS.WEB_APP}'s run detail pane, the **Harness auth secret** field shows which secret (if any) was used. Re-launch the run with the correct secret selected, or create one if your team doesn't have one yet. **The harness auth secret dropdown is empty.**\ The dropdown only lists secrets whose type matches the selected harness — Anthropic types for Claude Code, OpenAI for Codex. If you stored the credential as a raw value, recreate it using the typed flow above. @@ -124,7 +125,7 @@ Your team admin has disabled the harness for your workspace. Contact your admin ## Related pages -* [Harnesses in Oz](/platform/harnesses/) — overview of third-party harnesses in Oz. +* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) — overview of third-party harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}. * [Claude Code in Warp](/agents/cli-agents/claude-code/) — run Claude Code locally in the Warp terminal. * [Codex CLI in Warp](/agents/cli-agents/codex/) — run Codex locally in the Warp terminal. * [Cloud agent secrets](/platform/secrets/) — the full Warp-managed secrets reference. diff --git a/src/content/docs/platform/harnesses/claude-code.mdx b/src/content/docs/platform/harnesses/claude-code.mdx index 570d47c20..68a33c955 100644 --- a/src/content/docs/platform/harnesses/claude-code.mdx +++ b/src/content/docs/platform/harnesses/claude-code.mdx @@ -1,21 +1,22 @@ --- -title: Claude Code with Oz +title: Claude Code with the {{WARP_AUTOMATION_PLATFORM}} description: >- - Run Claude Code with Oz. Strong at code review, deep bug investigation, large + Run Claude Code with the {{WARP_AUTOMATION_PLATFORM}}. Strong at code review, deep bug investigation, large feature planning, and frontend or UI work. sidebar: label: "Claude Code" --- +import { VARS } from '@data/vars'; -Claude Code is Anthropic's agentic coding tool. Running it with Oz puts Claude Code inside a Warp-managed environment and connects it to the rest of the Oz platform — including triggers, environments, secrets, observability, and governance — while still behaving like the Claude Code your team already uses. +Claude Code is Anthropic's agentic coding tool. Running it with the {VARS.WARP_AUTOMATION_PLATFORM} puts Claude Code inside a Warp-managed environment and connects it to the rest of the {VARS.WARP_AUTOMATION_PLATFORM} — including triggers, environments, secrets, observability, and governance — while still behaving like the Claude Code your team already uses. :::note -This page covers Claude Code as a **cloud** harness, dispatched and orchestrated by Oz. To run Claude Code locally in your Warp terminal, see [Claude Code in Warp](/agents/cli-agents/claude-code/) instead. +This page covers Claude Code as a **cloud** harness, dispatched and orchestrated by the {VARS.WARP_AUTOMATION_PLATFORM}. To run Claude Code locally in your Warp terminal, see [Claude Code in Warp](/agents/cli-agents/claude-code/) instead. ::: ## Key features -* **Cloud orchestration** - Launch Claude Code from any Oz trigger: the Warp app, the Oz web app, the Oz CLI, the REST API, schedules, Slack mentions, Linear issues, or GitHub Actions. +* **Cloud orchestration** - Launch Claude Code from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, schedules, Slack mentions, Linear issues, or GitHub Actions. * **Claude model picker** - Choose the Claude model the harness uses, including the latest pinned Opus, Sonnet, and Haiku releases, the `best`/`opus`/`sonnet`/`haiku` aliases, and 1M-context variants. * **First-class subagent** - A Warp Agent parent can dispatch Claude Code subagents to handle steps that require code review or nuanced judgment within a larger orchestration. @@ -26,11 +27,11 @@ The Claude Code harness exposes Anthropic's coding-tuned model lineup. Common ch * `best` - Resolves to the current top-of-line Claude model. * `opus`, `sonnet`, `haiku` - Aliases that resolve to the current default for that family. -For the full list — including 1M-context variants for very large codebases and planning-tuned models — open the model picker in the Warp app's Cloud Mode or the **Model** field on the Oz web app's new-run pane. +For the full list — including 1M-context variants for very large codebases and planning-tuned models — open the model picker in the Warp app's Cloud Mode or the **Model** field on the {VARS.WEB_APP}'s new-run pane. ## Credentials and billing -Claude Code calls Anthropic directly using credentials your team provides. Oz supports three Anthropic credential types, stored as [Warp-managed secrets](/platform/secrets/): +Claude Code calls Anthropic directly using credentials your team provides. The {VARS.WARP_AUTOMATION_PLATFORM} supports three Anthropic credential types, stored as [Warp-managed secrets](/platform/secrets/): * **Anthropic API key** - For direct Anthropic API access. * **Anthropic Bedrock API key** - For Bedrock-routed inference using an API key. @@ -43,13 +44,13 @@ For setup steps, see [Connecting Claude Code credentials](/platform/harnesses/au ## Starting a Claude Code run * **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Claude Code**. -* **Oz 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. +* **{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` and the Anthropic secret name on the matching auth-secret field. See the [API reference](/reference/api-and-sdk/). ## Related pages -* [Harnesses in Oz](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. +* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. * [Authentication](/platform/harnesses/authentication/) — store Anthropic credentials as Warp-managed secrets. -* [Warp Agent with Oz](/platform/harnesses/warp-agent/) — Oz's default harness, the only one that can orchestrate Claude Code subagents. -* [Codex with Oz](/platform/harnesses/codex/) — Codex as a cloud harness. +* [Warp Agent with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/warp-agent/) — the {VARS.WARP_AUTOMATION_PLATFORM}'s default harness, the only one that can orchestrate Claude Code subagents. +* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) — Codex as a cloud harness. * [Claude Code in Warp](/agents/cli-agents/claude-code/) — Claude Code in your local Warp terminal. diff --git a/src/content/docs/platform/harnesses/codex.mdx b/src/content/docs/platform/harnesses/codex.mdx index 1377c15ca..9c72f4051 100644 --- a/src/content/docs/platform/harnesses/codex.mdx +++ b/src/content/docs/platform/harnesses/codex.mdx @@ -1,21 +1,22 @@ --- -title: Codex with Oz +title: Codex with the {{WARP_AUTOMATION_PLATFORM}} description: >- - Run Codex with Oz for codebase migrations, release coordination, batch test + Run Codex with the {{WARP_AUTOMATION_PLATFORM}} for codebase migrations, release coordination, batch test generation, and backend or DevOps automation. sidebar: label: "Codex" --- +import { VARS } from '@data/vars'; -Codex is OpenAI's coding agent. Running it with Oz puts Codex inside a Warp-managed environment and connects it to the rest of the Oz platform — including triggers, environments, secrets, observability, and governance — while still behaving like the Codex CLI your team already uses. +Codex is OpenAI's coding agent. Running it with the {VARS.WARP_AUTOMATION_PLATFORM} puts Codex inside a Warp-managed environment and connects it to the rest of the {VARS.WARP_AUTOMATION_PLATFORM} — including triggers, environments, secrets, observability, and governance — while still behaving like the Codex CLI your team already uses. :::note -This page covers Codex as a **cloud** harness, dispatched and orchestrated by Oz. To run Codex locally in your Warp terminal, see [Codex CLI in Warp](/agents/cli-agents/codex/) instead. +This page covers Codex as a **cloud** harness, dispatched and orchestrated by the {VARS.WARP_AUTOMATION_PLATFORM}. To run Codex locally in your Warp terminal, see [Codex CLI in Warp](/agents/cli-agents/codex/) instead. ::: ## Key features -* **Cloud orchestration** - Launch Codex from any Oz trigger: the Warp app, the Oz web app, the Oz CLI, the REST API, schedules, Slack mentions, Linear issues, or GitHub Actions. +* **Cloud orchestration** - Launch Codex from any {VARS.WARP_AUTOMATION_PLATFORM} trigger: the Warp app, the {VARS.WEB_APP}, the {VARS.WARP_AGENT_CLI}, the REST API, schedules, Slack mentions, Linear issues, or GitHub Actions. * **Codex model picker** - Choose the OpenAI model Codex uses, including the GPT-5 lineup, Codex-tuned variants, and a `default` option that lets Codex pick its own recommended model. * **First-class subagent** - A Warp Agent parent can dispatch Codex subagents to handle high-volume or well-defined coding steps inside a larger orchestration. @@ -27,11 +28,11 @@ The Codex harness exposes OpenAI's Codex-tuned and general coding models. Common * `gpt-5.5`, `gpt-5.4` - Recent strong coding models from OpenAI with a configurable reasoning level. * `gpt-5.4-mini` - A faster, lower-cost option for lighter coding tasks or subagents. -For the full list, including Codex-tuned and general models, open the model picker on the Oz web app's new-run pane. For details on each model, see [OpenAI's Codex model docs](https://developers.openai.com/codex/models). +For the full list, including Codex-tuned and general models, open the model picker on the {VARS.WEB_APP}'s new-run pane. For details on each model, see [OpenAI's Codex model docs](https://developers.openai.com/codex/models). ## Credentials and billing -Codex calls OpenAI directly using credentials your team provides. Oz supports one credential type today, stored as a [Warp-managed secret](/platform/secrets/): +Codex calls OpenAI directly using credentials your team provides. The {VARS.WARP_AUTOMATION_PLATFORM} supports one credential type today, stored as a [Warp-managed secret](/platform/secrets/): * **OpenAI API key** - The Codex harness authenticates to OpenAI using this key for every run. @@ -42,13 +43,13 @@ For setup steps, see [Connecting Codex credentials](/platform/harnesses/authenti ## Starting a Codex run * **Warp app** - In Cloud Mode, click the **Agent harness** dropdown above the input and choose **Codex**. -* **Oz 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. +* **{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/). ## Related pages -* [Harnesses in Oz](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. +* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. * [Authentication](/platform/harnesses/authentication/) — store OpenAI credentials as Warp-managed secrets. -* [Warp Agent with Oz](/platform/harnesses/warp-agent/) — Oz's default harness, the only one that can orchestrate Codex subagents. -* [Claude Code with Oz](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. +* [Warp Agent with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/warp-agent/) — the {VARS.WARP_AUTOMATION_PLATFORM}'s default harness, the only one that can orchestrate Codex subagents. +* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. * [Codex CLI in Warp](/agents/cli-agents/codex/) — Codex in your local Warp terminal. diff --git a/src/content/docs/platform/harnesses/index.mdx b/src/content/docs/platform/harnesses/index.mdx index 9feedda5d..f5756f81c 100644 --- a/src/content/docs/platform/harnesses/index.mdx +++ b/src/content/docs/platform/harnesses/index.mdx @@ -1,5 +1,5 @@ --- -title: Harnesses in Oz +title: Harnesses in the {{WARP_AUTOMATION_PLATFORM}} description: >- Run third-party harnesses such as Claude Code or Codex as cloud agents. They inherit the same triggers, environments, secrets, and observability as Warp @@ -8,21 +8,26 @@ sidebar: label: "Overview" --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; -Oz 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. +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. Watch this walkthrough to see how to run Warp Agent, Claude Code, or Codex as a cloud agent. - + ## What stays the same -Third-party harnesses inherit the same Oz platform features as Warp Agent: +Third-party harnesses inherit the same {VARS.WARP_AUTOMATION_PLATFORM} features as Warp Agent: * **Triggers** — Slack, Linear, schedules, CI, and API [triggers](/platform/triggers/) launch any harness. * **Environments and secrets** — Reuse the same [environments](/platform/environments/) and [agent secrets](/platform/secrets/). * **Skills and Rules** — Saved [Skills](/agents/capabilities/skills/) and [Rules](/agents/capabilities/rules/) apply across harnesses. -* **Observability** — Every run produces a transcript and shareable session in the [Oz dashboard](/platform/managing-cloud-agents/). +* **Observability** — Every run produces a transcript and shareable session in the [{VARS.DASHBOARD}](/platform/managing-cloud-agents/). + +## Plan requirements + +Third-party harnesses require a Build plan or higher. On the Free plan, cloud agent runs use Warp Agent, and choosing another harness returns an upgrade prompt. See [Warp pricing](https://www.warp.dev/pricing) for what each plan includes. ## Billing @@ -43,7 +48,7 @@ In Cloud Mode, choose a harness from the **Agent harness** dropdown above the in You can enter Cloud Mode by creating a new **Cloud Agent** tab or by using the `/cloud-agent` slash command. ::: -### Oz web app +### Web app On the new run or new schedule pane, choose the harness in the **Harness** field. @@ -53,8 +58,8 @@ Set the `harness` field on the agent config. See the [API reference](/reference/ ## Related pages -* [Warp Agent with Oz](/platform/harnesses/warp-agent/) — Oz's default first-party harness. -* [Claude Code with Oz](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. -* [Codex with Oz](/platform/harnesses/codex/) — Codex as a cloud harness. +* [Warp Agent with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/warp-agent/) — the {VARS.WARP_AUTOMATION_PLATFORM}'s default first-party harness. +* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. +* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) — Codex as a cloud harness. * [Authentication](/platform/harnesses/authentication/) — connect credentials and launch Claude Code or Codex. * [Third-party CLI agents in the Warp terminal](/agents/cli-agents/overview/) — run Claude Code, Codex, and other CLI agents locally. diff --git a/src/content/docs/platform/harnesses/warp-agent.mdx b/src/content/docs/platform/harnesses/warp-agent.mdx index ad7870bda..53d2338fc 100644 --- a/src/content/docs/platform/harnesses/warp-agent.mdx +++ b/src/content/docs/platform/harnesses/warp-agent.mdx @@ -1,13 +1,14 @@ --- -title: Warp Agent with Oz +title: Warp Agent with the {{WARP_AUTOMATION_PLATFORM}} description: >- - Warp Agent is Oz's default harness. It routes across leading models, has full + Warp Agent is the {{WARP_AUTOMATION_PLATFORM}}'s default harness. It routes across leading models, has full terminal access, and is the only harness that can orchestrate subagents. sidebar: label: "Warp Agent" --- +import { VARS } from '@data/vars'; -Warp Agent is the harness Warp builds and ships with Oz. It's the default for every cloud agent run unless you pick another harness, and it's the only harness that can spawn cross-harness subagents (for example, a Warp Agent parent dispatching a Claude Code or Codex child). +Warp Agent is the harness Warp builds and ships with the {VARS.WARP_AUTOMATION_PLATFORM}. It's the default for every cloud agent run unless you pick another harness, and it's the only harness that can spawn cross-harness subagents (for example, a Warp Agent parent dispatching a Claude Code or Codex child). Warp Agent is the same agent runtime that powers Agent Mode in the Warp terminal. Running it as a cloud harness gives you the same behavior — model routing, tool access, Skills, Rules, Memory — without tying execution to a single laptop. @@ -22,7 +23,7 @@ Warp Agent is the same agent runtime that powers Agent Mode in the Warp terminal ## How it works -Warp Agent is the same agent runtime as Agent Mode in the Warp terminal: it plans, calls tools, edits code, runs tests, and reports progress. The cloud platform adds the [environment](/platform/environments/), triggers, observability, and team governance around the run, and the transcript is inspectable in real time and replayable afterward from the [Oz dashboard](/platform/managing-cloud-agents/). +Warp Agent is the same agent runtime as Agent Mode in the Warp terminal: it plans, calls tools, edits code, runs tests, and reports progress. The cloud platform adds the [environment](/platform/environments/), triggers, observability, and team governance around the run, and the transcript is inspectable in real time and replayable afterward from the [{VARS.DASHBOARD}](/platform/managing-cloud-agents/). Team admins can disable any harness for their workspace. Users on that team can only start runs with the harnesses that remain enabled. @@ -53,17 +54,17 @@ Subagents run in the same environment as the parent and share the same secrets, 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**. -* **Oz web app** - On a new run or new schedule pane, leave the **Harness** field set to **Warp Agent**. -* **Oz CLI** - Run `oz agent run-cloud --prompt "..."` with no `--harness` flag, or pass `--harness oz` explicitly. +* **{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/). For a complete walkthrough, see the [Cloud agents quickstart](/platform/quickstart/). ## Related pages -* [Harnesses in Oz](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. -* [Claude Code with Oz](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. -* [Codex with Oz](/platform/harnesses/codex/) — Codex as a cloud harness. +* [Harnesses in the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/) — choose between Warp Agent, Claude Code, and Codex. +* [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/) — Claude Code as a cloud harness. +* [Codex with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/codex/) — Codex as a cloud harness. * [Model choice](/agents/inference/model-choice/) — the model catalog Warp Agent routes across. * [Agent Profiles and permissions](/agents/capabilities/agent-profiles-permissions/) — configure the default model, autonomy, and tool access for Warp Agent. * [Skills as agents](/platform/skills-as-agents/) — turn a saved skill into a reusable Warp Agent run. diff --git a/src/content/docs/platform/index.mdx b/src/content/docs/platform/index.mdx index 53014998a..b02f064b5 100644 --- a/src/content/docs/platform/index.mdx +++ b/src/content/docs/platform/index.mdx @@ -6,15 +6,22 @@ description: >- sidebar: label: "Cloud agents overview" --- +import { VARS } from '@data/vars'; import VideoEmbed from '@components/VideoEmbed.astro'; +{/* Transition notice for the 2026-08-18 rename. Remove after 2026-09-15, 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 {VARS.WEB_APP} keep the Oz name until September 15, 2026. +::: + 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. ### 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 Oz 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. +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. For a full walkthrough, see [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/). If the run came from Slack, Linear, GitHub Actions, a schedule, the CLI, or the API, it still produces a reviewable cloud agent run record. @@ -33,7 +40,7 @@ Cloud agents are designed for situations where: * **You want agents to operate continuously as part of engineering infrastructure.** * This includes [scheduled maintenance tasks](/platform/triggers/scheduled-agents/) and integration-driven automation. -![Oz use cases across the development lifecycle: Plan, Prototype, Build, Validate, Review + Merge, Deploy + Monitor](../../../assets/agent-platform/oz-use-cases.png) +![Cloud agent use cases across the development lifecycle: Plan, Prototype, Build, Validate, Review + Merge, Deploy + Monitor](../../../assets/agent-platform/oz-use-cases.png) --- @@ -55,7 +62,7 @@ If you are evaluating whether something should be a cloud agent, a good test is ### How cloud agents work -Cloud agents run on the [Oz Platform](/platform/overview/), which provides the primitives for triggering work, orchestrating tasks, executing agents (optionally in environments), injecting secrets, and inspecting results. +Cloud agents run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/), which provides the primitives for triggering work, orchestrating tasks, executing agents (optionally in environments), injecting secrets, and inspecting results. * Something **triggers** an agent task. * The **orchestrator creates** and tracks the task. @@ -63,11 +70,11 @@ Cloud agents run on the [Oz Platform](/platform/overview/), which provides the p 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. -For teams that need execution to stay within their network boundary, self-hosting supports two architectures: a **managed** worker daemon that lets Oz 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](/platform/self-hosting/) for details. ### What you get by default -Because cloud agents run on the [Oz Platform](/platform/overview/), each run is tracked and produces a persistent record that can be observed, shared, and reviewed (even if execution happens outside the Warp app). +Because cloud agents run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/), each run is tracked and produces a persistent record that can be observed, shared, and reviewed (even if execution happens outside the Warp app). #### Codebase Context @@ -77,7 +84,7 @@ Cloud agent runs automatically benefit from [Codebase Context](/agents/capabilit Cloud agent tasks are designed to be inspectable by the team: -* The [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/platform/oz-web-app/#runs) surface task status, source, trigger, creator, history, and credit usage. +* The [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app and the [Runs page in the {VARS.WEB_APP}](/platform/oz-web-app/#runs) surface task status, source, trigger, creator, history, and credit usage. * [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) opens the run transcript so teammates can inspect the prompt, plan, commands, logs, files changed, outputs, and follow-up messages where available. * [Agent Session Sharing](/agents/local-agents/session-sharing/) lets authorized teammates share, monitor, and steer live local or third-party agent sessions. @@ -91,7 +98,7 @@ For details on configuring MCP servers for cloud agents, see [MCP Servers](/plat #### API access to tasks -The Oz Platform exposes task visibility via the [**Oz API and SDKs**](/reference/api-and-sdk/), so teams can: +The {VARS.WARP_AUTOMATION_PLATFORM} exposes task visibility via the [**{VARS.API_SDK_NAME}**](/reference/api-and-sdk/), so teams can: * Query which tasks are running or have run. * Fetch task metadata and outcomes. @@ -99,10 +106,10 @@ The Oz Platform exposes task visibility via the [**Oz API and SDKs**](/reference ### Using cloud agents with or without the Warp app -Cloud agents do not require the Warp app. Teams can deploy and operate them through the [Oz Platform](/platform/overview/) using: +Cloud agents do not require the Warp app. Teams can deploy and operate them through the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) using: -* [Oz CLI](/reference/cli/) — run agents from scripts, CI, or the terminal -* [Oz web app](/platform/oz-web-app/) — visual interface for managing runs, schedules, environments, and integrations (works on mobile) +* [{VARS.WARP_AGENT_CLI}](/reference/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 @@ -113,7 +120,7 @@ If your team also uses Warp's terminal, you get an additional workflow: tasks la ### Billing and plan requirements -Cloud agents and [integrations](/platform/integrations/) run on the [Oz Platform](/platform/overview/) control plane, and usage is billed using credits. +Cloud agents and [integrations](/platform/integrations/) run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) control plane, and usage is billed using credits. :::note [Bring Your Own API Key (BYOK)](/agents/inference/bring-your-own-api-key/) is not supported for cloud agent runs. BYOK keys are stored locally on your device and are not accessible to cloud-hosted agents. All cloud agent runs consume Warp credits. @@ -148,14 +155,14 @@ 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. -* [Oz Platform](/platform/overview/) — CLI, Oz API/SDK, orchestration, tasks, environments, hosts, integrations, and more. +* [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) — CLI, {VARS.API_SDK_NAME}, orchestration, tasks, environments, hosts, integrations, and more. * [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. -* [Oz 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}](/reference/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. -* [Oz API and SDK](/reference/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. +* [{VARS.API_SDK_NAME}](/reference/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. diff --git a/src/content/docs/platform/integrations/azure-devops.mdx b/src/content/docs/platform/integrations/azure-devops.mdx index a7cbf7702..539a2a895 100644 --- a/src/content/docs/platform/integrations/azure-devops.mdx +++ b/src/content/docs/platform/integrations/azure-devops.mdx @@ -6,8 +6,9 @@ description: >- Connect cloud agents to Azure DevOps repos using personal access tokens and Warp-managed secrets. --- +import { VARS } from '@data/vars'; -Cloud agents work with any Git repository, including those hosted on Azure DevOps. A native Azure DevOps integration is not yet available, but you can grant agents access to your repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. +Cloud agents work with any Git repository, including those hosted on Azure DevOps. A native Azure DevOps integration is not yet available, but you can grant agents access to your repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any {VARS.WARP_AUTOMATION_PLATFORM} trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate an Azure DevOps personal access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. @@ -19,9 +20,9 @@ This approach works for both Azure DevOps Services (dev.azure.com) and Azure Dev ## Prerequisites -* A Warp account ([create an account at oz.warp.dev](https://oz.warp.dev)) +* A Warp account (create an account at {VARS.WEB_APP_URL}) * A repository hosted on Azure DevOps (cloud or self-hosted) -* The [Oz CLI](/reference/cli/) installed and authenticated +* The [{VARS.WARP_AGENT_CLI}](/reference/cli/) installed and authenticated --- @@ -121,8 +122,8 @@ oz agent run-cloud --environment --prompt "Your task here" With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: -* **Slack** — Tag **@Oz** in a message to start an agent run against your Azure DevOps repo. See [Slack](/platform/integrations/slack/). -* **Linear** — Tag **@Oz** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/). +* **Slack** — Tag **@warp** in a message to start an agent run against your Azure DevOps repo. See [Slack](/platform/integrations/slack/). +* **Linear** — Tag **@warp** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/). * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/). :::note diff --git a/src/content/docs/platform/integrations/bitbucket.mdx b/src/content/docs/platform/integrations/bitbucket.mdx index 632cfcd8c..3e2c47da4 100644 --- a/src/content/docs/platform/integrations/bitbucket.mdx +++ b/src/content/docs/platform/integrations/bitbucket.mdx @@ -6,8 +6,9 @@ description: >- Connect cloud agents to Bitbucket repos using access tokens and Warp-managed secrets. --- +import { VARS } from '@data/vars'; -Cloud agents work with any Git repository, including those hosted on Bitbucket. Unlike GitHub, Bitbucket does not have a native Warp integration, but you can grant agents access to your Bitbucket repositories using an access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. +Cloud agents work with any Git repository, including those hosted on Bitbucket. Unlike GitHub and GitLab, Bitbucket does not have a native Warp integration, but you can grant agents access to your Bitbucket repositories using an access token and Warp-managed secrets. Once configured, your environment works with any {VARS.WARP_AUTOMATION_PLATFORM} trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate a Bitbucket access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. @@ -22,9 +23,9 @@ Follow the section that matches your setup. ## Prerequisites -* A Warp account ([create an account at oz.warp.dev](https://oz.warp.dev)) +* A Warp account (create an account at {VARS.WEB_APP_URL}) * A repository hosted on Bitbucket (Cloud or Data Center/Server) -* The [Oz CLI](/reference/cli/) installed and authenticated +* The [{VARS.WARP_AGENT_CLI}](/reference/cli/) installed and authenticated --- @@ -185,11 +186,11 @@ Setup commands run on a fresh container for every agent run. Write them to be id --- -## Step 4: Test your environment +## Test your environment -Before connecting to integrations, verify the environment works by running a one-off agent. +Before connecting to integrations, verify the environment works by running a one-off agent. This applies to both Bitbucket Cloud and Bitbucket Data Center / Server. -1. Run the following command, replacing `` with the environment ID from Step 3: +1. Run the following command, replacing `` with the environment ID from Step 3 of whichever setup you followed: ```bash oz agent run-cloud --environment --prompt "Your task here" @@ -201,8 +202,8 @@ oz agent run-cloud --environment --prompt "Your task here" With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: -* **Slack** — Tag **@Oz** in a message to start an agent run against your Bitbucket repo. See [Slack](/platform/integrations/slack/). -* **Linear** — Tag **@Oz** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/). +* **Slack** — Tag **@warp** in a message to start an agent run against your Bitbucket repo. See [Slack](/platform/integrations/slack/). +* **Linear** — Tag **@warp** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/). * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/). :::note diff --git a/src/content/docs/platform/integrations/cloud-providers.mdx b/src/content/docs/platform/integrations/cloud-providers.mdx index bd79dedbc..5a7ae511a 100644 --- a/src/content/docs/platform/integrations/cloud-providers.mdx +++ b/src/content/docs/platform/integrations/cloud-providers.mdx @@ -5,6 +5,7 @@ description: >- sidebar: label: "AWS, GCP, and other cloud providers" --- +import { VARS } from '@data/vars'; Cloud agents can securely access AWS, GCP, and other cloud providers using short-lived OpenID Connect (OIDC) credentials. Configure your cloud agent environment to automatically authenticate to your cloud provider without storing long-lived keys, using Warp's built-in OIDC federation support. @@ -12,7 +13,7 @@ Cloud agents can securely access AWS, GCP, and other cloud providers using short ## Prerequisites -* A Warp account. You can [create an account in the Oz web app](https://oz.warp.dev). +* A Warp account. You can create an account in the {VARS.WEB_APP}. * A cloud provider account Follow the section for your cloud provider. @@ -23,7 +24,7 @@ Follow the section for your cloud provider. ### Step 1: Create an OIDC identity provider -The first step is to configure your AWS account to trust OIDC tokens produced by Oz. +The first step is to configure your AWS account to trust OIDC tokens produced by the {VARS.WARP_AUTOMATION_PLATFORM}. 1. Open the [AWS IAM console](https://console.aws.amazon.com/iam). 2. Click **Identity Providers**, then click **Add provider**. @@ -126,23 +127,23 @@ To allow multiple specific principals, use a list of subjects: Finally, configure the cloud agent environment to use your new AWS role. -1. Open the [Oz web app](https://oz.warp.dev). +1. Open the {VARS.WEB_APP}. 2. Create or edit an environment. See [Environments](/platform/oz-web-app/#environments) for instructions. 3. Expand the **AWS** section and enter the AWS role ARN from Step 2. 4. Save the environment. :::caution -Currently, AWS federation can only be configured in the Oz web app, not the CLI. +Currently, AWS federation can only be configured in the {VARS.WEB_APP}, not the CLI. ::: Agents running in this environment will now automatically assume the configured role when using the `aws` CLI or a compatible SDK. :::note -Oz uses the [**Assume role with web identity**](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-oidc) +The {VARS.WARP_AUTOMATION_PLATFORM} uses the [**Assume role with web identity**](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-oidc) AWS authentication mechanism. The following environment variables are set while the agent is running: * `AWS_ROLE_ARN`: the ARN of the role configured above -* `AWS_WEB_IDENTITY_TOKEN_FILE`: the path to a temporary file containing the agent's Oz OIDC token +* `AWS_WEB_IDENTITY_TOKEN_FILE`: the path to a temporary file containing the agent's {VARS.WARP_AUTOMATION_PLATFORM} OIDC token * `AWS_ROLE_SESSION_NAME`: a derived session name, of the form `Oz_Run_`. ::: @@ -152,8 +153,8 @@ AWS authentication mechanism. The following environment variables are set while ### Step 1: Create a Workload Identity Pool and Provider -The Oz GCP integration uses [Workload Identity Federation](https://docs.cloud.google.com/iam/docs/workload-identity-federation). -You will need to configure a pool and provider to trust OIDC tokens produced by Oz. +The {VARS.WARP_AUTOMATION_PLATFORM} GCP integration uses [Workload Identity Federation](https://docs.cloud.google.com/iam/docs/workload-identity-federation). +You will need to configure a pool and provider to trust OIDC tokens produced by the {VARS.WARP_AUTOMATION_PLATFORM}. These instructions use the `gcloud` tool. You can also follow the OIDC instructions in [Configure Workload Identity Federation with other identity providers](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) @@ -201,7 +202,7 @@ for example, you would run: ```bash gcloud projects add-iam-policy-binding \ - --member "principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools//attribute.teams/" \ + --member "principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools//group/" \ --role "roles/compute.viewer" ``` @@ -212,20 +213,20 @@ for the full syntax supported. Finally, configure the cloud agent environment to use your Workload Identity Federation provider. -1. Open the [Oz web app](https://oz.warp.dev). +1. Open the {VARS.WEB_APP}. 2. Create or edit an environment. See [Environments](/platform/oz-web-app/#environments) for instructions. 3. Expand the **GCP** section and enter the project number, pool ID, and provider ID from Step 1. 4. Save the environment. :::caution -Currently, Workload Identity Federation can only be configured in the Oz web app, not the CLI. +Currently, Workload Identity Federation can only be configured in the {VARS.WEB_APP}, not the CLI. ::: Agents running in this environment will now automatically configure [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials) to use the configured pool. Both the `GOOGLE_APPLICATION_CREDENTIALS` and `CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE` -environment variables are set, so both the `gcloud` CLI and official Google SDKs will use the Oz -federated credentials. Oz uses +environment variables are set, so both the `gcloud` CLI and official Google SDKs will use the {VARS.WARP_AUTOMATION_PLATFORM} +federated credentials. The {VARS.WARP_AUTOMATION_PLATFORM} uses [**executable-sourced credentials**](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create-credential-config) to configure ADC for automatic token rotation. @@ -233,36 +234,38 @@ to configure ADC for automatic token rotation. Environment variables alone are enough for the Google SDKs, but `gcloud` reports no active account until it signs in through its own auth system, and some tooling depends on an active account. During provider -setup, Oz therefore also runs `gcloud auth login` against the federated credential file so `gcloud` reports +setup, the {VARS.WARP_AUTOMATION_PLATFORM} therefore also runs `gcloud auth login` against the federated credential file so `gcloud` reports the federated identity as its active account. This step is best-effort and never blocks the run: -* **`gcloud` isn't installed** - Oz skips the sign-in. The ADC environment variables still provide credentials to the Google SDKs. -* **Sign-in fails or times out** - Oz logs the failure and continues. The ADC environment variables still work, so a run only loses the active-account convenience. +* **`gcloud` isn't installed** - The {VARS.WARP_AUTOMATION_PLATFORM} skips the sign-in. The ADC environment variables still provide credentials to the Google SDKs. +* **Sign-in fails or times out** - The {VARS.WARP_AUTOMATION_PLATFORM} logs the failure and continues. The ADC environment variables still work, so a run only loses the active-account convenience. To confirm the account inside a run, use `gcloud auth list`. ## Other providers -To authenticate from Oz to another provider that supports OIDC federation, you can issue tokens +To authenticate from the {VARS.WARP_AUTOMATION_PLATFORM} to another provider that supports OIDC federation, you can issue tokens directly. Within the agent environment, use the `oz federate issue-token` command to produce an OIDC token with your provider as the audience: ```bash -oz federate issue-token --audience your-provider.com --output-format json +oz federate issue-token --run-id --audience your-provider.com --output-format json ``` -Optionally, add `--duration ` to customize the token validity. This cannot exceed the -maximum runtime of an agent. +Replace `` with the current agent run's ID. + +Optionally, add `--duration ` to customize the token validity. Tokens are valid for +between 5 minutes and 3 hours. You can then exchange this token for provider-specific credentials. ## OIDC token claims -All Oz OIDC tokens include standard claims like `iss` (issuer) and `iat` (issued at). +All {VARS.WARP_AUTOMATION_PLATFORM} OIDC tokens include standard claims like `iss` (issuer) and `iat` (issued at). ### Audience @@ -279,7 +282,7 @@ By default, the `sub` claim uses the format `:`: * `user:abc123def456`: Identifies a user with ID `abc123def456` * `service_account:abc123def456`: Identifies your autogenerated team account -When authenticating to AWS, Oz will use a different `sub` claim format, because AWS trust policies cannot +When authenticating to AWS, the {VARS.WARP_AUTOMATION_PLATFORM} will use a different `sub` claim format, because AWS trust policies cannot match on custom OIDC claims. The format above will be prefixed with your team UID: * `scoped_principal:xyz789/user:abc123def456`: Identifies the user `abc123def456`, who is a member of team `xyz789`. * `scoped_principal:user:abc123def456`: Identifies the user `abc123def456`, who is not on any team. @@ -297,7 +300,7 @@ Team ID: xyz789 Team Name: My Team ``` -You can also check the user IDs from past runs using the Oz API: +You can also check the user IDs from past runs using the {VARS.API_SDK_NAME}: ```bash curl https://app.warp.dev/api/v1/agent/runs -H "Authorization: Bearer $WARP_API_KEY" @@ -318,10 +321,11 @@ curl https://app.warp.dev/api/v1/agent/runs -H "Authorization: Bearer $WARP_API_ ### Team -Every token includes a `teams` claim. The value will be a list with your team UID - currently, this -list only ever contains a single value. +Tokens for principals on a team include a `teams` claim listing the UIDs of the teams the +principal belongs to. Users on multiple teams get multiple values, and users on no team get no +`teams` claim. -### Oz run +### Run The following claims are derived from an agent run: diff --git a/src/content/docs/platform/integrations/github-actions.mdx b/src/content/docs/platform/integrations/github-actions.mdx index 8b804a7b1..ac85fbfb5 100644 --- a/src/content/docs/platform/integrations/github-actions.mdx +++ b/src/content/docs/platform/integrations/github-actions.mdx @@ -5,6 +5,7 @@ description: >- CI fixes. --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; Run agents directly in your GitHub Actions workflows using `oz-agent-action`. The agent integrates seamlessly into your CI pipeline, automating tasks like code review, issue triage, bug fixing, and maintenance using your repository context and GitHub permissions. This page covers how the integration works, how to set it up, and common automation patterns for development teams. @@ -13,10 +14,10 @@ Run agents directly in your GitHub Actions workflows using `oz-agent-action`. Th ::: :::note -GitHub Actions is different from the [GitHub integration](/platform/integrations/github/). GitHub Actions runs agents inside workflows you define in your repository, and you control the trigger, permissions, and prompt in YAML. The GitHub integration starts agents when someone mentions `@oz-agent` on an issue, pull request, or review comment, using the Oz by Warp GitHub App with no workflow file. +GitHub Actions is different from the [GitHub integration](/platform/integrations/github/). GitHub Actions runs agents inside workflows you define in your repository, and you control the trigger, permissions, and prompt in YAML. The GitHub integration starts agents when someone mentions `@warp-agent` on an issue, pull request, or review comment, using the Oz by Warp GitHub App with no workflow file. ::: -If you're comparing GitHub Actions with schedules, Slack, Linear, the GitHub integration, the Oz CLI, or API-triggered runs, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). +If you're comparing GitHub Actions with schedules, Slack, Linear, the GitHub integration, the {VARS.WARP_AGENT_CLI}, or API-triggered runs, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). Watch this demo to see the integration in action: @@ -33,7 +34,7 @@ In this demo ### What the GitHub Actions integration does -The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: +The `oz-agent-action` is a GitHub Action that wraps the {VARS.WARP_AGENT_CLI} and: * Runs an agent inside an Actions job * Caches package installation for faster builds @@ -55,7 +56,7 @@ To use agents in GitHub Actions, you need: ### Using Skills -Skills provide reusable instructions for agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agents/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/agents/capabilities/skills/#skills-as-agents) to run on a schedule or in response to events. +Skills provide reusable instructions for agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agents/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/platform/skills-as-agents/) to run on a schedule or in response to events. #### How to use skills @@ -112,7 +113,7 @@ The `oz-agent-action` supports several automation patterns commonly used in CI. * **Use case**: Add "@oz-agent fix this typo" or similar comments to a PR or Issue. :::note -The [GitHub integration](/platform/integrations/github/) responds to the same `@oz-agent` mentions without a workflow file. Use this Actions pattern when you want the run to happen inside your CI pipeline with workflow-scoped permissions; use the GitHub integration when you want mention-triggered runs on every repository the Oz by Warp GitHub App can access. +The [GitHub integration](/platform/integrations/github/) responds to `@warp-agent` mentions without a workflow file. Use this Actions pattern when you want the run to happen inside your CI pipeline with workflow-scoped permissions; use the GitHub integration when you want mention-triggered runs on every repository the Oz by Warp GitHub App can access. ::: What it does: diff --git a/src/content/docs/platform/integrations/github.mdx b/src/content/docs/platform/integrations/github.mdx index a1c3cac36..05c6050b4 100644 --- a/src/content/docs/platform/integrations/github.mdx +++ b/src/content/docs/platform/integrations/github.mdx @@ -3,12 +3,12 @@ title: GitHub integration sidebar: label: "GitHub" description: >- - Mention @oz-agent on a GitHub issue, pull request, or review comment to start + Mention @warp-agent on a GitHub issue, pull request, or review comment to start a cloud agent that replies in the thread and opens pull requests. --- import { VARS } from '@data/vars'; -The GitHub integration lets your team start cloud agents from GitHub itself. Mention **@oz-agent** in an issue comment, a pull request review comment, or the body of a new pull request, and Warp starts a cloud agent that reads the surrounding context, works the task in your codebase, and posts its progress and results back into the same thread. +The GitHub integration lets your team start cloud agents from GitHub itself. Mention **@warp-agent** in an issue comment, a pull request review comment, or the body of a new pull request, and Warp starts a cloud agent that reads the surrounding context, works the task in your codebase, and posts its progress and results back into the same thread. The integration is powered by the **Oz by Warp** GitHub App. Once a team admin installs the app and enables the GitHub organization, every teammate who has connected their GitHub account can trigger agents from GitHub without leaving a review or an issue. @@ -23,7 +23,7 @@ This page covers the native GitHub App integration. It is distinct from two othe ## What the GitHub integration does -* **@oz-agent mentions** - Mention the agent in a comment or pull request body to start a cloud agent run with the issue or pull request as context. +* **@warp-agent mentions** - Mention the agent in a comment or pull request body to start a cloud agent run with the issue or pull request as context. * **In-thread status** - Warp posts a status comment carrying the run link, then follows up with progress comments and a final summary in the same issue, pull request, or review thread. * **Thread-aware follow-ups** - Mention the agent again in the same thread and Warp continues the existing run instead of starting a new one. * **Automatic repository access** - The repository the event came from is cloned for the run, alongside any repositories in the environment you configure for the integration. @@ -31,9 +31,9 @@ This page covers the native GitHub App integration. It is distinct from two othe ## How it works -When you mention `@oz-agent`, GitHub sends the event to Warp through the Oz by Warp GitHub App installation. Warp then: +When you mention `@warp-agent`, GitHub sends the event to Warp through the Oz by Warp GitHub App installation. Warp then: -1. Confirms the comment or pull request body contains the `@oz-agent` mention and that the author is a person rather than a bot. +1. Confirms the comment or pull request body contains the `@warp-agent` mention and that the author is a person rather than a bot. 2. Maps the GitHub App installation to a Warp team using the organizations enabled in the Admin Panel. 3. Maps the GitHub account that posted the mention to a Warp account, so the run is attributed to that person. 4. Posts a status comment in the thread and starts the cloud agent run with the issue, pull request, or review thread as context. @@ -43,12 +43,12 @@ The agent replies through Warp's status comments, which are posted by the GitHub ### Supported triggers -The integration starts or continues a run for these GitHub events when the text contains `@oz-agent`: +The integration starts or continues a run for these GitHub events when the text contains `@warp-agent`: * **Issue comments** - A new comment on an issue. Warp reads the issue title, description, labels, state, and the recent comment thread. * **Pull request comments** - A new top-level comment on a pull request. These continue the pull request's existing run when one exists. * **Pull request review comments** - A new inline review comment or a reply in a review thread. Warp reads the pull request, the review thread, and the diff of the commented file, and replies inside the same review thread. -* **New pull requests** - A pull request opened with `@oz-agent` in its description. Warp reads the title, description, and the head and base branches. +* **New pull requests** - A pull request opened with `@warp-agent` in its description. Warp reads the title, description, and the head and base branches. Mentions in other places don't start a run. Editing a comment to add the mention, mentioning the agent in an issue or pull request title, and mentions posted by bots are all ignored. @@ -65,7 +65,7 @@ When a run for that thread is already in flight, a new mention is delivered to t ## Requirements * **Team membership** - The GitHub integration requires a [Warp team](/knowledge-and-collaboration/teams/). Configuration is team-scoped, and runs are owned by the team associated with the GitHub App installation. -* **Plan and credits** - Your team must be on a Build, Max, or Business plan with at least 20 credits available, or on an Enterprise plan with a team credit pool per your contract. See [Access, billing, and identity](/platform/team-access-billing-and-identity/). +* **Plan and credits** - Your team must have cloud agents enabled and credits available. On Enterprise plans, runs draw from a team credit pool per your contract. See [Access, billing, and identity](/platform/team-access-billing-and-identity/). * **Oz by Warp GitHub App** - A GitHub organization owner installs the [Oz by Warp](https://github.com/apps/oz-by-warp) GitHub App on the organization or account that owns the repositories, granting it access to all repositories or a selected set. The installation's repository access is what agents act with, so scope it deliberately. * **An enabled GitHub organization** - A Warp team admin adds the organization under **Enabled GitHub Orgs** in the Admin Panel so the installation maps to your Warp team. * **A connected GitHub account** - Each teammate connects their GitHub account to Warp once, so Warp can identify who triggered the run and which team to bill. The connection identifies the requester; it doesn't determine what the agent can reach on GitHub. @@ -98,7 +98,7 @@ In the Warp app, a team admin goes to **Settings** > **Admin Panel** > **Platfor
Enabled GitHub Orgs setting in the Admin Panel.
-Until the organization is enabled, mentions in its repositories return a comment asking a Warp team admin to enable the organization. +Until the organization is enabled, mentions in its repositories return a comment asking a Warp workspace admin to configure GitHub repository access in the Admin Panel. ### 3. Configure how GitHub-triggered runs execute @@ -120,15 +120,15 @@ Each teammate connects their GitHub account so Warp can match the mention to a W Connect the account from the GitHub integration row in the {VARS.WEB_APP}, or the first time you trigger a run: when Warp can't match your GitHub account, it replies in the thread with a link to connect. -## Using @oz-agent in GitHub +## Using @warp-agent in GitHub Mention the agent and describe the task in the same comment: -> @oz-agent this test is flaky on CI. Find the race condition and open a PR with a fix. +> @warp-agent this test is flaky on CI. Find the race condition and open a PR with a fix. On a pull request review comment, the agent also receives the diff for the file you commented on, so you can ask for a targeted change: -> @oz-agent rename this helper to `parseRepoRef` and update the call sites. +> @warp-agent rename this helper to `parseRepoRef` and update the call sites. Warp responds in the thread with a status comment that links to the run, then posts progress updates as the agent works, and finally posts the agent's summary along with any pull requests it opened and branches it pushed. @@ -144,12 +144,12 @@ Every GitHub-triggered run is a cloud agent run: GitHub-triggered runs separate **what the agent can do on GitHub** from **who the run belongs to**. -**Access comes from the GitHub App installation.** A run started by an `@oz-agent` mention authenticates with a token minted for the Oz by Warp GitHub App installation that delivered the event, not with the mentioning user's GitHub authorization. Cloning, branches, commits, pull requests, and the status comments all use that installation token, so on GitHub the work is attributed to the Oz by Warp GitHub App rather than to the person who wrote the mention. The installation's repository selection is therefore the boundary on what the agent can reach: adjust it in your [GitHub settings](https://github.com/settings/installations). +**Access comes from the GitHub App installation.** A run started by an `@warp-agent` mention authenticates with a token minted for the Oz by Warp GitHub App installation that delivered the event, not with the mentioning user's GitHub authorization. Cloning, branches, commits, pull requests, and the status comments all use that installation token, so on GitHub the work is attributed to the Oz by Warp GitHub App rather than to the person who wrote the mention. The boundary on what the agent can reach is the installation's repository selection, optionally narrowed further by the repository access a Warp admin grants the team in the Admin Panel. Adjust the installation in your [GitHub settings](https://github.com/settings/installations). **Identity comes from the account connection.** Warp matches the GitHub account that posted the mention to the Warp account that connected it, not by email address. That binding decides who the run is attributed to in Warp, which team owns it, and whose credits pay for it. The person must be a member of the Warp team that enabled the organization. :::caution -Because the run uses the installation's access rather than the mentioner's, anyone who can comment in a repository covered by the installation — and who has a connected GitHub account on that Warp team — can start an agent that acts with the installation's full repository access. Grant the app only the repositories your team wants agents to work in. +Because the run uses the installation's access rather than the mentioner's, anyone who can comment in a repository covered by the installation — and who has a connected GitHub account on that Warp team — can start an agent that acts with all the repository access granted to that team. Grant the app, and the team, only the repositories your team wants agents to work in. ::: For fully automated workflows that run without a triggering user, such as scheduled agents or runs started with an agent API key, see [Team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization). @@ -167,11 +167,11 @@ For fully automated workflows that run without a triggering user, such as schedu ## Troubleshooting -### Nothing happens after mentioning @oz-agent +### Nothing happens after mentioning @warp-agent The event never reached Warp, or it was filtered out. Check in this order: -1. The comment body contains `@oz-agent`, spelled exactly, rather than only the issue or pull request title. +1. The comment body contains `@warp-agent`, spelled exactly, rather than only the issue or pull request title. 2. The Oz by Warp GitHub App is installed on the organization and has access to that repository. 3. The mention was posted by a person. Bot-authored comments are ignored. 4. The comment is new. Editing an existing comment to add the mention doesn't start a run. @@ -180,13 +180,13 @@ The event never reached Warp, or it was filtered out. Check in this order: Warp received the mention but couldn't match your GitHub account to a Warp account. Use the link in the reply to connect your GitHub account, then mention the agent again. -### "This repository's GitHub App installation is not associated with a Warp team" +### "This repository is not enabled for a Warp team" -The app is installed, but no Warp team has enabled that GitHub organization. A Warp team admin adds the organization under **Enabled GitHub Orgs** in **Settings** > **Admin Panel** > **Platform** in the Warp app. +The app is installed, but no Warp team has access to that repository. A Warp workspace admin configures GitHub repository access in **Settings** > **Admin Panel** > **Platform** in the Warp app. -### "Your Warp account is not a member of any team associated with this repository" +### "Your Warp account is not a member of any team with access to this repository" -Your GitHub account is connected, but your Warp account isn't in the team that enabled the organization. Ask a team admin to add you to the Warp team. +Your GitHub account is connected, but your Warp account isn't in a team with access to that repository. Ask a team admin to add you to the Warp team. ### The run starts but fails immediately diff --git a/src/content/docs/platform/integrations/gitlab.mdx b/src/content/docs/platform/integrations/gitlab.mdx index 6586594f3..d885a7abb 100644 --- a/src/content/docs/platform/integrations/gitlab.mdx +++ b/src/content/docs/platform/integrations/gitlab.mdx @@ -3,29 +3,40 @@ title: GitLab integration sidebar: label: "GitLab" description: >- - Connect cloud agents to GitLab repos using personal access tokens and - Warp-managed secrets. + Connect cloud agents to GitLab.com repos natively, or use access tokens and + Warp-managed secrets for self-managed instances. --- +import { VARS } from '@data/vars'; -Cloud agents work with any Git repository, including those hosted on GitLab. Unlike GitHub, GitLab does not have a native Warp integration, but you can grant agents access to your GitLab repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. +Cloud agents work natively with repositories hosted on GitLab.com. Connect your GitLab account when you create an environment in the {VARS.WEB_APP}, select the projects agents need, and Warp handles the rest at runtime: repositories are cloned automatically, your GitLab credentials are injected into the run, the `glab` CLI is authenticated, and agents can push branches and open merge requests on your behalf. Merge requests the agent opens are reported as run outputs. -This page explains how to generate a GitLab personal access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. +For self-managed GitLab instances, native connection isn't available yet. Instead, grant agents access using a personal access token and Warp-managed secrets, as described in [Self-managed GitLab instances](#self-managed-gitlab-instances). :::note -This approach works for both GitLab.com and self-hosted GitLab instances. +To route GitLab activity into a factory — merge request events and bot mentions triggering work — see the [GitLab factory integration](/factories/integrations/gitlab/) instead. This page covers standalone cloud agent environments. ::: --- -## Prerequisites +## Connect GitLab.com natively -* A Warp account ([create an account at oz.warp.dev](https://oz.warp.dev)) -* A repository hosted on GitLab (cloud or self-hosted) -* The [Oz CLI](/reference/cli/) installed and authenticated +1. In the {VARS.WEB_APP}, create or edit an [environment](/platform/environments/). +2. Choose GitLab as the repository source and authorize with your GitLab account when prompted. Warp requests the `api` and `read_user` scopes, which grant read and write access to your projects. +3. Select the projects the agent should clone, then finish configuring the environment (Docker image, setup commands). + +At the start of each run, Warp clones the selected repositories and injects your GitLab token, so agents can fetch, push branches, and open merge requests without extra setup. Once configured, the environment works with any {VARS.WARP_AUTOMATION_PLATFORM} trigger—Slack, Linear, schedules, or the CLI. + +:::note +Native GitLab environment creation is available in the {VARS.WEB_APP} only. The `--repo` flag on `oz environment create` accepts GitHub repositories; to script GitLab environments, use the web app or the setup-command approach below. +::: --- -## Step 1: Generate a personal access token +## Self-managed GitLab instances + +Native connection supports GitLab.com only. For a self-managed GitLab instance, generate a personal access token, store it securely, and configure an environment that clones your repository at runtime. + +### Step 1: Generate a personal access token :::note These steps generate a personal access token tied to your GitLab account. If your team prefers a shared bot user, [GitLab project access tokens](https://docs.gitlab.com/user/project/settings/project_access_tokens/) work the same way. @@ -35,18 +46,16 @@ These steps generate a personal access token tied to your GitLab account. If you 2. Click your avatar in the top-right corner, then click **Edit profile**. 3. In the left sidebar, click **Access**, then click **Personal access tokens**. 4. Click **Add new token**. -5. Enter a descriptive name for the token (e.g. `warp-oz-agent`), and choose an expiration date that matches your team's rotation policy. +5. Enter a descriptive name for the token (e.g. `warp-agent`), and choose an expiration date that matches your team's rotation policy. 6. Under **Select scopes**, select **read\_repository**. 7. Click **Generate token**. 8. Copy the token value immediately. GitLab will not show it again. :::note -**read\_repository** is the minimum required scope to clone a repository. If a future workflow requires the agent to push commits or open merge requests, you will also need **write\_repository**. +**read\_repository** is the minimum required scope to clone a repository. If a workflow requires the agent to push commits or open merge requests, you also need **write\_repository**. ::: ---- - -## Step 2: Store the token as a Warp-managed secret +### Step 2: Store the token as a Warp-managed secret Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/platform/secrets/) documentation for full details on scoping and managing secrets. @@ -70,11 +79,9 @@ If you need to update a secret value, run: oz secret update --value GITLAB_TOKEN ``` ---- - -## Step 3: Create an environment with a clone setup command +### Step 3: Create an environment with a clone setup command -Create an environment that uses your token to clone the repository at the start of each agent run. Because the `--repo` flag in `oz environment create` is designed for GitHub repositories, you clone your GitLab repo via a setup command instead. +Create an environment that uses your token to clone the repository at the start of each agent run. 1. Run the following command: @@ -82,7 +89,7 @@ Create an environment that uses your token to clone the repository at the start oz environment create \ --name "my-gitlab-env" \ --docker-image \ - --setup-command 'git clone https://oauth2:$GITLAB_TOKEN@gitlab.com/your-group/your-repo.git' \ + --setup-command 'git clone https://oauth2:$GITLAB_TOKEN@gitlab.example.com/your-group/your-repo.git' \ --setup-command 'cd your-repo && ' ``` @@ -92,8 +99,7 @@ Use single quotes around setup commands that reference secrets. Double quotes ca 2. Replace the following placeholders: * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) - * `gitlab.com/your-group/your-repo.git` with your actual repository URL - * For a self-hosted GitLab instance, replace `gitlab.com` with your server's hostname. + * `gitlab.example.com/your-group/your-repo.git` with your server's hostname and repository path * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. :::caution @@ -102,9 +108,7 @@ Setup commands run on a fresh container for every agent run. Write them to be id 3. Note the environment ID returned. You will need it in the next step. ---- - -## Step 4: Test your environment +### Step 4: Test your environment Before connecting to integrations, verify the environment works by running a one-off agent. @@ -118,12 +122,8 @@ oz agent run-cloud --environment --prompt "Your task here" ## Next steps -With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: +With your environment configured, you can connect it to any Warp trigger: -* **Slack** — Tag **@Oz** in a message to start an agent run against your GitLab repo. See [Slack](/platform/integrations/slack/). -* **Linear** — Tag **@Oz** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/). +* **Slack** — Tag **@warp** in a message to start an agent run against your GitLab repo. See [Slack](/platform/integrations/slack/). +* **Linear** — Tag **@warp** on an issue to kick off a workflow. See [Linear](/platform/integrations/linear/). * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/). - -:::note -Native support for opening GitLab merge requests from agent-generated changes is planned as a future enhancement. -::: diff --git a/src/content/docs/platform/integrations/index.mdx b/src/content/docs/platform/integrations/index.mdx index 2e00fd655..8a70e308c 100644 --- a/src/content/docs/platform/integrations/index.mdx +++ b/src/content/docs/platform/integrations/index.mdx @@ -6,6 +6,7 @@ description: >- development workflows. --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; Warp integrations let your team trigger agents directly from the terminal, or from tools like [Slack](/platform/integrations/slack/), [Linear](/platform/integrations/linear/), [Jira](/platform/integrations/jira/), and [GitHub](/platform/integrations/github/). Once set up, agents can: @@ -13,17 +14,13 @@ 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 -If you're deciding whether an agent should run from a schedule, Slack, Linear, GitHub, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). +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 -Warp has two distinct GitHub surfaces. The [GitHub integration](/platform/integrations/github/) starts agents when someone mentions `@oz-agent` on an issue, pull request, or review comment, using the Oz by Warp GitHub App. [GitHub Actions](/platform/integrations/github-actions/) runs agents inside workflows you define in your own CI pipeline. +Warp has two distinct GitHub surfaces. The [GitHub integration](/platform/integrations/github/) starts agents when someone mentions `@warp-agent` on an issue, pull request, or review comment, using the Oz by Warp GitHub App. [GitHub Actions](/platform/integrations/github-actions/) runs agents inside workflows you define in your own CI pipeline. ::: -:::note -For a full walkthrough of Warp's integrations and configurable environments, see [Integration setup](/reference/cli/integration-setup/). -::: - -All of this is powered by the [Oz CLI](/reference/cli/). +Integrations run on the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) (formerly Oz), which handles the trigger, the [environment](/platform/environments/) the agent executes in, and the record of each run. --- @@ -36,8 +33,9 @@ Use the setup walkthrough below for a quick look at how environments connect to * [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. * [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 `@oz-agent` on issues, pull requests, and review comments to start agents that reply in the thread. +* [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. -* [GitLab](/platform/integrations/gitlab/), [Bitbucket](/platform/integrations/bitbucket/), and [Azure DevOps](/platform/integrations/azure-devops/) - Connect non-GitHub repositories with tokens and Warp-managed secrets. +* [GitLab](/platform/integrations/gitlab/) - Connect GitLab.com repos natively, or self-managed instances with tokens and Warp-managed secrets. +* [Bitbucket](/platform/integrations/bitbucket/) and [Azure DevOps](/platform/integrations/azure-devops/) - Connect repositories with tokens and Warp-managed secrets. * [AWS, GCP, and other cloud providers](/platform/integrations/cloud-providers/) - Give cloud agents short-lived access to cloud services. * [Managing cloud agents](/platform/managing-cloud-agents/) - Monitor and review integration-triggered runs across your team by source, status, or creator. diff --git a/src/content/docs/platform/integrations/jira.mdx b/src/content/docs/platform/integrations/jira.mdx index 3113df95e..ab5805d9d 100644 --- a/src/content/docs/platform/integrations/jira.mdx +++ b/src/content/docs/platform/integrations/jira.mdx @@ -5,6 +5,7 @@ sidebar: description: >- Trigger cloud agent runs directly from Jira issues using the warp-agent label. --- +import { VARS } from '@data/vars'; The Jira integration lets your team kick off cloud agent runs directly from Jira Cloud issues. When you add the `warp-agent` label to an issue, an agent starts in the cloud and gets to work — then posts status updates and a summary as Jira comments when it's done. @@ -16,7 +17,7 @@ The Jira integration lets your team kick off cloud agent runs directly from Jira * **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. -* **Jira site admin** - Installing the Oz app in Jira requires site admin permissions. +* **Jira site admin** - Installing the {VARS.WARP_AUTOMATION_PLATFORM} app in Jira requires site admin permissions. --- @@ -24,15 +25,15 @@ The Jira integration lets your team kick off cloud agent runs directly from Jira #### 1. Open the Jira app installation page -In the [Oz web app](https://oz.warp.dev/integrations), find Jira and click **Set up**. On the Atlassian installation page, click **Get app**. +In the {VARS.WEB_APP}, find Jira and click **Set up**. On the Atlassian installation page, click **Get app**. -#### 2. Install Oz on your Jira site +#### 2. Install the app on your Jira site -Choose the Jira Cloud site you want to connect, review the requested permissions, and install Oz. Only Jira site admins can install apps. +Choose the Jira Cloud site you want to connect, review the requested permissions, and install the {VARS.WARP_AUTOMATION_PLATFORM}. Only Jira site admins can install apps. -#### 3. Open the Oz configuration page +#### 3. Open the app configuration page -In your Jira site, open **Manage apps**. Find Oz, open its three-dot actions menu, then click **Configure**. +In your Jira site, open **Manage apps**. Find the {VARS.WARP_AUTOMATION_PLATFORM}, open its three-dot actions menu, then click **Configure**. The configuration page URL for the production app follows this pattern: @@ -50,19 +51,19 @@ The confirmation page displays **Jira connected** when the connection succeeds. #### 5. (Optional) Configure the default environment, model, and harness -Return to the [Integrations page in the Oz web app](https://oz.warp.dev/integrations), then click **Edit Jira** to set the default [environment](/platform/environments/), model, harness, and agent for Jira-triggered runs. If you don't change these settings, Oz uses your workspace's default configuration. +Return to the Integrations page in the {VARS.WEB_APP}, then click **Edit Jira** to set the default [environment](/platform/environments/), model, harness, and agent for Jira-triggered runs. If you don't change these settings, the {VARS.WARP_AUTOMATION_PLATFORM} uses your workspace's default configuration. --- ### How to start a run -Add the label **`warp-agent`** to any Jira issue. Oz will pick it up, post a comment to let you know it's started, and begin working through the task using the issue title, description, and recent comments as context. +Add the label **`warp-agent`** to any Jira issue. The {VARS.WARP_AUTOMATION_PLATFORM} will pick it up, post a comment to let you know it's started, and begin working through the task using the issue title, description, and recent comments as context. -When the run finishes, Oz posts a summary comment to the issue with links to any pull requests or branches it created, along with a link to the full conversation in Warp. To track runs across your team, open the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app, where Jira-triggered runs appear in the **All** tab. +When the run finishes, the {VARS.WARP_AUTOMATION_PLATFORM} posts a summary comment to the issue with links to any pull requests or branches it created, along with a link to the full conversation in Warp. To track runs across your team, open the [Agent Management Panel](/platform/managing-cloud-agents/) in the Warp app, where Jira-triggered runs appear in the **All** tab. #### Connecting your Jira account to Warp -This step is for any user who triggers runs — it doesn't require Jira admin permissions. The first time you trigger a run, Oz posts a comment prompting you to connect your Jira account to Warp. Connecting attributes your Jira-triggered runs to your Warp account; the run doesn't start until your account is connected. After connecting, re-add the `warp-agent` label to start the run. +This step is for any user who triggers runs — it doesn't require Jira admin permissions. The first time you trigger a run, the {VARS.WARP_AUTOMATION_PLATFORM} posts a comment prompting you to connect your Jira account to Warp. Connecting attributes your Jira-triggered runs to your Warp account; the run doesn't start until your account is connected. After connecting, re-add the `warp-agent` label to start the run. 1. Follow the link in the comment to open the Warp page in your Jira personal settings. The link for the production app follows this pattern: @@ -78,13 +79,13 @@ The page displays **Jira account connected** when the link succeeds, and the set ### Troubleshooting -If Oz doesn't respond after adding the label, check that: +If the {VARS.WARP_AUTOMATION_PLATFORM} doesn't respond after adding the label, check that: -* The Oz app is installed and the workspace is connected (see the app's **Configure** screen in Jira). +* The {VARS.WARP_AUTOMATION_PLATFORM} app is installed and the workspace is connected (see the app's **Configure** screen in Jira). * The issue is in Jira Cloud (not Server or Data Center). :::note -When a Jira-triggered run fails to start, Oz updates its comment on the issue to say it could not start the task. Re-add the `warp-agent` label to try again; a new attempt starts a new comment thread. +When a Jira-triggered run fails to start, the {VARS.WARP_AUTOMATION_PLATFORM} updates its comment on the issue to say it could not start the task. Re-add the `warp-agent` label to try again; a new attempt starts a new comment thread. ::: For other issues, reach out to your Warp contact or join the [Warp community on Slack](https://go.warp.dev/join-preview). diff --git a/src/content/docs/platform/integrations/linear.mdx b/src/content/docs/platform/integrations/linear.mdx index efe5a6b70..94299c1a9 100644 --- a/src/content/docs/platform/integrations/linear.mdx +++ b/src/content/docs/platform/integrations/linear.mdx @@ -7,8 +7,9 @@ description: >- pull requests on your behalf. --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; -The Linear integration lets your team delegate development work directly to agents from inside Linear. When you tag @Oz on an issue or comment, an agent will spin up in the cloud, clone the repos defined in your environment, and begin working through the task. +The Linear integration lets your team delegate development work directly to agents from inside Linear. When you tag @warp on an issue or comment, an agent will spin up in the cloud, clone the repos defined in your environment, and begin working through the task. Agents keep you updated inside Linear, generate pull requests using your GitHub account, and provide a link to join a live remote session so you can watch or steer the workflow in real time. @@ -18,18 +19,18 @@ This guide explains what the integration does, how it works end-to-end, and how --- -### Using Oz inside Linear +### Triggering agents inside Linear -Tagging @Oz on an issue or in a Linear comment starts an agent run. Oz clones the repositories defined in your environment, sets up your development environment using your Docker image and setup commands, and begins working through the task with full context from your codebase and the Linear issue. Agents post updates as they progress, including a task list, elapsed time, and checkpoints, so you can follow along without leaving Linear. +Tagging @warp on an issue or in a Linear comment starts an agent run. The {VARS.WARP_AUTOMATION_PLATFORM} clones the repositories defined in your environment, sets up your development environment using your Docker image and setup commands, and begins working through the task with full context from your codebase and the Linear issue. Agents post updates as they progress, including a task list, elapsed time, and checkpoints, so you can follow along without leaving Linear. Agents also share a link to an interactive remote session using Warp's [cloud agent session sharing](/platform/viewing-cloud-agent-runs/). Opening this link lets you view the live terminal output for the running agent in Warp or in the browser. From there, you can interrupt or guide the agent with additional instructions when needed. Once the agent finishes, it will create a pull request on your behalf — using your GitHub permissions — and post a summary of its work and the PR link back into Linear. You can start an agent in two ways: -* **Tag @Oz in a comment** and describe what you want done. -* **Assign the issue to Oz** as if it were a teammate. +* **Tag @warp in a comment** and describe what you want done. +* **Assign the issue to @warp** as if it were a teammate. -Oz will acknowledge the request directly in the Linear issue and begin working. +The agent will acknowledge the request directly in the Linear issue and begin working. Agents keep you informed through: @@ -68,9 +69,9 @@ Because PRs are created as _you_, this makes code review, auditing, and team col ### Requirements * **Team membership** - The Linear integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. -* **Plan and 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. +* **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. -* **Identity** - You must be logged into Warp with the same email as your Linear workspace. +* **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. * You must have write access to the repo if you want Warp to create PRs on your behalf. @@ -79,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 [Oz CLI](/reference/cli/). For more instructions, see [Integrations Overview](/platform/integrations/). +Setup involves two steps powered by the [{VARS.WARP_AGENT_CLI}](/reference/cli/). For more instructions, see [Integrations Overview](/platform/integrations/). #### 1. Create an environment @@ -101,7 +102,7 @@ For full instructions, see our [Environment Setup](/platform/integrations/) docs Once your environment exists, create the integration. :::note -For easier setup, use the [Oz web app](https://oz.warp.dev) to configure integrations with a guided flow. +For easier setup, use the {VARS.WEB_APP} to configure integrations with a guided flow. ::: Alternatively, you can use the CLI: @@ -110,7 +111,7 @@ Alternatively, you can use the CLI: oz integration create linear --environment ``` -The CLI will open a browser window prompting you to install the Oz app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team. +The CLI will open a browser window prompting you to install the {VARS.WARP_AUTOMATION_PLATFORM} app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team. :::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: @@ -123,12 +124,12 @@ If the integration cannot be created or a Linear-triggered run cannot start, use ### Uninstallation instructions -To remove the Oz integration from Linear: +To remove the {VARS.WARP_AUTOMATION_PLATFORM} integration from Linear: 1. Only a Linear team admin can manage app permissions. 2. In Linear, go to **Settings**. 3. Navigate to Agents under the Features section. -4. Select Oz from the list of installed agents. +4. Select the {VARS.WARP_AUTOMATION_PLATFORM} from the list of installed agents. 5. Click **Revoke access** to remove the integration for your workspace. @@ -137,4 +138,4 @@ After revoking access, Warp will no longer be able to read issues, receive trigg ### Troubleshooting -If something isn't working as expected—missing repos, PR failures, Linear not detecting Oz, or environment issues—see our [Integrations Troubleshooting](/platform/integrations/#troubleshooting) page for detailed guidance on GitHub permissions, environment configuration, and common setup problems. +If something isn't working as expected—missing repos, PR failures, Linear not detecting the {VARS.WARP_AUTOMATION_PLATFORM}, or environment issues—see our [Integrations Troubleshooting](/platform/integrations/#troubleshooting) page for detailed guidance on GitHub permissions, environment configuration, and common setup problems. diff --git a/src/content/docs/platform/integrations/quickstart-github-actions.mdx b/src/content/docs/platform/integrations/quickstart-github-actions.mdx index cf5b3ca10..54830ef12 100644 --- a/src/content/docs/platform/integrations/quickstart-github-actions.mdx +++ b/src/content/docs/platform/integrations/quickstart-github-actions.mdx @@ -6,6 +6,7 @@ description: >- sidebar: label: "Quickstart" --- +import { VARS } from '@data/vars'; Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://github.com/warpdotdev/oz-agent-action). This quickstart walks you through setting up your first GitHub Actions integration: a PR review workflow that automatically analyzes pull requests and posts inline review comments. @@ -13,7 +14,7 @@ Add agents to your GitHub Actions workflows with [`oz-agent-action`](https://git ## Prerequisites -* **Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings). 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 {VARS.WEB_APP}. 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. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. --- @@ -35,7 +36,7 @@ This workflow triggers an agent whenever a PR is opened or marked ready for revi Create `.github/workflows/oz-pr-review.yml` in your repository with the following content: ```yaml -name: Oz PR review +name: Warp PR review on: pull_request: @@ -51,7 +52,7 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Review PR with Oz + - name: Review PR with Warp uses: warpdotdev/oz-agent-action@v1 with: prompt: | @@ -71,14 +72,14 @@ Create a new pull request in your repository to trigger the workflow. To verify the workflow ran: 1. Go to the **Actions** tab in your repository. -2. Click **Oz PR review** in the list of workflows. +2. Click **Warp PR review** in the list of workflows. 3. Select the most recent run to see the agent's output in the job logs. ## 4. View the run -Each `oz-agent-action` step creates a cloud agent run you can inspect from the Oz dashboard: +Each `oz-agent-action` step creates a run you can inspect from the {VARS.DASHBOARD}: -* **Oz web app** - Go to the [Runs page in the Oz web app](https://oz.warp.dev/runs) to see the full run transcript: status, commands executed, files changed, and agent output. See [Viewing Cloud Agent Runs](/platform/viewing-cloud-agent-runs/) for a complete walkthrough. +* **{VARS.WEB_APP}** - Go to the Runs page in the {VARS.WEB_APP} to see the full run transcript: status, commands executed, files changed, and agent output. See [Viewing Cloud Agent Runs](/platform/viewing-cloud-agent-runs/) for a complete walkthrough. * **Warp app** - Open the conversations panel to see the run alongside your other agent activity. When the run completes, the agent posts feedback as inline review comments on the PR. diff --git a/src/content/docs/platform/integrations/quickstart.mdx b/src/content/docs/platform/integrations/quickstart.mdx index b4b4103b8..13bd19931 100644 --- a/src/content/docs/platform/integrations/quickstart.mdx +++ b/src/content/docs/platform/integrations/quickstart.mdx @@ -6,18 +6,19 @@ description: >- sidebar: label: "Quickstart" --- +import { VARS } from '@data/vars'; -Oz integrations let you trigger cloud agents directly from the tools your team already uses. This guide walks you through connecting Oz to Slack. Once set up, anyone on your team can tag @Oz in a message or thread to kick off a cloud agent that runs the task and posts results back to the conversation. +{VARS.WARP_AUTOMATION_PLATFORM} integrations let you trigger cloud agents directly from the tools your team already uses. This guide walks you through connecting the {VARS.WARP_AUTOMATION_PLATFORM} to Slack. Once set up, anyone on your team can tag @warp in a message or thread to kick off a cloud agent that runs the task and posts results back to the conversation. :::note -**Want to connect with Linear instead?** The setup is the same — just substitute `slack` with `linear` in the CLI commands, or select Linear in the Oz web app. See [Linear](/platform/integrations/linear/) for details. +**Want to connect with Linear instead?** The setup is the same — just substitute `slack` with `linear` in the CLI commands, or select Linear in the {VARS.WEB_APP}. See [Linear](/platform/integrations/linear/) for details. ::: --- ## Prerequisites -* **Eligible plan** - The Slack integration requires a Warp team on Build, Max, or Business plan with at least 20 credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/). +* **Eligible team** - The Slack integration requires a Warp team with cloud agents enabled and credits available. See [Access, Billing, and Identity](/platform/team-access-billing-and-identity/). * **A cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have one yet, follow the [Cloud Agents Quickstart](/platform/quickstart/) or run `/create-environment` in Warp. * **GitHub authorization** - Warp needs access to your repos to clone code and open PRs. You'll be prompted to authorize the Warp GitHub app when you first create the integration. @@ -25,15 +26,15 @@ Oz integrations let you trigger cloud agents directly from the tools your team a ## 1. Connect the Slack integration -The simplest way to set up the integration is **using the Oz web app**: +The simplest way to set up the integration is **using the {VARS.WEB_APP}**: -1. Navigate to the [Integrations page in the Oz web app](https://oz.warp.dev/integrations). +1. Navigate to the Integrations page in the {VARS.WEB_APP}. 2. Click **Slack**. -3. Follow the guided flow to select your environment and authorize Oz in your Slack workspace. +3. Follow the guided flow to select your environment and authorize the {VARS.WARP_AUTOMATION_PLATFORM} in your Slack workspace. All members of your Warp team can now use the integration. -**Using the Oz CLI instead:** +**Using the {VARS.WARP_AGENT_CLI} instead:** Run `oz integration create` to connect the Slack integration: @@ -41,7 +42,7 @@ Run `oz integration create` to connect the Slack integration: oz integration create slack --environment ``` -Replace `` with your environment ID (see [Environments](/platform/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Oz app in your workspace. +Replace `` with your environment ID (see [Environments](/platform/environments/) if you need to create one). Find it with `oz environment list` on the {VARS.WARP_AGENT_CLI} or in the {VARS.WEB_APP}. The CLI opens a browser window to authorize the {VARS.WARP_AUTOMATION_PLATFORM} app in your workspace. :::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: @@ -58,31 +59,31 @@ oz integration create slack \ --prompt "Always open a draft PR and request review from the team-leads group." ``` -## 2. Tag @Oz in Slack +## 2. Tag the agent in Slack -In any channel or thread in your Slack workspace, tag @Oz with a task: +In any channel or thread in your Slack workspace, tag @warp with a task: -> @Oz scan the authentication module for security issues and summarize what you find +> @warp scan the authentication module for security issues and summarize what you find -Oz acknowledges the request immediately and starts an agent run in the cloud. You'll see progress updates appear in the thread as the agent works. +The {VARS.WARP_AUTOMATION_PLATFORM} acknowledges the request immediately and starts an agent run in the cloud. You'll see progress updates appear in the thread as the agent works. -You can also tag @Oz inside an existing thread. Oz picks up the full thread history as context automatically, so you can tag it mid-discussion without repeating background. +You can also tag @warp inside an existing thread. The {VARS.WARP_AUTOMATION_PLATFORM} picks up the full thread history as context automatically, so you can tag it mid-discussion without repeating background. ## 3. Watch the run While the agent works, progress updates appear directly in the Slack thread. To inspect the run in more detail: -* **Click the session link** - Oz posts a link in the thread to open a live terminal view of the agent. Watch in real time, add follow-up instructions, or let it run to completion. -* **Go to the [Runs page in the Oz web app](https://oz.warp.dev/runs)** - See the full run transcript: status, commands executed, files changed, and agent output. See [Viewing Cloud Agent Runs](/platform/viewing-cloud-agent-runs/) for a complete walkthrough. +* **Click the session link** - The {VARS.WARP_AUTOMATION_PLATFORM} posts a link in the thread to open a live terminal view of the agent. Watch in real time, add follow-up instructions, or let it run to completion. +* **Go to the Runs page in the {VARS.WEB_APP}** - See the full run transcript: status, commands executed, files changed, and agent output. See [Viewing Cloud Agent Runs](/platform/viewing-cloud-agent-runs/) for a complete walkthrough. -When the task is complete, Oz posts a summary back to the original Slack thread. +When the task is complete, the {VARS.WARP_AUTOMATION_PLATFORM} posts a summary back to the original Slack thread. -**Breaking it down:** Oz reads the Slack thread as context, runs the agent inside the environment you configured — with your repos cloned and Docker image running — and returns results where the conversation started, in Slack, without anyone leaving the thread. +**Breaking it down:** The {VARS.WARP_AUTOMATION_PLATFORM} reads the Slack thread as context, runs the agent inside the environment you configured — with your repos cloned and Docker image running — and returns results where the conversation started, in Slack, without anyone leaving the thread. --- ## Next steps -* **Customize agent behavior** - Use a [skill](/platform/skills-as-agents/) as the base prompt for your integration to give Oz consistent, reusable instructions across every run. +* **Customize agent behavior** - Use a [skill](/platform/skills-as-agents/) as the base prompt for your integration to give the {VARS.WARP_AUTOMATION_PLATFORM} 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. * **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 7d4cfb8d3..d00988f73 100644 --- a/src/content/docs/platform/integrations/slack.mdx +++ b/src/content/docs/platform/integrations/slack.mdx @@ -6,6 +6,7 @@ description: >- Trigger agents from Slack to run cloud tasks, track progress, and create pull requests. --- +import { VARS } from '@data/vars'; The Slack integration lets your team trigger cloud agents directly from Slack conversations. Tag @Warp in a message or DM the bot to start a cloud agent that clones your repos, works through the task, posts progress updates, and opens pull requests back into the same thread. @@ -13,12 +14,12 @@ The Slack integration lets your team trigger cloud agents directly from Slack co #### Installation -1. Log in to the [Oz web app](https://oz.warp.dev) and go to the [Integrations page](https://oz.warp.dev/integrations). +1. Log in to the {VARS.WEB_APP} and go to the Integrations page. 2. Click **Connect** next to **Slack**. You'll be prompted to install the Warp app into your Slack workspace. 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 [Oz CLI](/reference/cli/): +Alternatively, install via the [{VARS.WARP_AGENT_CLI}](/reference/cli/): ``` oz integration create slack --environment @@ -29,7 +30,7 @@ The CLI opens a browser window to install the Warp app into your Slack workspace #### Requirements * **Team membership** - The Slack integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. -* **Plan and 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. +* **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. --- @@ -64,7 +65,7 @@ Agents keep you informed directly in Slack via: * Activity updates showing progress throughout the run * Checkpoints indicating major steps completed -* A direct link to the Oz run in the [Oz web app](/platform/oz-web-app/), where you can view the full run transcript and metadata +* A direct link to the {VARS.PLATFORM_RUN} in the [{VARS.WEB_APP}](/platform/oz-web-app/), where you can view the full run transcript and metadata * A session-sharing link that opens a live terminal view of the remote agent [Cloud agent session sharing](/platform/viewing-cloud-agent-runs/) works in Warp or in your browser and supports multiple teammates joining the same live session. @@ -73,7 +74,7 @@ To monitor Slack-triggered runs alongside the rest of your team's agents, open t ### Joining the live remote session -Selecting **View Agent** opens the active agent session. Inside the session you’ll see: +Selecting **View conversation** opens the active agent session. Inside the session you’ll see: * The agent’s full execution log * The plan/task list @@ -107,7 +108,7 @@ An environment defines everything the agent needs to run your code in the cloud: Create an environment via: -* **Oz CLI** +* **{VARS.WARP_AGENT_CLI}** ```bash oz environment create \ @@ -144,14 +145,14 @@ If the integration cannot be created or a Slack-triggered run cannot start, use * Integrations are scoped to your Warp team. * Any teammate in the same Slack workspace and Warp team can use the integration. -* Warp maps Slack users to Warp accounts by email address. +* The first time you mention the bot or DM it, Warp sends you a link to connect your Slack identity to your Warp account. * Teammates must individually authorize GitHub on their first run. --- ### Privacy -The Warp app reads Slack messages only where it is mentioned or directly messaged: the triggering message, its thread history (used as task context), and your Slack profile email (used to map you to your Warp account). Message content is used to run the agent task and is handled per the [Warp Privacy Policy](https://www.warp.dev/privacy), which describes how Warp collects, manages, and stores third-party data. +The Warp app reads Slack messages only where it is mentioned or directly messaged: the triggering message, its thread history (used as task context), and your Slack profile information. Message content is used to run the agent task and is handled per the [Warp Privacy Policy](https://www.warp.dev/privacy), which describes how Warp collects, manages, and stores third-party data. ### Uninstallation instructions diff --git a/src/content/docs/platform/managing-cloud-agents.mdx b/src/content/docs/platform/managing-cloud-agents.mdx index a87ccc804..46b1cdbc2 100644 --- a/src/content/docs/platform/managing-cloud-agents.mdx +++ b/src/content/docs/platform/managing-cloud-agents.mdx @@ -2,21 +2,22 @@ title: Managing cloud agents description: >- Monitor and manage agent activity across your team with Warp's Agent - Management Panel and the Oz web app's Runs page. + Management Panel and the {{WEB_APP}}'s Runs page. sidebar: label: "Managing cloud agents" --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; -Warp provides two management surfaces for tracking and observing agent activity across your account and, where applicable, your team: the **Agent Management Panel** in the Warp app and the [**Runs** page in the Oz web app](/platform/oz-web-app/#runs), which also works on mobile devices. +Warp provides two management surfaces for tracking and observing agent activity across your account and, where applicable, your team: the **Agent Management Panel** in the Warp app and the [**Runs** page in the {VARS.WEB_APP}](/platform/oz-web-app/#runs), which also works on mobile devices. 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. -The Agent Management Panel and Oz web app Runs page are designed to answer, at a glance: +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. * Which runs are working, blocked, failed, succeeded, or canceled. -* Where an agent run was triggered from, such as a local agent conversation, the Oz CLI, Slack, Linear, a schedule, or the API. +* Where an agent run was triggered from, such as a local agent conversation, the {VARS.WARP_AGENT_CLI}, Slack, Linear, a schedule, or the API. * How parent and child runs relate in orchestrated workflows. * Which session to open when you need prompt, plan, command, log, output, or follow-up context. * How many credits those runs consumed. @@ -34,7 +35,7 @@ These management surfaces include your **local (interactive) agents** and [cloud ### What appears in the agent management surfaces -The Agent Management Panel and Oz web app Runs page include two categories of agent activity. +The Agent Management Panel and {VARS.WEB_APP} Runs page include two categories of agent activity. #### Interactive agents @@ -58,7 +59,7 @@ In the **Personal** tab, you can view all of the interactive and cloud agent con ### Inspect or review an agent run -Use the Agent Management Panel or Oz web app Runs page as the starting point when a teammate asks, "What did the agent do?" +Use the Agent Management Panel or {VARS.WEB_APP} Runs page as the starting point when a teammate asks, "What did the agent do?" 1. In the agents list, use the filter menu to filter by source, day, creator, or status. 2. Select the matching row to open the shared session or local conversation. @@ -81,7 +82,7 @@ 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 [Oz CLI](/reference/cli/) +* **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/) * **Slack / Linear**: runs triggered by [integrations](/platform/integrations/) * **Scheduled**: runs triggered on a [cron schedule](/platform/triggers/scheduled-agents/) @@ -127,9 +128,9 @@ When a parent agent spawns one or more child agents through [multi-agent orchest * **Local children in the Warp app** - while you're viewing the parent agent, an orchestration pill bar above the agent view header shows one pill per child with a live status badge. Click a child pill to switch the pane to that child's conversation in place; click the parent pill - or the breadcrumb that replaces the pill bar while you're viewing a child - to return. Local children don't appear as separate rows in the Agent Management Panel list. * **Cloud children in the Warp app** - appear in the Agent Management Panel list as their own rows alongside the parent and other runs. Filter by source, status, or creator to isolate them. -* **Cloud children in the [Oz web app](/platform/oz-web-app/)** - grouped under the parent's row on the Runs page, and surfaced together inside the parent's detail pane on a **Sub-agents** tab. +* **Cloud children in the [{VARS.WEB_APP}](/platform/oz-web-app/)** - grouped under the parent's row on the Runs page, and surfaced together inside the parent's detail pane on a **Sub-agents** tab. -The parent's own status reflects only its work - a parent can finish successfully while a child is still running or has failed. To verify that an orchestration completed, check each child individually from the pill bar (in the Warp app) or the **Sub-agents** tab (in the Oz web app). +The parent's own status reflects only its work - a parent can finish successfully while a child is still running or has failed. To verify that an orchestration completed, check each child individually from the pill bar (in the Warp app) or the **Sub-agents** tab (in the {VARS.WEB_APP}). ## Related pages @@ -137,4 +138,4 @@ The parent's own status reflects only its work - a parent can finish successfull * [Multi-agent orchestration](/platform/orchestration/) — Parent/child model, run state transitions, and common orchestration patterns. * [Viewing cloud agent runs](/platform/viewing-cloud-agent-runs/) — Open and inspect a remote cloud agent run. * [Handoff between local and cloud agents](/platform/handoff/) — Move agent work between local and cloud, or continue a finished cloud run. -* [Oz web app](/platform/oz-web-app/) — Manage runs and schedules from any browser. +* [{VARS.WEB_APP}](/platform/oz-web-app/) — Manage runs and schedules from any browser. diff --git a/src/content/docs/platform/mcp.mdx b/src/content/docs/platform/mcp.mdx index 6340c539d..7ed331f26 100644 --- a/src/content/docs/platform/mcp.mdx +++ b/src/content/docs/platform/mcp.mdx @@ -6,6 +6,7 @@ description: >- sidebar: label: "MCP servers" --- +import { VARS } from '@data/vars'; Cloud agents can call external tools through [Model Context Protocol (MCP) servers](/agents/capabilities/mcp/). This lets agents reach beyond the terminal to automatically interact with systems like GitHub, dbt, Sentry, or any custom internal service, whenever the workflow requires it. @@ -66,7 +67,7 @@ You can define any number of MCP servers in a single config. ``` :::note -If the config passes through a system that pre-processes `{{...}}` before it reaches Oz (for example, Jira/Atlassian Automation), use JSON unicode escapes for the braces: `\u007b\u007bMY_SECRET\u007d\u007d` decodes to `{{MY_SECRET}}`, which Oz resolves normally. +If the config passes through a system that pre-processes `{{...}}` before it reaches the {VARS.WARP_AUTOMATION_PLATFORM} (for example, Jira/Atlassian Automation), use JSON unicode escapes for the braces: `\u007b\u007bMY_SECRET\u007d\u007d` decodes to `{{MY_SECRET}}`, which the {VARS.WARP_AUTOMATION_PLATFORM} resolves normally. ::: ## Using MCP servers in an agent config file diff --git a/src/content/docs/platform/orchestration/index.mdx b/src/content/docs/platform/orchestration/index.mdx index a47109777..d21e1f3c3 100644 --- a/src/content/docs/platform/orchestration/index.mdx +++ b/src/content/docs/platform/orchestration/index.mdx @@ -1,12 +1,13 @@ --- title: Multi-agent orchestration -description: Coordinate parent and child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows on the Oz Platform. +description: Coordinate parent and child agents across local and cloud runs to build supervisor/worker, fan-out, critic, DAG, and swarm workflows in Warp. sidebar: label: "Orchestration" --- 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 [Oz CLI](/reference/cli/), and the [Oz API](/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}](/reference/cli/), and the [{VARS.API_SDK_NAME}](/reference/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. @@ -21,7 +22,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 [Oz web app](/platform/oz-web-app/), and the [Oz API](/reference/api-and-sdk/) render that single level. The parent and each child each have an independent **run** with its own lifecycle, transcript, conversation, and credit usage. +Orchestrations today are exactly one level deep: a parent and its direct children. The Warp app, the [{VARS.WEB_APP}](/platform/oz-web-app/), and the [{VARS.API_SDK_NAME}](/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. ### Where parent and child agents can run @@ -51,8 +52,8 @@ 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 Oz web app** - cloud children appear under the parent on the [Runs page](https://oz.warp.dev/runs) and in the parent's **Sub-agents** tab, with their status updating live. -* **The Oz 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. +* **The {VARS.WEB_APP}** - cloud children appear under the parent on the Runs page 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. ## Messaging between agents @@ -112,14 +113,14 @@ In both cases, approval is required before the parent launches children. Approvi Because every parent and child is tracked as its own conversation or run, the existing observability surfaces work without changes: * **[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. -* **[Oz 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. -* **[Oz API](/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.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). * **[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. -* [Oz API and SDK](/reference/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 Oz Platform. +* [{VARS.API_SDK_NAME}](/reference/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. diff --git a/src/content/docs/platform/orchestration/multi-agent-runs.mdx b/src/content/docs/platform/orchestration/multi-agent-runs.mdx index 469cc1150..4cdcdb3d0 100644 --- a/src/content/docs/platform/orchestration/multi-agent-runs.mdx +++ b/src/content/docs/platform/orchestration/multi-agent-runs.mdx @@ -1,12 +1,13 @@ --- title: Running orchestrated agents -description: Start multi-agent orchestrations from the Warp app, the Oz CLI, the Oz web app, or the Oz API, 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 {{API_SDK_NAME}}, 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 Oz CLI, the Oz web app, or the Oz 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. +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. Watch this walkthrough to see how to start and inspect an orchestrated agent run from Warp. @@ -17,7 +18,7 @@ Watch this walkthrough to see how to start and inspect an orchestrated agent run Pick where the parent will run. Every orchestration starts with a single parent that spawns children: * **Parent in the Warp app** - use the `/orchestrate` or `/plan` slash command. This is the fastest way to try orchestration. -* **Parent in the cloud** - trigger the parent through the Oz CLI (`oz agent run-cloud`), the [Oz API](/reference/api-and-sdk/), or any integration (Slack, Linear, schedule). The parent runs in an environment and spawns children from there. +* **Parent in the cloud** - trigger the parent through the {VARS.WARP_AGENT_CLI} (`oz agent run-cloud`), the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), or any integration (Slack, Linear, schedule). 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. @@ -63,9 +64,9 @@ This is the recommended way to fan work out from the CLI: the parent decides how If you need to fan out from a script and want each child linked to a specific parent, use the [API](#starting-an-orchestrated-run-from-the-api). `oz agent run-cloud` doesn't currently accept a parent run ID flag, so script-launched runs from the CLI are independent runs. ::: -## Starting an orchestrated run from the Oz web app +## Starting an orchestrated run from the web app -In the Oz web app's [**Runs** page](https://oz.warp.dev/runs): +In the {VARS.WEB_APP}'s **Runs** page: 1. Click **New run** in the header. 2. Select an environment and, optionally, a skill that performs orchestration. @@ -118,7 +119,7 @@ Content-Type: application/json } ``` -Setting `parent_run_id` is what links the child to its parent across the Agent Management Panel in the Warp app, the Oz web app Runs page, and the descendants query (`?ancestor_run_id=`). +Setting `parent_run_id` is what links the child to its parent across the Agent Management Panel in the Warp app, the {VARS.WEB_APP} Runs page, and the descendants query (`?ancestor_run_id=`). A scripted fan-out, including parent linking, looks like this: @@ -148,7 +149,7 @@ done ## Retrieving conversations and artifacts -Every parent and child started through the Oz API is tracked as an Oz 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.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: * **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`. @@ -190,7 +191,7 @@ Self-hosted, local, and GitHub Action runs cannot be cancelled through this endp * [Multi-agent orchestration](/platform/orchestration/) - parent/child model, run state transitions, and common patterns. * [How to run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) - practical task decomposition, worktree ownership, validation, and review handoff guidance. -* [Oz CLI](/reference/cli/) - command reference for `oz agent run-cloud` and `oz run`. -* [Oz API and SDK](/reference/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 Oz web app. +* [{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. +* [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}. * [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 d7fab747b..b4f315516 100644 --- a/src/content/docs/platform/overview.mdx +++ b/src/content/docs/platform/overview.mdx @@ -1,16 +1,25 @@ --- -title: Oz Platform overview +title: "{{WARP_AUTOMATION_PLATFORM}} overview" description: >- - The Oz Platform provides the CLI, API/SDK, orchestration, environments, and + The {{WARP_AUTOMATION_PLATFORM}} provides the CLI, API/SDK, orchestration, environments, and observability for cloud agents. sidebar: - label: "Oz platform" + label: "{{WARP_AUTOMATION_PLATFORM}}" --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; -Cloud agents run on the **Oz Platform**. The platform gives you a consistent way to **trigger work**, **orchestrate and track tasks**, **execute agents** (in an optional [environment](/platform/environments/), on a host), and inspect outcomes with team visibility. First-party [integrations](/platform/integrations/) connect external events — like Slack messages, GitHub PRs, or CI failures — to cloud agents automatically. +Cloud agents run on the **{VARS.WARP_AUTOMATION_PLATFORM}**. The platform gives you a consistent way to **trigger work**, **orchestrate and track tasks**, **execute agents** (in an optional [environment](/platform/environments/), on a host), and inspect outcomes with team visibility. First-party [integrations](/platform/integrations/) connect external events — like Slack messages, GitHub PRs, or CI failures — to cloud agents automatically. - +{/* Transition notice for the 2026-08-18 rename. Remove after 2026-09-15, 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 {VARS.WEB_APP} keep the Oz name until September 15, 2026, which is why you'll still see it in commands and URLs. +::: + + :::note **New to cloud agents?** Start with the [Cloud agents quickstart](/platform/quickstart/) to run your first agent in ~10 minutes. @@ -23,11 +32,11 @@ Cloud agents run on the **Oz Platform**. The platform gives you a consistent way 3. The agent executes on a **host**, optionally inside an environment, using the required configuration and credentials. 4. The task produces a **persistent record** (status, metadata, transcript, outputs) your team can review and manage. -![Oz Platform architecture showing Trigger, Agent, Environment, and Artifacts components](../../../assets/agent-platform/most-flexible-platform-for-building-with-agents.png) +![Flow diagram: a trigger kicks off an agent, which runs in an environment and creates artifacts, on either Warp-hosted or self-hosted infrastructure](../../../assets/agent-platform/most-flexible-platform-for-building-with-agents.png) -![Oz Platform detailed architecture showing components, triggers, orchestrator, and agent runners](../../../assets/agent-platform/oz-diagram.png) +![Architecture diagram: Warp-designed and customer-defined triggers create an agent task, which the agent orchestrator routes to agent runners on Warp or customer infrastructure](../../../assets/agent-platform/platform-architecture.png) -The sections below describe the Oz Platform primitives that power this flow, and how they compose. +The sections below describe the {VARS.WARP_AUTOMATION_PLATFORM} primitives that power this flow, and how they compose. --- @@ -44,9 +53,15 @@ In practice: **triggers create tasks; tasks execute on a host (optionally in an --- -### Oz CLI +### Warp Factories + +[Warp Factories](/factories/) builds on the primitives described on this page to run persistent, multi-agent development workflows. A factory coordinates specialized cloud agents that move each work item through triage, specification, implementation, and review. It's in Early Access — [request access](https://www.warp.dev/factories/request-access) to use it with your team. -The [Oz CLI](/reference/cli/) is the **headless interface** for running agents in non-interactive mode. It's commonly used in CI, scripts, and server environments where there is no interactive UI. For interactive workflows, use the [agent](/agents/) embedded in Warp's desktop app. +--- + +### CLI + +The [{VARS.WARP_AGENT_CLI}](/reference/cli/) is the **headless interface** for running agents in non-interactive mode. It's commonly used in CI, scripts, and server environments where there is no interactive UI. For interactive workflows, use the [agent](/agents/) embedded in Warp's desktop app. A key property of the CLI is that it is **cloud-connected**. Even when an agent is started on a local machine or in CI, it reports progress to Warp’s servers. This enables team visibility, session sharing (where supported), and programmatic tracking through the API. @@ -58,7 +73,7 @@ Use the CLI when: * An external system is orchestrating runs (for example GitHub Actions, custom automation, incident tooling). * You want task observability and auditing without requiring Warp desktop. -#### How it fits in the Oz Platform +#### How the CLI fits into cloud agent runs Depending on the command, the CLI typically: @@ -88,7 +103,7 @@ The orchestrator: * Runs on Warp's servers (cloud control plane). * Creates tasks when triggers fire (integrations, schedules, API calls, or explicit starts). * Tracks lifecycle state (created → running → completed/failed) and associated metadata. -* Exposes task lifecycle operations via the [Oz CLI](/reference/cli/) and a [REST API](/reference/api-and-sdk/) (create tasks, query history, and inspect status/outputs). +* Exposes task lifecycle operations via the [{VARS.WARP_AGENT_CLI}](/reference/cli/) and a [REST API](/reference/api-and-sdk/) (create tasks, query history, and inspect status/outputs). * Powers SDKs (TypeScript/Python) for programmatic usage on top of the orchestrator API. * Supports [multi-agent orchestration](/platform/orchestration/) for parent/child workflows, fan-out, and review swarms. @@ -133,9 +148,9 @@ Environments are recommended when: --- -### Oz API and SDK +### API and SDK -The Oz [Agent API](/reference/api-and-sdk/) is the HTTP interface to the Oz Platform. It lets you create and inspect cloud agent tasks from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app. +The {VARS.WARP_AUTOMATION_PLATFORM} [Agent API](/reference/api-and-sdk/) is the HTTP interface to the {VARS.WARP_AUTOMATION_PLATFORM}. It lets you create and inspect cloud agent tasks from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app. **What you can do with the API** @@ -143,9 +158,9 @@ The Oz [Agent API](/reference/api-and-sdk/) is the HTTP interface to the Oz Plat * Monitor execution by listing tasks and tracking state transitions over time (for example: `QUEUED` → `INPROGRESS` → `SUCCEEDED/FAILED`). * Inspect results and provenance by fetching a task’s full details, including the original prompt, creator/source metadata, session link, and resolved agent configuration. -**Oz SDKs** +**SDKs** -Oz provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDKs](https://github.com/warpdotdev/oz-sdk-typescript) that wrap the Oz API with: +Warp provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDKs](https://github.com/warpdotdev/oz-sdk-typescript) that wrap the {VARS.API_SDK_NAME} with: * Typed requests/responses (autocomplete, fewer schema mistakes) * Built-in retries and timeouts (with per-request overrides) @@ -182,7 +197,7 @@ With Warp hosting: With self-hosting: * The agent runs on customer-managed infrastructure. -* Oz orchestrator still manages lifecycle and observability. +* The {VARS.WARP_AUTOMATION_PLATFORM} orchestrator still manages lifecycle and observability. * This is used when teams want code and execution to remain on their own systems rather than being cloned or executed in Warp's cloud. :::note @@ -218,7 +233,7 @@ Examples of context extracted by first-party integrations: #### Custom integrations -With custom integrations, you own the webhook and event-handling logic. Your system receives an event, applies any filtering or enrichment you need, and then calls the Oz API (directly or via an SDK) to create a task. The resulting task is still a full cloud agent run — observable, manageable, and auditable like any other. +With custom integrations, you own the webhook and event-handling logic. Your system receives an event, applies any filtering or enrichment you need, and then calls the API (directly or via an SDK) to create a task. The resulting task is still a full cloud agent run — observable, manageable, and auditable like any other. Custom integrations are a good fit when: @@ -283,17 +298,10 @@ Warp supports centralized configuration so these settings apply consistently reg This is especially useful when the same workflow can be triggered from multiple places (for example Slack, CI, and schedules). Instead of duplicating setup across systems, teams can keep configuration in one place and reuse it across triggers. -### Using the Oz Platform with or without the Warp app - -[Cloud agents](/platform/) do not require Warp's desktop terminal. Teams can operate cloud agent workflows using: - -* [Oz CLI](/reference/cli/) — run agents from scripts, CI, or the terminal -* [Oz web app](/platform/oz-web-app/) — visual interface for managing runs, schedules, environments, and integrations from any browser, including mobile -* [Session sharing](/agents/local-agents/session-sharing/) — attach to running tasks to monitor or steer -* [Management UI](/platform/managing-cloud-agents/) — view agent activity and run history -* [APIs and SDKs](/reference/api-and-sdk/) — programmatic access for custom integrations - -**If your team also uses Warp’s terminal, you gain an additional workflow:** +### Where to go next -* Tasks launched via the CLI can be handed off into an interactive session for review, edits, or continuation. -* This is useful when you want a human checkpoint (final edits, validation, merge decisions) without losing the audit trail from the cloud agent run. +* [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. +* [Warp Factories](/factories/) — build a software factory on these primitives. +* [Environments](/platform/environments/) — define the toolchain and repos a run executes against. +* [{VARS.API_SDK_NAME}](/reference/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 58acab47f..50d1f16f0 100644 --- a/src/content/docs/platform/oz-web-app.mdx +++ b/src/content/docs/platform/oz-web-app.mdx @@ -1,21 +1,22 @@ --- -title: Oz web app for cloud agents +title: "{{WEB_APP}} for cloud agents" description: >- - Use the Oz web app to manage cloud agents, view runs, create schedules, and + Use the {{WEB_APP}} to manage cloud agents, view runs, create schedules, and configure environments and integrations from any browser or mobile device. sidebar: - label: "Oz web app" + label: "{{WEB_APP}}" --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; -The [Oz web app](https://oz.warp.dev) provides a visual interface for managing cloud agents. You can start runs, browse agents and skills, create schedules, configure environments, and set up integrations—all without installing Warp or using the CLI. +The {VARS.WEB_APP} provides a visual interface for managing cloud agents. You can start runs, browse agents and skills, create schedules, configure environments, and set up integrations—all without installing Warp or using the CLI. :::note -The Oz web app works on mobile devices, so you can monitor and manage your cloud agents from anywhere. +The {VARS.WEB_APP} works on mobile devices, so you can monitor and manage your cloud agents from anywhere. ::: -Watch this short demo to create an environment and run an agent using the Oz web app: - +Watch this short demo to create an environment and run an agent using the {VARS.WEB_APP}: + ## Quick reference @@ -28,7 +29,7 @@ Watch this short demo to create an environment and run an agent using the Oz web ## When to use the web app -The Oz web app is ideal when you want to: +The {VARS.WEB_APP} is ideal when you want to: * **Monitor agent activity** — View runs, check status, and inspect outputs from any device * **Start quick runs** — Dispatch agents without opening a terminal @@ -37,17 +38,17 @@ The Oz 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 [Oz CLI](/reference/cli/) or [API](/reference/api-and-sdk/). +For scripting, automation, and CI/CD workflows, use the [{VARS.WARP_AGENT_CLI}](/reference/cli/) or [API](/reference/api-and-sdk/). ## Getting started -When you first sign in to the Oz web app, you'll see a guided onboarding flow that helps you get started based on your goals. +When you first sign in to the {VARS.WEB_APP}, you'll see a guided onboarding flow that helps you get started based on your goals. -The onboarding asks "What brings you to Oz?" and offers three paths: +The onboarding asks "What brings you to the {VARS.WARP_AUTOMATION_PLATFORM}?" and offers three paths: * **Create an agent automation** — Walks you through setting up a scheduled agent, integration-triggered agent, or other automation * **Run Cloud Agents in Warp** — Opens the Warp app (or takes you to the download page) to run cloud agents interactively -* **Build an app that uses agents** — Links to the [Oz Platform](/platform/overview/) docs for using the CLI, SDK, or API +* **Build an app that uses agents** — Links to the [{VARS.WARP_AUTOMATION_PLATFORM}](/platform/overview/) docs for using the CLI, SDK, or API You can skip onboarding at any time to go directly to the Runs page. @@ -82,7 +83,7 @@ To start a new run: ### Inspecting orchestrated runs -The Oz web app renders [multi-agent orchestrations](/platform/orchestration/) as nested rows on the **Runs** page, so you can follow parent and child execution together. +The {VARS.WEB_APP} renders [multi-agent orchestrations](/platform/orchestration/) as nested rows on the **Runs** page, so you can follow parent and child execution together. Open a parent run from the Runs page. When the run has children, the detail pane adds a **Sub-agents** tab next to **Details**: @@ -147,7 +148,7 @@ To create a skill for agents:
Creating a skill in the Oz web app.
-After the PR is merged, refresh skills so the new skill appears in the Oz web app. +After the PR is merged, refresh skills so the new skill appears in the {VARS.WEB_APP}. ## Schedules @@ -225,7 +226,7 @@ The **Integrations** page (`/integrations`) lets you configure first-party integ ### Available integrations -
IntegrationDescription
SlackTag @Oz in messages or threads to trigger agents directly from Slack conversations
LinearTag @Oz on issues to trigger agents from your issue tracker
GitHubMention @oz-agent on issues, pull requests, and review comments to trigger agents from GitHub
+
IntegrationDescription
SlackTag @warp in messages or threads to trigger agents directly from Slack conversations
LinearTag @warp on issues to trigger agents from your issue tracker
GitHubMention @warp-agent on issues, pull requests, and review comments to trigger agents from GitHub
![The Integrations page in the Oz web app.](../../../assets/agent-platform/oz-web-app-integrations.png) @@ -250,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 -* [Oz CLI](/reference/cli/) — Command-line interface for running agents -* [Oz API & SDK](/reference/api-and-sdk/) — Programmatic access to 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 diff --git a/src/content/docs/platform/quickstart.mdx b/src/content/docs/platform/quickstart.mdx index 6a264a517..b597b592c 100644 --- a/src/content/docs/platform/quickstart.mdx +++ b/src/content/docs/platform/quickstart.mdx @@ -7,8 +7,9 @@ description: >- sidebar: label: "Quickstart" --- +import { VARS } from '@data/vars'; -**Cloud agents** run in a remote environment and can be triggered from events, schedules, integrations, or manually. This enables scaling agents off your laptop, automating development tasks, and building apps on top of agents. Oz handles the orchestration, execution, and observability. +**Cloud agents** run in a remote environment and can be triggered from events, schedules, integrations, or manually. This enables scaling agents off your laptop, automating development tasks, and building apps on top of agents. The {VARS.WARP_AUTOMATION_PLATFORM} handles the orchestration, execution, and observability. Cloud agents can run interactively (where you steer them in real-time) or autonomously (as background tasks). Each run creates a persistent session that your team can inspect, share, and query through the Warp app, the CLI, web app, or API. @@ -27,7 +28,7 @@ This guide walks you through running your first cloud agent with an environment Before you begin, make sure you have: * **Warp desktop app** - Download from the [Warp website](https://www.warp.dev) -* **Warp account** - Create an account from the [Oz web app](https://oz.warp.dev) +* **Warp account** - Create an account from the {VARS.WEB_APP} :::note New to Warp? You'll get credits to try cloud agents. You need at least 20 credits available to run cloud agents and integrations. @@ -84,8 +85,8 @@ You can continue conversing with the agent in real-time, watch its progress, and You can view details of your agent's run, including commands executed, files changed, and environment used, several different ways: * In the Warp app, open the [conversations panel](/agents/local-agents/interacting-with-agents/#conversation-panel) to see all your agent runs. * Click the session link in your terminal output. -* Go to the [Oz web app](https://oz.warp.dev) and navigate to the **Runs** tab. -* Access from mobile via the [Oz web app](/platform/oz-web-app/). +* Go to the {VARS.WEB_APP} and navigate to the **Runs** tab. +* Access from mobile via the [{VARS.WEB_APP}](/platform/oz-web-app/). **Breaking it down:** Every cloud agent run is auto-tracked. You get a shareable link, a run record, and full visibility into what the agent did. You or your teammates can watch the agent's progress in real-time and even steer it if needed. The run record persists after completion so you can review it later. @@ -101,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 [Oz CLI quickstart](/reference/cli/quickstart/) for CLI-based workflows. +**Prefer using the CLI?** See the [{VARS.WARP_AGENT_CLI} quickstart](/reference/cli/quickstart/) for CLI-based workflows. --- @@ -110,10 +111,10 @@ Follow the prompts to save your task definition. Once created, you can run it ag Now that you've run your first cloud agent, try these next steps: * [**Schedule recurring work**](/platform/triggers/scheduled-agents-quickstart/) - Create a scheduled agent for maintenance tasks like dependency checks, cleanup, or triage. -* [**Trigger agents from Slack or Linear**](/platform/integrations/quickstart/) - Connect Oz to team tools so mentions and issue updates can launch cloud agent runs. +* [**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 Oz API or SDKs. +* [**Build programmatic automations**](/reference/api-and-sdk/quickstart/) - Start cloud agent runs from your own systems with the {VARS.API_SDK_NAME}. For example, schedule a recurring agent from the CLI: diff --git a/src/content/docs/platform/runners.mdx b/src/content/docs/platform/runners.mdx index 70b33fe32..e37047646 100644 --- a/src/content/docs/platform/runners.mdx +++ b/src/content/docs/platform/runners.mdx @@ -6,6 +6,7 @@ description: >- Runners define the OS, architecture, instance size, and sandbox image cloud agents run on, managed with the {{WARP_AGENT_CLI}}. --- +import { VARS } from '@data/vars'; 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. @@ -24,7 +25,7 @@ What runners give you: * **Flexible OS targets** – Run agents on Linux with a custom Docker image. macOS runners are in limited preview. * **Independent of environments** – Override an environment's default runner per run without changing the environment itself. -## How runners fit into the Oz Platform +## How runners fit into cloud agent runs A runner is the compute layer for a cloud agent run. When a run starts, Warp provisions a sandbox on the runner's shape, then prepares the workspace defined by the environment (cloning repos and executing setup commands) before the agent begins. @@ -36,7 +37,7 @@ Each environment has a default runner. Specifying a runner for a run overrides t ## Managing runners with the CLI -Use the [Oz CLI](/reference/cli/) to create, list, update, and delete runners. Runner commands require an authenticated CLI—see the [CLI quickstart](/reference/cli/quickstart/) to get set up. +Use the [{VARS.WARP_AGENT_CLI}](/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. ### Create a runner @@ -117,4 +118,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. -* [Oz CLI reference](/reference/cli/) – Full command-line reference for the Oz platform. +* [{VARS.WARP_AGENT_CLI} reference](/reference/cli/) – Full command-line reference for runners and every other cloud agent command. diff --git a/src/content/docs/platform/secrets.mdx b/src/content/docs/platform/secrets.mdx index 76bf48a56..48e427b8b 100644 --- a/src/content/docs/platform/secrets.mdx +++ b/src/content/docs/platform/secrets.mdx @@ -6,6 +6,7 @@ description: >- Securely store, scope, and inject credentials for Warp cloud agents across CLI, Slack, Linear, and scheduled runs—without ever exposing secret values. --- +import { VARS } from '@data/vars'; Cloud agents often need to interact with external systems such as APIs, databases, cloud providers, or internal tooling. To do this safely, Warp provides Warp-managed **agent secrets**, a secure way to store, scope, and inject credentials into cloud agent runs without exposing secret values to users or logs. @@ -82,13 +83,13 @@ Personal secrets belong to an **individual user**. --- -## Creating secrets in the Oz web app +## Creating secrets in the web app -The [Oz web app](/platform/oz-web-app/) provides a guided side pane for creating Warp-managed secrets. Use it when you want a point-and-click flow without leaving the browser; the CLI flow below remains available for scripting and automation. +The [{VARS.WEB_APP}](/platform/oz-web-app/) provides a guided side pane for creating Warp-managed secrets. Use it when you want a point-and-click flow without leaving the browser; the CLI flow below remains available for scripting and automation. To create a secret in the web app: -1. In the Oz web app (oz.warp.dev), open the **Secrets** page. +1. In the {VARS.WEB_APP} ({VARS.WEB_APP_URL}), open the **Secrets** page. 2. Click **Add secret** to open the **Add secret** side pane. 3. Enter a **Name** (for example, `OPENAI_API_KEY`). This becomes the environment variable name injected into runs. 4. Enter the **Value**. The value is encrypted in your browser before it is sent to the server; Warp never sees the plaintext. @@ -100,7 +101,7 @@ The new secret appears in the Secrets list immediately. Its value is never reada --- -## Managing agent secrets with the Oz CLI +## Managing agent secrets with the CLI Secrets are managed using the `oz secret` command family. @@ -221,7 +222,7 @@ Which secrets an agent receives depends on how the agent was triggered. When an agent is triggered by a specific user, such as: -* Oz CLI +* {VARS.WARP_AGENT_CLI} * Slack mentions * Linear updates @@ -257,9 +258,9 @@ A [cloud environment](/platform/environments/) can declare its own list of secre #### Attach secrets to an environment -Use the environment form in the [Oz web app](/platform/oz-web-app/) to attach secrets to an environment: +Use the environment form in the [{VARS.WEB_APP}](/platform/oz-web-app/) to attach secrets to an environment: -1. In the Oz web app (oz.warp.dev), open the **Environments** page. +1. In the {VARS.WEB_APP} ({VARS.WEB_APP_URL}), open the **Environments** page. 2. Click an existing environment to edit it, or click **New environment** to create one. 3. In the environment form, open the **Secrets** section. 4. Select the team and personal secrets the environment should contribute to each run. Only secret names already in your scope are selectable; values are never displayed. @@ -281,7 +282,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 [Oz API & SDK reference](/reference/api-and-sdk/) for the exact field and shape. +Run-level scoping is exposed through the public REST API on the run config. See the [{VARS.API_SDK_NAME} reference](/reference/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 index 34a4714a4..e0c346c05 100644 --- a/src/content/docs/platform/self-hosting/index.mdx +++ b/src/content/docs/platform/self-hosting/index.mdx @@ -2,9 +2,10 @@ title: Self-hosting overview description: >- Run cloud agents on your own infrastructure. Choose between a managed - worker daemon orchestrated by Oz or unmanaged CLI-based execution you + worker daemon orchestrated by the {{WARP_AUTOMATION_PLATFORM}} 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. @@ -20,14 +21,14 @@ Self-hosting lets your team run cloud agent workloads on your own infrastructure 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** — Oz orchestrates agent runs. You run the `oz-agent-worker` daemon on your infrastructure; it connects to Oz and waits for work. Slack mentions, Linear comments, schedules, 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. Oz provides session tracking and observability for each run, but does not start or stop agents for you. +* **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 mentions, Linear comments, schedules, 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** | Oz (Slack, Linear, schedules, API, `run-cloud`) | Your system (CI, cron, scripts) | +| **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 | @@ -46,12 +47,12 @@ If your security requirement is "repository clones and execution must stay on ou With any self-hosted architecture: -* **Agent runs are tracked and steerable** — View status, metadata, and session transcripts in the [Oz dashboard](https://oz.warp.dev), the Warp app, or via the [API/SDK](/reference/api-and-sdk/). Authorized teammates can attach to running sessions to monitor or steer agents. +* **Agent runs are tracked and steerable** — View status, metadata, and session transcripts in the {VARS.DASHBOARD}, 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. BYOLLM currently applies to interactive (local) agents; cloud agent support is coming. +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. ::: --- @@ -67,7 +68,7 @@ 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 Oz to handle starting and stopping agents** (from Slack, the web interface, the Warp app, schedules, or the API)? +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?** @@ -99,13 +100,13 @@ The managed architecture supports three backends for task execution: ## Managed architecture -With the managed architecture, you run the `oz-agent-worker` daemon on your infrastructure. The daemon connects to Oz's backend, waits for tasks to be assigned to it, and executes those tasks on its host using one of three backends: +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 Oz — it can remotely start agents via Slack, Linear, the [Oz web app](https://oz.warp.dev), 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. +The managed architecture enables full orchestration by the {VARS.WARP_AUTOMATION_PLATFORM} — it can remotely start agents via Slack, Linear, the {VARS.WEB_APP}, 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 @@ -158,7 +159,7 @@ All tasks created through that integration route to your self-hosted worker. ### From the API and SDKs -When creating a run via the [Oz API](/reference/api-and-sdk/), include `worker_host` in the config: +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 \ @@ -175,7 +176,7 @@ curl -X POST https://app.warp.dev/api/v1/agent/run \ ### From the web UI -When creating a run, schedule, or integration in the [Oz web app](https://oz.warp.dev), select your self-hosted worker from the host dropdown. +When creating a run, schedule, or integration in the {VARS.WEB_APP}, select your self-hosted worker from the host dropdown. --- @@ -197,9 +198,9 @@ Musl-based Docker images (such as Alpine Linux) are not supported as task images Self-hosted runs have the same observability as Warp-hosted runs: -* **Oz dashboard** — View task status, history, and metadata from the [Oz web app](https://oz.warp.dev). +* **Run history** — View task status, history, and metadata in the {VARS.DASHBOARD}, hosted in the {VARS.WEB_APP}. * **Session sharing** — Authorized teammates can attach to running tasks to monitor progress. -* **APIs and SDKs** — Query task history and build monitoring using the [Oz API](/reference/api-and-sdk/). +* **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. diff --git a/src/content/docs/platform/self-hosting/managed-direct.mdx b/src/content/docs/platform/self-hosting/managed-direct.mdx index e1b744e94..a2cef140a 100644 --- a/src/content/docs/platform/self-hosting/managed-direct.mdx +++ b/src/content/docs/platform/self-hosting/managed-direct.mdx @@ -1,13 +1,14 @@ --- title: "Managed: Direct backend" description: >- - Run the Oz managed worker with the Direct backend to execute cloud agent + Run the {{WARP_AUTOMATION_PLATFORM}} managed worker with the Direct backend to execute cloud agent tasks directly on the host, without Docker or Kubernetes. sidebar: label: "Managed: Direct" --- +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. Oz still orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); the worker just runs the agent in a per-task workspace on its own filesystem. +Run the `oz-agent-worker` daemon with the **Direct backend** — 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/). @@ -38,8 +39,8 @@ 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 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 [Oz web app](https://oz.warp.dev/settings) so the worker can authenticate to Oz. 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}** 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 {VARS.WEB_APP} 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. --- @@ -47,7 +48,7 @@ The Direct backend does not provide per-task container isolation. Each task runs ### 1. Set your API key -Export the API key so the worker can authenticate to Oz: +Export the API key so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}: ```bash export WARP_API_KEY="your_agent_api_key" @@ -70,7 +71,7 @@ backend: workspace_root: "/var/lib/oz/workspaces" ``` -**Expected outcome:** The worker connects to Oz and begins listening for tasks. Each assigned task runs in a freshly-created subdirectory of `workspace_root`. +**Expected outcome:** The worker connects to the {VARS.WARP_AUTOMATION_PLATFORM} and begins listening for tasks. Each assigned task runs in a freshly-created subdirectory of `workspace_root`. --- diff --git a/src/content/docs/platform/self-hosting/managed-docker.mdx b/src/content/docs/platform/self-hosting/managed-docker.mdx index 85e26543c..1b083678f 100644 --- a/src/content/docs/platform/self-hosting/managed-docker.mdx +++ b/src/content/docs/platform/self-hosting/managed-docker.mdx @@ -1,13 +1,14 @@ --- title: "Managed: Docker backend" description: >- - Run the Oz managed worker daemon with the Docker backend to execute cloud + Run the {{WARP_AUTOMATION_PLATFORM}} managed worker daemon with the Docker backend to execute cloud agent tasks in isolated containers on your infrastructure. sidebar: label: "Managed: Docker" --- +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 Oz (Slack, Linear, schedules, API, `oz agent run-cloud`). +Run the `oz-agent-worker` daemon with the **Docker backend** — the default managed path. Each agent task runs in an isolated Docker container spawned from the worker, 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/). @@ -26,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 [Oz web app](https://oz.warp.dev/settings) so the worker can authenticate to Oz. 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 {VARS.WEB_APP} 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. :::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. @@ -46,7 +47,7 @@ docker info ## Set your API key -Export your agent API key so the worker can authenticate to Oz: +Export your agent API key so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}: ```bash export WARP_API_KEY="your_agent_api_key" @@ -70,7 +71,7 @@ docker run -v /var/run/docker.sock:/var/run/docker.sock \ warpdotdev/oz-agent-worker --worker-id "my-worker" ``` -**Expected outcome:** The worker connects to Oz and logs that it's listening for tasks. +**Expected outcome:** The worker connects to the {VARS.WARP_AUTOMATION_PLATFORM} and logs that it's listening for tasks. ### Option 2: Go install @@ -88,9 +89,9 @@ go build -o oz-agent-worker ./oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` -Once started, the worker connects to Oz, waits for tasks routed to its `--worker-id`, runs each task in an isolated Docker container, and reports status and results back. The worker automatically reconnects if the connection drops. +Once started, the worker connects to the {VARS.WARP_AUTOMATION_PLATFORM}, waits for tasks routed to its `--worker-id`, runs each task in an isolated Docker container, and reports status and results back. The worker automatically reconnects if the connection drops. -You can run multiple workers with the same `--worker-id` for redundancy — Oz distributes tasks across connected workers. +You can run multiple workers with the same `--worker-id` for redundancy — the {VARS.WARP_AUTOMATION_PLATFORM} distributes tasks across connected workers. --- diff --git a/src/content/docs/platform/self-hosting/managed-kubernetes.mdx b/src/content/docs/platform/self-hosting/managed-kubernetes.mdx index cddee1a43..43b44cc2c 100644 --- a/src/content/docs/platform/self-hosting/managed-kubernetes.mdx +++ b/src/content/docs/platform/self-hosting/managed-kubernetes.mdx @@ -1,13 +1,14 @@ --- title: "Managed: Kubernetes backend" description: >- - Deploy the Oz managed worker into a Kubernetes cluster with the included + Deploy the {{WARP_AUTOMATION_PLATFORM}} managed worker into a Kubernetes cluster with the included Helm chart. Each agent task runs as a Kubernetes Job in your cluster. sidebar: label: "Managed: Kubernetes" --- +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. Oz orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); your cluster provides the compute, scheduling, and policy enforcement. +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 self-hosted workers](/platform/self-hosting/managed-docker/#routing-runs-to-self-hosted-workers). @@ -38,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 [Oz web app](https://oz.warp.dev/settings) so the worker can authenticate to Oz. 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 {VARS.WEB_APP} 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. --- diff --git a/src/content/docs/platform/self-hosting/monitoring.mdx b/src/content/docs/platform/self-hosting/monitoring.mdx index a66d52f47..2188d57e9 100644 --- a/src/content/docs/platform/self-hosting/monitoring.mdx +++ b/src/content/docs/platform/self-hosting/monitoring.mdx @@ -3,12 +3,13 @@ title: Self-hosted worker monitoring sidebar: label: "Monitoring" description: >- - Monitor self-hosted Oz workers with OpenTelemetry metrics. Export to + Monitor self-hosted {{WARP_AUTOMATION_PLATFORM}} workers with OpenTelemetry metrics. Export to Prometheus, OTLP, or console to track worker health, task throughput, and saturation. --- +import { VARS } from '@data/vars'; -The `oz-agent-worker` daemon exports infrastructure-level metrics over [OpenTelemetry](https://opentelemetry.io/), giving your team real-time visibility into worker health, task throughput, and capacity. Combine these metrics with the [Oz dashboard](https://oz.warp.dev) for full observability across both the orchestration plane and your self-hosted compute. +The `oz-agent-worker` daemon exports infrastructure-level metrics over [OpenTelemetry](https://opentelemetry.io/), giving your team real-time visibility into worker health, task throughput, and capacity. Combine these metrics with the {VARS.DASHBOARD} for full observability across both the orchestration plane and your self-hosted compute. :::note When running the binary directly, metrics export follows the [OpenTelemetry autoexport](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/exporters/autoexport) default — if `OTEL_METRICS_EXPORTER` is unset, the worker pushes OTLP to `localhost:4318`. Set `OTEL_METRICS_EXPORTER=none` to disable export. The Helm chart is opt-in: it only enables export when `metrics.enabled=true`. @@ -136,7 +137,7 @@ metrics: All metrics use the `oz_worker_` prefix. Each worker process emits a distinct set of series, identified by the resource attributes `service.name`, `service.version`, `worker.id`, and `worker.backend`. -* **`oz_worker_connected`** (gauge) — `1` while the worker has an active WebSocket connection to Oz's backend, `0` otherwise. +* **`oz_worker_connected`** (gauge) — `1` while the worker has an active WebSocket connection to the {VARS.WARP_AUTOMATION_PLATFORM}'s backend, `0` otherwise. * **`oz_worker_tasks_active`** (gauge / UpDownCounter) — Tasks currently executing on this worker. * **`oz_worker_tasks_max_concurrent`** (gauge) — Configured concurrency limit (`0` means unlimited). * **`oz_worker_tasks_claimed_total`** (counter) — Total tasks accepted since process start. diff --git a/src/content/docs/platform/self-hosting/quickstart.mdx b/src/content/docs/platform/self-hosting/quickstart.mdx index 8894cfbff..67deebce4 100644 --- a/src/content/docs/platform/self-hosting/quickstart.mdx +++ b/src/content/docs/platform/self-hosting/quickstart.mdx @@ -1,16 +1,17 @@ --- title: Self-hosting quickstart description: >- - Get a managed self-hosted Oz worker running on Docker and route your first + Get a managed self-hosted {{WARP_AUTOMATION_PLATFORM}} worker running on Docker and route your first cloud agent run to it in under 10 minutes. sidebar: label: "Quickstart" --- +import { VARS } from '@data/vars'; Run your first cloud agent on your own infrastructure in ~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting. :::note -This quickstart sets up the [managed architecture](/platform/self-hosting/#managed-architecture), where Oz 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](/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. ::: --- @@ -19,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 [Oz web app](https://oz.warp.dev/settings) so the worker can authenticate to Oz. 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 CLI** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). +* **An agent API key** — Create one in the {VARS.WEB_APP} 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). --- @@ -30,7 +31,7 @@ _~10 minutes_ ### 1. Export your API key -Export the agent API key so the worker container can authenticate to Oz automatically: +Export the agent API key so the worker container can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM} automatically: ```bash export WARP_API_KEY="your_agent_api_key" @@ -46,7 +47,7 @@ docker run -v /var/run/docker.sock:/var/run/docker.sock \ warpdotdev/oz-agent-worker --worker-id "my-worker" ``` -**Expected outcome:** The worker connects to Oz and begins listening for tasks. You should see log output confirming the connection (something like `Connected to Oz` / `Waiting for tasks`). +**Expected outcome:** The worker connects to the {VARS.WARP_AUTOMATION_PLATFORM} and begins listening for tasks. You should see log output confirming the connection (something like `Connected to Oz` / `Waiting for tasks`). :::caution For production deployments, pin to a specific image digest (e.g., `warpdotdev/oz-agent-worker@sha256:...`) instead of the `latest` tag. @@ -54,17 +55,17 @@ For production deployments, pin to a specific image digest (e.g., `warpdotdev/oz ### 3. Route a run to your worker -In a separate terminal on any machine with the Oz CLI, route a cloud agent run to your worker by passing `--host` with the worker ID you chose: +In a separate terminal on any machine with the {VARS.WARP_AGENT_CLI}, route a cloud agent run to your worker by passing `--host` with the worker ID you chose: ```bash oz agent run-cloud --prompt "List the files in the current directory" --host "my-worker" ``` -**Expected outcome:** Oz 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 [Oz dashboard](https://oz.warp.dev) with status moving from `QUEUED` → `INPROGRESS` → `SUCCEEDED`. +**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 {VARS.DASHBOARD} with status moving from `QUEUED` → `INPROGRESS` → `SUCCEEDED`. ### 4. Verify the run -Open the [Oz dashboard](https://oz.warp.dev), 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. +Open the {VARS.DASHBOARD}, find the new task, and confirm the session transcript shows the agent running against your worker. You can attach to the session at any time via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer it. --- @@ -73,7 +74,7 @@ Open the [Oz dashboard](https://oz.warp.dev), find the new task, and confirm the * [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. * [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 Oz web app. +* [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. diff --git a/src/content/docs/platform/self-hosting/security-and-networking.mdx b/src/content/docs/platform/self-hosting/security-and-networking.mdx index 77e02b9d3..5b22cef4a 100644 --- a/src/content/docs/platform/self-hosting/security-and-networking.mdx +++ b/src/content/docs/platform/self-hosting/security-and-networking.mdx @@ -1,7 +1,7 @@ --- title: Security and networking description: >- - Security model, data boundaries, and network requirements for self-hosted Oz + Security model, data boundaries, and network requirements for self-hosted {{WARP_AUTOMATION_PLATFORM}} cloud agents — including per-backend considerations and BYOLLM. --- @@ -29,7 +29,7 @@ Self-hosted execution keeps repository clones, source files, build artifacts, ru * LLM inference requests and responses, which include code context from the agent's interactions. :::note -While repositories are cloned and stored only on your infrastructure, code content appears in session transcripts and LLM prompts as part of normal agent operation. All data routed through Warp's backend is covered by [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. +Repositories are cloned and stored only on your infrastructure, but code content can still appear in session transcripts, artifacts, and LLM prompts as part of normal agent operation. Warp does not persistently store your source code or train on it. For retention with customer-supplied inference, see [LLM inference and BYOLLM](#llm-inference-and-byollm). ::: --- @@ -104,9 +104,7 @@ See [GitLab](/platform/integrations/gitlab/) and [Bitbucket](/platform/integrati ## LLM inference and BYOLLM -LLM inference routes through Warp's backend, which has [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements with all contracted model providers. Enterprise teams that need full control over 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. - -BYOLLM currently applies to interactive (local) agents; cloud agent BYOLLM support is coming. +LLM inference routes through Warp's backend. With Warp-managed inference, requests go to contracted providers covered by [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. With customer-supplied inference, provider-side retention follows your team's agreement with that provider. Enterprise teams that want inference routed and billed through their own accounts can use [team-managed model keys and endpoints](/enterprise/enterprise-features/team-managed-keys-and-endpoints/) or [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/); cloud agent support varies by provider, so check each provider's page. --- diff --git a/src/content/docs/platform/self-hosting/troubleshooting.mdx b/src/content/docs/platform/self-hosting/troubleshooting.mdx index 6c6bc3c05..f1546b947 100644 --- a/src/content/docs/platform/self-hosting/troubleshooting.mdx +++ b/src/content/docs/platform/self-hosting/troubleshooting.mdx @@ -1,11 +1,12 @@ --- title: Self-hosting troubleshooting description: >- - Diagnose and fix common problems with self-hosted Oz worker daemons across + Diagnose and fix common problems with self-hosted {{WARP_AUTOMATION_PLATFORM}} worker daemons across Docker, Kubernetes, and Direct backends. sidebar: label: "Troubleshooting" --- +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. @@ -45,19 +46,19 @@ The steps below apply to the [managed architecture](/platform/self-hosting/#mana **Fix:** -1. Install the Oz 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](/reference/cli/#installing-the-cli). 2. If the CLI isn't on `PATH`, set `oz_path` in the config file to the absolute path of the `oz` binary. --- ## Worker won't connect -**Cause:** The API key is invalid, expired, or the host cannot reach Oz's backend. +**Cause:** The API key is invalid, expired, or the host cannot reach the {VARS.WARP_AUTOMATION_PLATFORM}'s backend. **Fix:** 1. Confirm your API key is correct, not expired, and has team scope. -2. Regenerate the API key in **Settings** > **Cloud platform** > **Oz Cloud API Keys** if you suspect it's invalid. +2. Regenerate the API key in **Settings** > **Cloud platform** > **{VARS.WARP_AUTOMATION_PLATFORM} Cloud API Keys** if you suspect it's invalid. 3. Ensure the host has outbound internet access to `oz.warp.dev:443`. 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. @@ -102,7 +103,7 @@ See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide. **Fix (all backends):** -1. Review task logs in the [Oz dashboard](https://oz.warp.dev) or via [session sharing](/agents/local-agents/session-sharing/). +1. Review task logs in the {VARS.DASHBOARD} or via [session sharing](/agents/local-agents/session-sharing/). 2. Use `--no-cleanup` to keep the container, Job, or workspace around for inspection after failure. 3. Use `--log-level debug` to see detailed execution logs. 4. Ensure the worker machine or cluster has sufficient resources (CPU, memory, disk). @@ -123,7 +124,7 @@ See [Monitoring](/platform/self-hosting/monitoring/) for the full setup guide. ### Direct backend (task failures) -1. Verify the Oz CLI is accessible. +1. Verify the {VARS.WARP_AGENT_CLI} is accessible. 2. Verify the workspace root directory has write permissions for the user running the worker. --- diff --git a/src/content/docs/platform/self-hosting/unmanaged.mdx b/src/content/docs/platform/self-hosting/unmanaged.mdx index 39966f573..49cf1d397 100644 --- a/src/content/docs/platform/self-hosting/unmanaged.mdx +++ b/src/content/docs/platform/self-hosting/unmanaged.mdx @@ -6,11 +6,12 @@ description: >- sidebar: label: "Unmanaged" --- +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 Oz 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](/platform/self-hosting/#managed-architecture) instead. ::: ## When to use unmanaged @@ -28,12 +29,12 @@ Unmanaged works on any platform Warp supports (Linux, macOS, Windows) with no de _~5 minutes_ -No Docker, no worker daemon, no environment required — just the Oz CLI on any host that can reach the internet. +No Docker, no worker daemon, no environment required — just the {VARS.WARP_AGENT_CLI} on any host that can reach the internet. ### Prerequisites -* **The Oz 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 [Oz web app](https://oz.warp.dev/settings). 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](/reference/cli/#installing-the-cli) for platform-specific instructions. +* **A Warp API key** — For automation, create an agent API key in the {VARS.WEB_APP}. See [API Keys](/reference/cli/api-keys/) for personal vs. agent guidance. ### 1. Authenticate @@ -51,7 +52,7 @@ Invoke `oz agent run` in the directory where you want the agent to operate. The oz agent run --prompt "Refactor the authentication module" --share team ``` -**Expected outcome:** The agent starts immediately in the current working directory, and a tracked session appears in the [Oz dashboard](https://oz.warp.dev). +**Expected outcome:** The agent starts immediately in the current working directory, and a tracked session appears in the {VARS.DASHBOARD}. ### 3. Control sharing @@ -120,9 +121,9 @@ Whether Kubernetes pods provide sufficient sandboxing for agents depends on your Unmanaged agents are tracked on Warp's backend. Each run creates a persistent session that your team can: -* **View** in the [Oz dashboard](https://oz.warp.dev). +* **View** in the {VARS.DASHBOARD}. * **Attach to** via [Agent Session Sharing](/agents/local-agents/session-sharing/) to monitor or steer. -* **Query** through the [Oz API/SDK](/reference/api-and-sdk/) for custom dashboards or monitoring. +* **Query** through the [{VARS.API_SDK_NAME}](/reference/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. @@ -135,5 +136,5 @@ Unmanaged runs don't ship with the bundled declarations script, so end-of-run wo * [Self-hosting overview](/platform/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. -* [Oz CLI](/reference/cli/) — Full CLI reference for `oz agent run` and related commands. +* [{VARS.WARP_AGENT_CLI}](/reference/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/skills-as-agents.mdx b/src/content/docs/platform/skills-as-agents.mdx index ce131df7e..e2e7d5ed7 100644 --- a/src/content/docs/platform/skills-as-agents.mdx +++ b/src/content/docs/platform/skills-as-agents.mdx @@ -2,10 +2,11 @@ title: Skills as Agents description: >- Run agents based on skills for consistent, repeatable workflows. Use skills - with local or cloud agents from the CLI, Oz web app, API, or on a schedule. + with local or cloud agents from the CLI, {{WEB_APP}}, API, or on a schedule. sidebar: label: "Skills as agents" --- +import { VARS } from '@data/vars'; You can start an agent from a [skill](/agents/capabilities/skills/)—a reusable set of instructions that defines what the agent should do. When you run an agent based on a skill, the skill provides the base prompt and behavior, while you supply additional context for that specific run. @@ -48,10 +49,10 @@ For cloud agent runs (`oz agent run-cloud`), skills are discovered from reposito 1. **Create a skill** in your repository (see [Creating skills](/agents/capabilities/skills/#creating-skills)) 2. **Add the repository** to an environment -3. **The skill appears** in the Agents list in the Oz web app +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 [Oz API](/reference/api-and-sdk/) reference for details. +You can also list available skills programmatically using the `GET /agent` endpoint. See the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) reference for details. ::: ### Extra skill directories in cloud runs @@ -78,20 +79,20 @@ The Warp Agent harness reads `WARP_SKILL_DIRS` directly. For [third-party harnes You can start an agent from a skill using multiple entry points. -### Oz web app +### Web app -Use the [Oz web app](/platform/oz-web-app/) to run skill-based agents from a visual interface. From the web app, you can: +Use the [{VARS.WEB_APP}](/platform/oz-web-app/) to run skill-based agents from a visual interface. From the web app, you can: * Browse all skills available from your environments on the **Agents** page * View suggested agents from Warp's public [oz-skills repository](https://github.com/warpdotdev/oz-skills) * Start a new run by selecting a skill, environment, and prompt * Create scheduled agents that run skills on a cron schedule -For a complete walkthrough of the web app interface, see [Oz Web App](/platform/oz-web-app/). +For a complete walkthrough of the web app interface, see [{VARS.WEB_APP}](/platform/oz-web-app/). ### CLI -Use the `--skill` flag with the Oz CLI: +Use the `--skill` flag with the {VARS.WARP_AGENT_CLI}: ```sh # Run locally with a skill @@ -143,7 +144,7 @@ oz schedule create \ --prompt "Scan for dead code and unused feature flags. Open a PR with removals." ``` -You can also create schedules from the [Oz web app](/platform/oz-web-app/) using the **New schedule** action. +You can also create schedules from the [{VARS.WEB_APP}](/platform/oz-web-app/) using the **New schedule** action. For full scheduling documentation, see [Scheduled Agents](/platform/triggers/scheduled-agents/). @@ -151,7 +152,7 @@ For full scheduling documentation, see [Scheduled Agents](/platform/triggers/sch ## Suggested Skills -The [Oz web app](/platform/oz-web-app/) displays suggested agents from the public [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. These are pre-built skills that demonstrate common use cases and can be used as starting points for your own workflows. +The [{VARS.WEB_APP}](/platform/oz-web-app/) displays suggested agents from the public [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. These are pre-built skills that demonstrate common use cases and can be used as starting points for your own workflows. Suggested skills appear on the Agents page under the **Suggested** filter. @@ -162,6 +163,6 @@ Suggested skills appear on the Agents page under the **Suggested** filter. * [Skills](/agents/capabilities/skills/) — How to create skills and skill file format * [Environments](/platform/environments/) — Configure repositories and runtime context for cloud agents * [Scheduled Agents](/platform/triggers/scheduled-agents/) — Run agents automatically on a cron schedule -* [Oz Web App](/platform/oz-web-app/) — Visual interface for managing cloud agents -* [Oz CLI](/reference/cli/) — Command-line interface for running agents -* [Oz API & SDK](/reference/api-and-sdk/) — Programmatic access to cloud agents +* [{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 diff --git a/src/content/docs/platform/software-factory.mdx b/src/content/docs/platform/software-factory.mdx deleted file mode 100644 index a946fe9d5..000000000 --- a/src/content/docs/platform/software-factory.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Software factory -description: >- - A software factory uses specialized agents to take new issues through triage, spec, implementation, and review, producing pull requests for your team to merge. -sidebar: - label: "Software factory" ---- - -A software factory is a development system where specialized agents take new issues through triage, spec, implementation, and review, producing pull requests for your team to merge. Instead of every developer executing every step — reading each issue, writing specs, implementing changes, reviewing output — agents execute and humans review. The team's job shifts from doing the work to defining the process and raising the quality bar over time. - -Warp uses this model to build Warp itself. The [agent dashboard at build.warp.dev](https://build.warp.dev) shows the work Warp's agents are tackling across the open source repository in real time. - -Read on to learn about the two loops that make up a software factory, the agent roles involved, and how to decide if this model is right for your team. - -## The two loops - -A software factory has two loops that work together. - -**The inner loop** is the execution loop: a triage agent, spec agent, implementation agent, and reviewer agent work in sequence, turning a new issue into a pull request for human review. - -**The outer loop** is the improvement loop: a [scheduled agent](/platform/triggers/scheduled-agents/) reviews past inner-loop runs, observes where maintainers made corrections, and opens a pull request to update the skill files that drive the inner-loop agents. Over time, the factory gets better without anyone manually rewriting prompts. - -The inner loop ships software. The outer loop improves the factory that ships it. - -## Agent roles - -A software factory delegates work to specialized agents, each with a narrow responsibility: - -* **Triage agent** - Reviews new issues for clarity and completeness. Labels issues as ready to implement, needs more information, or a duplicate. Flags open questions for the reporter before implementation begins, so the backlog stays clean and actionable. -* **Spec agent** - Drafts a product spec (user stories and acceptance criteria) and a tech spec (implementation strategy, relevant code locations, and edge cases). The specs serve as the blueprint for the implementation agent and the review criteria for the reviewer agent. -* **Implementation agent** - Builds against approved specs. Uses spec context to make better architectural decisions and raises a blocked status when specs are missing or ambiguous rather than guessing. -* **Reviewer agent** - Checks the implementation against specs, code conventions, and security requirements. Posts inline review comments and validates that acceptance criteria are met before a human reviewer opens the PR. - -The [`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) repository is the complete reference implementation with all four roles deployed in a working system. - -## How it works - -Each agent role is backed by a **skill**, a markdown file checked into a Git repository that defines the agent's behavior: what to check, how to classify results, what to output, and when to escalate. Skills are versioned, reviewed as code changes, and composable across repositories. - -The inner loop runs when a new issue is filed: - -1. A webhook or GitHub Action triggers the triage agent. The agent runs in a cloud [environment](/platform/environments/), analyzes the issue, and applies labels and comments. -2. When the issue is labeled `ready-to-spec`, the spec agent creates `PRODUCT.md` and `TECH.md` in a `specs/` directory in the repository. -3. A human reviews and approves the specs. -4. When the implementation label is applied, the implementation agent opens a PR that includes the spec files alongside the code. - -Oz orchestrates each agent as a cloud run. Every run has its own environment (repository checkout, secrets, toolchain), its own permissions, and a session link your team can use to inspect what the agent did, steer it mid-run, or use [Handoff](/platform/handoff/) to move work back to a local session. For parent/child fan-out and review swarms across those roles, see [Multi-agent orchestration](/platform/orchestration/). - -The outer loop runs on a [schedule](/platform/triggers/scheduled-agents/), not in response to events. - -A scheduled cloud agent collects signals from past inner-loop runs and generates a diff to the relevant skill files. That diff goes through a normal pull request review before merging. Humans decide what improves; agents propose it. - -## When to use a software factory - -A software factory is a strong fit when: - -* Your team has a repeatable development workflow: a backlog of issues with consistent shape, and a process you can write down and teach to an agent. -* The cost of a missed edge case in agent output is recoverable. The agent opens a pull request, not a deploy, so humans stay in control of what ships. -* You want to scale throughput without scaling headcount linearly, or you want to move faster on a large backlog with a small team. - -Start with one agent role. Most teams start with a triage agent, which is the simplest loop to close correctly. A well-groomed backlog immediately benefits every developer on the team. Add spec, implementation, and reviewer agents as you build confidence in each step. - -## Reference implementation - -[`warpdotdev/oz-for-oss`](https://github.com/warpdotdev/oz-for-oss) is Warp's open-source software factory platform for GitHub-hosted repositories. It includes a Vercel webhook layer, GitHub App, and skill files for every agent role in the loop: triage, spec, implementation, review, verification, and self-improvement. Get started with the [onboarding guide](https://github.com/warpdotdev/oz-for-oss/blob/main/docs/onboarding.md). - -## Related pages - -* [Build a triage agent for your issue backlog](/guides/agent-workflows/build-a-triage-agent) — Start the series with the simplest agent role. -* [Write product and tech specs with agents](/guides/agent-workflows/write-product-and-tech-specs-with-agents) — Write specs that guide implementation agents. -* [Set up your software factory](/guides/agent-workflows/set-up-a-software-factory) — Connect the four roles into a working loop. -* [Run a software factory in the cloud](/guides/agent-workflows/run-a-software-factory-in-the-cloud) — Move the loop off your laptop with Oz. -* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent) — Add the outer improvement loop. -* [Multi-agent orchestration](/platform/orchestration/) — Coordinate specialized agent roles as parent and child runs. -* [Skills](/agents/capabilities/skills) — How skill files work in Warp and Oz. -* [Cloud agents overview](/platform) — Setting up cloud agents on Oz. -* [Deployment patterns](/platform/deployment-patterns) — Common architectures for cloud agent deployment. 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 cf4d74010..aa09bcda0 100644 --- a/src/content/docs/platform/team-access-billing-and-identity.mdx +++ b/src/content/docs/platform/team-access-billing-and-identity.mdx @@ -7,6 +7,7 @@ description: >- sidebar: label: "Access, billing, and identity" --- +import { VARS } from '@data/vars'; This page explains how access to cloud agents works for both individual users and teams, how billing and credits apply, and how Warp maps user identities across integrations. @@ -37,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 Oz API +* Run agents using `oz agent run-cloud` or the {VARS.API_SDK_NAME} * Credits are drawn from your Warp credits (including cloud agent credits, when applicable) * Agents execute on Warp-hosted infrastructure @@ -61,12 +62,12 @@ A [Warp team](/knowledge-and-collaboration/teams/) is a group of users who share **What teams enable:** -* **Integrations** - Create Slack, Linear, and Jira integrations that all team members can use, and enable the [GitHub integration](/platform/integrations/github/) so teammates can start agents with an `@oz-agent` mention +* **Integrations** - Create Slack, Linear, and Jira integrations that all team members can use, and enable the [GitHub integration](/platform/integrations/github/) so teammates can start agents with an `@warp-agent` mention * **Shared configuration** - Team-level environments, secrets, and settings * **Self-hosting** - Run agents on your own infrastructure (Enterprise only) * **Team visibility** - Shared observability into agent runs and history -Integrations are created at the team level, not per-user. Once a Slack or Linear integration is installed, everyone on your Warp team can use **@Oz** in the connected workspace. The integration behaves the same way for all teammates, and everyone shares the same underlying environment configuration. The GitHub integration is team-level in the same way: once an admin enables the GitHub organization, any teammate with a connected GitHub account can start a run by mentioning **@oz-agent**. +Integrations are created at the team level, not per-user. Once a Slack or Linear integration is installed, everyone on your Warp team can use **@warp** in the connected workspace. The integration behaves the same way for all teammates, and everyone shares the same underlying environment configuration. The GitHub integration is team-level in the same way: once an admin enables the GitHub organization, any teammate with a connected GitHub account can start a run by mentioning **@warp-agent**. When someone triggers a cloud agent for the first time, Warp may prompt them to grant GitHub authorization so the agent can open pull requests or push branches under their identity. This allows each run to use the correct permissions without requiring additional setup from an admin. @@ -97,11 +98,11 @@ Warp needs a reliable way to know which person a cloud agent run is acting for, * Slack uses a dedicated account-linking flow to map a Slack user to their Warp account. This is the recommended path for Slack-triggered agents, since it doesn’t rely on email matching. * Linear currently maps identities using email address matching. Your Linear email must match your Warp account email for Warp to correctly attribute and scope agent runs. -* The [GitHub integration](/platform/integrations/github/) maps the GitHub account that mentioned `@oz-agent` to the Warp account that connected it, rather than by email. Until a teammate connects their GitHub account, Warp replies in the thread with a link to connect instead of starting a run. That binding sets run attribution, team ownership, and billing; the run's GitHub access comes from the app installation instead. +* The [GitHub integration](/platform/integrations/github/) maps the GitHub account that mentioned `@warp-agent` to the Warp account that connected it, rather than by email. Until a teammate connects their GitHub account, Warp replies in the thread with a link to connect instead of starting a run. That binding sets run attribution, team ownership, and billing; the run's GitHub access comes from the app installation instead. * Each teammate must authorize GitHub before an agent can write PRs or push branches on their behalf * For Slack-triggered, Linear-triggered, and locally triggered runs, agents operate using the GitHub permissions of the triggering user -This ensures runs are scoped to what the user is allowed to see and modify, and that ownership of PRs remains clear across teams and repositories. The two exceptions are agent API key runs with [team GitHub authorization](#team-github-authorization) and runs started from an `@oz-agent` mention, which both authenticate as the Oz by Warp GitHub App installation. +This ensures runs are scoped to what the user is allowed to see and modify, and that ownership of PRs remains clear across teams and repositories. The two exceptions are agent API key runs with [team GitHub authorization](#team-github-authorization) and runs started from an `@warp-agent` mention, which both authenticate as the Oz by Warp GitHub App installation. --- @@ -123,7 +124,7 @@ The GitHub App token gives the agent access to the repositories included in the :::note There are two places you may encounter this installation flow: - * During the first-time experience for Oz, when you connect your GitHub account. + * During the first-time experience for the {VARS.WARP_AUTOMATION_PLATFORM}, when you connect your GitHub account. * When you click **Configure access on GitHub** in the repository selector while creating an environment. Each installation is scoped to a single GitHub organization or personal account — you can install the app to multiple orgs separately. @@ -141,7 +142,7 @@ There are two places you may encounter this installation flow:
Enabled GitHub Orgs setting in the Admin Panel.
-3. **Use an agent API key.** Tasks initiated with an agent API key on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. On GitHub, commits and pull requests are opened by the Oz by Warp GitHub App rather than any individual user; in the Oz dashboard, the run is attributed to the bound [cloud agent](/platform/agents/). +3. **Use an agent API key.** Tasks initiated with an agent API key on the team now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. On GitHub, commits and pull requests are opened by the Oz by Warp GitHub App rather than any individual user; in the {VARS.DASHBOARD}, the run is attributed to the bound [cloud agent](/platform/agents/). ### How this relates to environments @@ -156,9 +157,9 @@ The environment configuration and the **Enabled GitHub Orgs** setting in the Adm Team GitHub authorization is complementary to the existing personal token flow: -* **User-triggered runs** (personal API key, Slack, Linear, Warp app) - The agent authenticates as Oz acting on the triggering user's behalf. PRs and commits are attributed to that user. -* **Agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. On GitHub, PRs and commits are attributed to the Oz by Warp GitHub App rather than any individual user. In the Oz dashboard, the run is attributed to the bound [cloud agent](/platform/agents/), which controls run filtering and audit attribution on the Warp side. -* **[GitHub integration](/platform/integrations/github/) runs** (an `@oz-agent` mention on an issue or pull request) - The agent authenticates as the installation that delivered the event, so its repository access and its GitHub attribution match the agent API key flow. In the Oz dashboard the run is still attributed to the teammate who wrote the mention, and their team is billed. +* **User-triggered runs** (personal API key, Slack, Linear, Warp app) - The agent authenticates using the triggering user's personal token. PRs and commits are attributed to that user. +* **Agent API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. On GitHub, PRs and commits are attributed to the Oz by Warp GitHub App rather than any individual user. In the {VARS.DASHBOARD}, the run is attributed to the bound [cloud agent](/platform/agents/), which controls run filtering and audit attribution on the Warp side. +* **[GitHub integration](/platform/integrations/github/) runs** (an `@warp-agent` mention on an issue or pull request) - The agent authenticates as the installation that delivered the event, so its repository access and its GitHub attribution match the agent API key flow. In the {VARS.DASHBOARD} the run is still attributed to the teammate who wrote the mention, and their team is billed. These flows can coexist on the same team. Personal tokens are still used for user-triggered runs from a personal API key, Slack, Linear, and the Warp app, and the GitHub App installation token is used for agent API key runs and for GitHub integration runs. @@ -176,14 +177,14 @@ To change which repositories the GitHub App can access, edit the app installatio #### Slack / Linear -Installing the Oz app gives Warp access to the Slack channels or Linear teams where the app is installed. +Installing the {VARS.WARP_AUTOMATION_PLATFORM} app gives Warp access to the Slack channels or Linear teams where the app is installed. **When a run is triggered, Warp receives:** * The content of the tagged thread or issue * Relevant surrounding context used to build the agent prompt -Warp stores only the content required for the agent to complete its task. You can message @Oz directly, mention it in channels, or tag it on specific issues depending on the integration. +Warp stores only the content required for the agent to complete its task. You can message @warp directly, mention it in channels, or tag it on specific issues depending on the integration. #### GitHub @@ -201,7 +202,7 @@ Warp’s behavior in GitHub is defined by two layers of control: * Are included in the environment configuration * Are accessible to both the GitHub app and the triggering user. -Runs triggered by an `@oz-agent` mention through the [GitHub integration](/platform/integrations/github/) follow the first layer only. Warp receives the content of the issue, pull request, or review thread that carried the mention, including the recent comments and the diff of a commented file, and the run authenticates with the GitHub App installation that delivered the event. Cloning, commits, branches, pull requests, and status comments all use that installation's access rather than the mentioning user's, so the installation's repository selection is the only boundary on what those runs can reach. The repository that triggered the mention is cloned alongside any repositories in the configured environment, and only the repositories that installation covers are available to the agent. +Runs triggered by an `@warp-agent` mention through the [GitHub integration](/platform/integrations/github/) follow the first layer only. Warp receives the content of the issue, pull request, or review thread that carried the mention, including the recent comments and the diff of a commented file, and the run authenticates with the GitHub App installation that delivered the event. Cloning, commits, branches, pull requests, and status comments all use that installation's access rather than the mentioning user's, so the installation's repository selection is the only boundary on what those runs can reach. The repository that triggered the mention is cloned alongside any repositories in the configured environment, and only the repositories that installation covers are available to the agent. --- diff --git a/src/content/docs/platform/triggers/index.mdx b/src/content/docs/platform/triggers/index.mdx index 0f585068b..a16756bc2 100644 --- a/src/content/docs/platform/triggers/index.mdx +++ b/src/content/docs/platform/triggers/index.mdx @@ -4,20 +4,21 @@ description: >- Configure triggers to run cloud agents automatically based on schedules or events. --- +import { VARS } from '@data/vars'; -Triggers allow you to run cloud agents automatically without manual intervention. You can set up agents to run on schedules, in response to webhooks, or through other automation patterns. +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. 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 Oz CLI, or the API, start with [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). +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/). ## 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 Oz CLI. +* **[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. * **[Integrations](/platform/integrations/)** - Trigger agents from external services like Slack, Linear, or Jira. -* **[GitHub](/platform/integrations/github/)** - Mention `@oz-agent` on an issue, pull request, or review comment to start an agent that replies in the thread. +* **[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. -After a trigger fires, track and review the resulting runs across your team from the [Agent Management Panel and Oz web app Runs page](/platform/managing-cloud-agents/), where you can filter by source, status, day, or creator. +After a trigger fires, track and review the resulting runs across your team from the [Agent Management Panel and {VARS.WEB_APP} Runs page](/platform/managing-cloud-agents/), where you can filter by source, status, day, or creator. diff --git a/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx b/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx index 507477c50..cdb5081ab 100644 --- a/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx +++ b/src/content/docs/platform/triggers/scheduled-agents-quickstart.mdx @@ -9,7 +9,7 @@ sidebar: import VideoEmbed from '@components/VideoEmbed.astro'; import { VARS } from '@data/vars'; -Scheduled agents are cloud agents that run on a recurring cron schedule, handling recurring tasks automatically without manual triggers. This guide walks you through setting up an agent that triages your GitHub bug reports every week, checks whether each issue has enough detail to investigate, and posts follow-up comments when information is missing. You'll use a prebundled skill and the Oz web app; no CLI or custom code required. +Scheduled agents are cloud agents that run on a recurring cron schedule, handling recurring tasks automatically without manual triggers. This guide walks you through setting up an agent that triages your GitHub bug reports every week, checks whether each issue has enough detail to investigate, and posts follow-up comments when information is missing. You'll use a prebundled skill and the {VARS.WEB_APP}; no CLI or custom code required. Watch this short demo of creating and testing a scheduled agent: @@ -25,7 +25,7 @@ Watch this short demo of creating and testing a scheduled agent: ## 1. Set up a scheduled agent -1. From the [Schedules page](https://oz.warp.dev/schedules) in the Oz web app, click **New schedule**. +1. From the Schedules page in the {VARS.WEB_APP}, click **New schedule**. 2. Enter a schedule name, e.g. `Weekly bug report triage`. 3. Expand **General**, then under **Agent**, choose the identity that will run the schedule. **Quick run** is the default and runs every execution as you. See [Run identity and pull request authorship](#run-identity-and-pull-request-authorship) before you decide. 4. Under **Skills**, select **github-bug-report-triage**. @@ -33,7 +33,7 @@ Watch this short demo of creating and testing a scheduled agent: 6. Under **Frequency**, choose a preset or enter a custom cron expression (e.g., `0 9 * * 1` for every Monday at 9 AM). 7. Click **Create schedule**. -**Breaking it down:** The schedule lives in Oz's cloud infrastructure. Unlike a local cron job, it fires even when your machine is off. Each run starts a fresh, isolated session with no state carried over from previous executions, and every run is tracked and reviewable in the [Oz web app](/platform/oz-web-app/). +**Breaking it down:** The schedule lives in the {VARS.WARP_AUTOMATION_PLATFORM}'s cloud infrastructure. Unlike a local cron job, it fires even when your machine is off. Each run starts a fresh, isolated session with no state carried over from previous executions, and every run is tracked and reviewable in the [{VARS.WEB_APP}](/platform/oz-web-app/). ### Run identity and pull request authorship @@ -54,12 +54,12 @@ The {VARS.WARP_AGENT_CLI} has no **Agent** flag, so a schedule created with `oz To verify your setup without waiting for the schedule to fire, trigger a test run now: -1. From the [Schedules page](https://oz.warp.dev/schedules) in the Oz web app, click the schedule you just created. +1. From the Schedules page in the {VARS.WEB_APP}, click the schedule you just created. 2. Click ⋮ and select **Run now**, then click **Run** to confirm. -Your test run will appear under **All** on the [Runs page](https://oz.warp.dev/runs). Once the schedule fires on its cron, those runs will appear under **Recurring**. +Your test run will appear under **All** on the Runs page. Once the schedule fires on its cron, those runs will appear under **Recurring**. -Runs are also accessible from the conversation panel view in the Warp app and on mobile via the Oz web app. +Runs are also accessible from the conversation panel view in the Warp app and on mobile via the {VARS.WEB_APP}. :::note **Prefer the CLI?** See [Scheduled Agents](/platform/triggers/scheduled-agents/) for `oz schedule create`, `oz schedule list`, and full schedule management commands. To use a custom skill instead of a prebundled one, see [Skills as Agents](/platform/skills-as-agents/). @@ -70,6 +70,6 @@ Runs are also accessible from the conversation panel view in the Warp app and on ## Next steps * **Choose the right unattended trigger** - Compare schedules, Slack, Linear, GitHub Actions, CLI, and API workflows in [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). -* **Trigger agents from your tools** - Connect Oz to Slack or Linear to trigger agents from mentions or issue updates. See [Integrations Quickstart](/platform/integrations/quickstart/). +* **Trigger agents from your tools** - Connect the {VARS.WARP_AUTOMATION_PLATFORM} to Slack or Linear to trigger agents from mentions or issue updates. See [Integrations Quickstart](/platform/integrations/quickstart/). * **Manage and refine your schedule** - Change the frequency, swap skills, or pause and resume the schedule. See [Scheduled Agents](/platform/triggers/scheduled-agents/) for the full reference. * **Share with your team** - Schedules and environments are shared across your Warp team, so everyone benefits automatically. diff --git a/src/content/docs/platform/triggers/scheduled-agents.mdx b/src/content/docs/platform/triggers/scheduled-agents.mdx index 1e88fdc54..f9e8b71f6 100644 --- a/src/content/docs/platform/triggers/scheduled-agents.mdx +++ b/src/content/docs/platform/triggers/scheduled-agents.mdx @@ -15,9 +15,9 @@ Warp's Scheduled Agents let you run cloud agents automatically on a **recurring Scheduled Agents run in the background on Warp’s infrastructure. Each run starts from a clean session, executes a fixed prompt, and produces its own task and session history that can be inspected after the fact. -For a guided, no-CLI walkthrough that creates a recurring agent from the Oz web app, see the [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/). This page is the full reference for managing schedules with the Oz CLI. +For a guided, no-CLI walkthrough that creates a recurring agent from the {VARS.WEB_APP}, see the [Scheduled Agents quickstart](/platform/triggers/scheduled-agents-quickstart/). This page is the full reference for managing schedules with the {VARS.WARP_AGENT_CLI}. -If you're deciding whether to use a schedule, Slack or Linear trigger, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). +If you're deciding whether to use a schedule, Slack or Linear trigger, GitHub Actions, the {VARS.WARP_AGENT_CLI}, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/). --- @@ -53,11 +53,11 @@ Because each run is isolated, Scheduled Agents are safe to use for tasks that be --- -### Scheduling agents with the Oz CLI +### Scheduling agents with the CLI -Oz scheduled agents are managed through the Oz `schedule` family of CLI commands. +{VARS.WARP_AUTOMATION_PLATFORM} scheduled agents are managed through the {VARS.WARP_AUTOMATION_PLATFORM} `schedule` family of CLI commands. -All scheduling operations require the Oz CLI and an authenticated session. +All scheduling operations require the {VARS.WARP_AGENT_CLI} and an authenticated session. #### Creating a schedule diff --git a/src/content/docs/platform/viewing-cloud-agent-runs.mdx b/src/content/docs/platform/viewing-cloud-agent-runs.mdx index 7902cdd24..12cb6f3b1 100644 --- a/src/content/docs/platform/viewing-cloud-agent-runs.mdx +++ b/src/content/docs/platform/viewing-cloud-agent-runs.mdx @@ -7,8 +7,9 @@ sidebar: label: "Viewing cloud agent runs" --- 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 [Oz 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}](/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. 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. diff --git a/src/content/docs/platform/warp-hosting.mdx b/src/content/docs/platform/warp-hosting.mdx index 13cf9741d..3b7ee8010 100644 --- a/src/content/docs/platform/warp-hosting.mdx +++ b/src/content/docs/platform/warp-hosting.mdx @@ -5,10 +5,11 @@ description: >- sidebar: label: "Warp-hosted agents" --- +import { VARS } from '@data/vars'; Warp's managed infrastructure lets your team run cloud agent workloads in fast, secure sandboxes. -Use Warp-hosted agents to quickly get started with Oz, without needing to configure compute resources or maintain services. +Use Warp-hosted agents to quickly get started with the {VARS.WARP_AUTOMATION_PLATFORM}, without needing to configure compute resources or maintain services. ## Sandbox environment @@ -50,5 +51,5 @@ Warp's hosted agents have network egress enabled by default. Outgoing requests m ## Related pages -* [Oz Platform](/platform/overview/) - Learn how Warp-hosted agents fit into the Oz Platform. +* [{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. diff --git a/src/content/docs/quickstart.mdx b/src/content/docs/quickstart.mdx index 09f707d98..980e0bc65 100644 --- a/src/content/docs/quickstart.mdx +++ b/src/content/docs/quickstart.mdx @@ -90,7 +90,7 @@ Learn more about [Autosuggestions](/terminal/command-completions/autosuggestions ## 5. Ask your first agent question -Everything you've done so far has been in **terminal mode**, running shell commands the way you normally would. Warp also has **Agent Mode**, a dedicated conversation view where you interact with Oz, Warp's built-in agent, using natural language. +Everything you've done so far has been in **terminal mode**, running shell commands the way you normally would. Warp also has **Agent Mode**, a dedicated conversation view where you interact with the Warp Agent, Warp's built-in agent, using natural language. Start an agent conversation by pressing `⌘↩` (macOS) or `Ctrl+Shift+Enter` (Windows/Linux). Then type a prompt: @@ -98,7 +98,7 @@ Start an agent conversation by pressing `⌘↩` (macOS) or `Ctrl+Shift+Enter` ( Explain the architecture of this project ``` -Oz reads your codebase, understands its structure, and responds with a context-aware explanation. From here you can ask follow-up questions, have Oz write or refactor code, debug errors, or run commands on your behalf — all within the same conversation. +The Warp Agent reads your codebase, understands its structure, and responds with a context-aware explanation. From here you can ask follow-up questions, have the Warp Agent write or refactor code, debug errors, or run commands on your behalf — all within the same conversation. :::note You don't always need to switch modes manually. If you type a natural-language prompt in terminal mode, Warp auto-detects it and offers to send it to an agent. diff --git a/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx b/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx index 1f246efb1..3bdfd4c2f 100644 --- a/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx +++ b/src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx @@ -5,10 +5,11 @@ description: >- and create draft PRs. --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; ### Turn production errors into draft PRs with Cloud Agents + TypeScript SDK - + :::note Example repository: [**Sentry monitor example repository**](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor) diff --git a/src/content/docs/reference/api-and-sdk/index.mdx b/src/content/docs/reference/api-and-sdk/index.mdx index e2dfd68d6..8c611490b 100644 --- a/src/content/docs/reference/api-and-sdk/index.mdx +++ b/src/content/docs/reference/api-and-sdk/index.mdx @@ -1,18 +1,19 @@ --- -title: "Oz API & SDK reference" +title: "{{API_SDK_NAME}} reference" sidebar: - label: "Oz API & SDK" + label: "{{API_SDK_NAME}}" description: >- - Create and inspect cloud agent runs over HTTP with the Oz API, or use the - Python and TypeScript SDKs for typed requests, retries, and error handling. + Create and inspect cloud agent runs over HTTP, or use the Python and + TypeScript SDKs for typed requests, retries, and error handling. --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; -The Oz API and SDKs let you create, monitor, and inspect cloud agent runs programmatically. Use the REST API from any HTTP client, or the official Python and TypeScript SDKs for typed requests, built-in retries, and structured error handling. The SDKs are ideal for CI pipelines, internal tools, and custom integrations. +The {VARS.API_SDK_NAME} lets you 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. -### Oz API +### API overview -The Oz API 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. +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. **With the API you can:** @@ -26,9 +27,9 @@ 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). ::: -### Oz SDK +### SDK overview -Oz provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs that wrap the Oz API 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.API_SDK_NAME} with: * **Typed requests and responses** (editor autocomplete, fewer schema mistakes) * **Built-in retries and timeouts** (with per-request overrides) @@ -37,7 +38,7 @@ Oz provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [ If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. - + **SDK vs raw REST** @@ -50,7 +51,7 @@ For the full SDK surface area and latest usage, refer to the GitHub repos: [**Py --- -## Oz API +## API reference ### REST API base URL @@ -135,11 +136,11 @@ The API shares a set of reusable models across endpoints. Detailed JSON schemas, --- -## Oz SDKs +## SDKs ### Python SDK -The Python SDK is the recommended way to call the Oz API from Python services and scripts. It provides: +The Python SDK is the recommended way to call the API from Python services and scripts. It provides: * Sync + async clients * Typed request/response models @@ -149,7 +150,7 @@ See the [**Python SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-python ### TypeScript SDK -The TypeScript SDK is the recommended way to call the Oz API from Node.js services and modern TS/JS runtimes. It provides: +The TypeScript SDK is the recommended way to call the API from Node.js services and modern TS/JS runtimes. It provides: * Fully typed params/responses * First-class error handling, retries/timeouts diff --git a/src/content/docs/reference/api-and-sdk/quickstart.mdx b/src/content/docs/reference/api-and-sdk/quickstart.mdx index 52d9b7721..00107985e 100644 --- a/src/content/docs/reference/api-and-sdk/quickstart.mdx +++ b/src/content/docs/reference/api-and-sdk/quickstart.mdx @@ -1,24 +1,25 @@ --- title: "API & SDK quickstart" description: >- - Create and monitor your first cloud agent run via the Oz API or SDK in ~5 + Create and monitor your first cloud agent run via the {{API_SDK_NAME}} in ~5 minutes. sidebar: label: "Quickstart" --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; -The Oz API 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.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. 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: - + --- ## Prerequisites -* **A Warp API key** - Create one in the [Oz web app](https://oz.warp.dev/settings) 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. -* **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don't have an environment yet, follow the [Cloud Agents Quickstart](/platform/quickstart/) first. +* **A Warp API key** - Create one in the {VARS.WEB_APP} and copy the raw value. Use a personal key if you want runs attributed to you, or an agent key to attribute runs to a [cloud agent](/platform/agents/). See [API Keys](/reference/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. --- @@ -48,7 +49,7 @@ curl -X POST https://app.warp.dev/api/v1/agent/run \ }' ``` -Replace `` with your environment ID. Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). +Replace `` with your environment ID. Find it with `oz environment list` on the {VARS.WARP_AGENT_CLI} or in the {VARS.WEB_APP}. :::note Prefer typed requests? The official [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) wrap the same API with typed models, retries, and error handling. @@ -85,13 +86,13 @@ curl "https://app.warp.dev/api/v1/agent/runs" \ Once the run reaches `SUCCEEDED`, the response includes a `session_link` — a direct URL to the full run transcript, including commands executed, files changed, and agent output. -You can also view and manage all runs in the [Oz dashboard](https://oz.warp.dev/runs). +You can also view and manage all runs in the {VARS.DASHBOARD}. --- ## Next steps -* **Read the full API reference** - [Oz API](/reference/api-and-sdk/) documents all endpoint parameters, query filters, and response schemas. +* **Read the full API reference** - [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) documents all endpoint parameters, query filters, and response schemas. * **Explore the SDKs** - [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) include typed request/response models, retries, and error handling. * **See a real-world example** - [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors. * **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/authentication-required.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/authentication-required.mdx index ec348aefd..37e3adcd9 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/authentication-required.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/authentication-required.mdx @@ -4,6 +4,7 @@ description: >- The API key in the request is invalid, expired, or missing. Generate a new key and update your client configuration. --- +import { VARS } from '@data/vars'; The `authentication_required` error occurs when the API request lacks valid authentication credentials. @@ -48,7 +49,7 @@ This error is returned when: ## How to resolve -1. Generate a new API key from the [Oz web app](https://oz.warp.dev) or via the Oz CLI. +1. Generate a new API key from the {VARS.WEB_APP} or via the {VARS.WARP_AGENT_CLI}. 2. Update your client configuration with the new key. 3. Retry the request. @@ -56,5 +57,5 @@ This error is returned when: ## Related -* [Oz API & SDK](/reference/api-and-sdk/) — API authentication -* [Oz Platform](/platform/overview/) — API key management +* [{VARS.API_SDK_NAME}](/reference/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/conflict.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/conflict.mdx index f13e52c50..489a0620a 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/conflict.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/conflict.mdx @@ -6,6 +6,7 @@ description: >- The request conflicts with the current state of the resource. Wait for the resource to reach the expected state and retry. --- +import { VARS } from '@data/vars'; The `conflict` error occurs when a request cannot be completed because the resource is in a state that conflicts with the requested operation. @@ -56,4 +57,4 @@ For task cancellation specifically, wait until the task moves from **pending** t ## Related * [Managing Cloud Agents](/platform/managing-cloud-agents/) — Viewing and managing agent tasks -* [Oz API & SDK](/reference/api-and-sdk/) — API reference for managing agent tasks +* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) — API reference for managing agent tasks diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx index e8f2a92fc..af4046131 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx @@ -1,12 +1,13 @@ --- title: Errors Overview description: >- - Reference for all error codes returned by the Oz platform API. Each error + Reference for all error codes returned by the {{API_SDK_NAME}}. Each error includes an HTTP status, machine-readable code, and actionable resolution steps. --- +import { VARS } from '@data/vars'; -When the Oz 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, a human-readable message, and metadata to help you diagnose and resolve the issue. +When the {VARS.API_SDK_NAME} encounters an error, it returns a structured JSON response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807). Every error response includes a machine-readable error code, a human-readable message, and metadata to help you diagnose and resolve the issue. --- @@ -86,6 +87,6 @@ When an error response includes a `trace_id`, you can include it when [contactin ## Related -* [Oz API & SDK](/reference/api-and-sdk/) — API reference for creating and managing agent tasks +* [{VARS.API_SDK_NAME}](/reference/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/integration-disabled.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-disabled.mdx index 1573fcebc..91cdccec5 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-disabled.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-disabled.mdx @@ -1,11 +1,12 @@ --- title: integration_disabled description: >- - The integration (Slack, Linear, etc.) is currently disabled in the Oz - settings. Enable it to continue. + The integration (Slack, Linear, etc.) is currently disabled in the + {{WARP_AUTOMATION_PLATFORM}} settings. Enable it to continue. --- +import { VARS } from '@data/vars'; -The `integration_disabled` error occurs when a task targets an integration that is currently disabled in the Oz settings. +The `integration_disabled` error occurs when a task targets an integration that is currently disabled in the {VARS.WARP_AUTOMATION_PLATFORM} settings. --- @@ -21,7 +22,7 @@ The `integration_disabled` error occurs when a task targets an integration that This error is returned when: -* A Slack message, Linear issue, or other integration event triggers a cloud agent, but the corresponding integration has been disabled in the Oz settings +* A Slack message, Linear issue, or other integration event triggers a cloud agent, but the corresponding integration has been disabled in the {VARS.WARP_AUTOMATION_PLATFORM} settings * The integration was previously active but has been turned off by a team admin --- @@ -43,7 +44,7 @@ This error is returned when: ## How to resolve -1. Go to the [Oz integrations page](https://oz.warp.dev/integrations). +1. Go to the {VARS.WARP_AUTOMATION_PLATFORM} integrations page. 2. Enable the integration that was disabled. 3. Retry the triggering event or task. @@ -52,4 +53,4 @@ This error is returned when: ## Related * [Integrations](/platform/integrations/) — Configuring Slack, Linear, and GitHub integrations -* [Oz Web App](/platform/oz-web-app/) — Managing integrations via the web interface +* [{VARS.WEB_APP}](/platform/oz-web-app/) — Managing integrations via the web interface diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx index 23d638cb0..24b249f9f 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/integration-not-configured.mdx @@ -4,6 +4,7 @@ description: >- The integration's setup is incomplete. Visit the setup URL to finish configuring the integration. --- +import { VARS } from '@data/vars'; The `integration_not_configured` error occurs when a task requires an integration whose setup has not been completed (for example, missing OAuth tokens or unfinished configuration steps). @@ -55,7 +56,7 @@ This error includes extra fields beyond the standard response format: ## How to resolve -1. Visit the `setup_url` provided in the response metadata (or go to the [Oz integrations page](https://oz.warp.dev/integrations)). +1. Visit the `setup_url` provided in the response metadata (or go to the {VARS.WARP_AUTOMATION_PLATFORM} integrations page). 2. Complete all setup steps for the integration. 3. Retry the triggering event or task. diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx index 86a83033e..dc807a2fd 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/invalid-request.mdx @@ -4,6 +4,7 @@ description: >- The request body is malformed, missing required fields, or contains invalid parameter values. --- +import { VARS } from '@data/vars'; The `invalid_request` error occurs when the API request is malformed or contains invalid parameters. @@ -57,4 +58,4 @@ The `detail` field in the response will describe the specific validation issue. ## Related -* [Oz API & SDK](/reference/api-and-sdk/) — API request format and parameters +* [{VARS.API_SDK_NAME}](/reference/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/reference/api-and-sdk/troubleshooting/errors/not-authorized.mdx index 5e7e1917a..964bbfc17 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/not-authorized.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/not-authorized.mdx @@ -4,6 +4,7 @@ description: >- The authenticated user or API key does not have permission to perform the requested operation. --- +import { VARS } from '@data/vars'; The `not_authorized` error occurs when the authenticated principal (user or API key) does not have sufficient permissions to perform the requested operation. @@ -55,4 +56,4 @@ This error is returned when: ## Related * [Access, Billing, and Identity](/platform/team-access-billing-and-identity/) — Permission model and identity -* [Oz API & SDK](/reference/api-and-sdk/) — API authentication and authorization +* [{VARS.API_SDK_NAME}](/reference/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/reference/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx index 8dae9b3c4..eaabaa540 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/operation-not-supported.mdx @@ -4,6 +4,7 @@ description: >- The requested operation is not supported for this resource or its current state. --- +import { VARS } from '@data/vars'; The `operation_not_supported` error occurs when you attempt an operation that is not currently supported for the given resource or its current state. @@ -56,4 +57,4 @@ This error is returned when: * [Cloud Agents Overview](/platform/) — How cloud agent tasks work * [Self-hosting](/platform/self-hosting/) — Self-hosted agent configuration -* [Oz API & SDK](/reference/api-and-sdk/) — API reference for managing agent tasks +* [{VARS.API_SDK_NAME}](/reference/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/reference/api-and-sdk/troubleshooting/errors/resource-not-found.mdx index 45cc276ab..e3f7f36f3 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-not-found.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/resource-not-found.mdx @@ -4,6 +4,7 @@ description: >- The requested resource (task, environment, schedule, agent, etc.) does not exist or has been deleted. --- +import { VARS } from '@data/vars'; The `resource_not_found` error occurs when a referenced resource cannot be found. This typically means the resource ID is incorrect, the resource has been deleted, or it belongs to a different team. @@ -48,7 +49,7 @@ The `detail` field in the response will describe which resource was not found. ## How to resolve 1. Verify the resource ID is correct and properly formatted. -2. Check that the resource has not been deleted (for example, via the [Oz web app](https://oz.warp.dev) or CLI). +2. Check that the resource has not been deleted (for example, via the {VARS.WEB_APP} or CLI). 3. Confirm the resource belongs to your team or that you have access to it. --- diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx index f183b8f89..097333f4f 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/index.mdx @@ -1,11 +1,12 @@ --- title: API Troubleshooting description: >- - Troubleshooting resources for the Oz API and SDK, including a full reference + Troubleshooting resources for the {{API_SDK_NAME}}, including a full reference for all platform error codes. --- +import { VARS } from '@data/vars'; -When the Oz platform API 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. +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 diff --git a/src/content/docs/reference/cli/agent-profiles.mdx b/src/content/docs/reference/cli/agent-profiles.mdx index 3fdf11751..179d02a75 100644 --- a/src/content/docs/reference/cli/agent-profiles.mdx +++ b/src/content/docs/reference/cli/agent-profiles.mdx @@ -1,13 +1,18 @@ --- title: Agent profiles description: >- - Use agent profiles with the Oz CLI to control what the agent can access, how + Use agent profiles with the {{WARP_AGENT_CLI}} to control what the agent can access, how it behaves, and where it can act. sidebar: label: "Agent Profiles" --- +import { VARS } from '@data/vars'; -Agent profiles control what the agent can do, how it behaves, and where it can act when running from the Oz 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. +:::caution +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: + +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. Agent profiles control three things: diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx index 4e45f1203..c93911586 100644 --- a/src/content/docs/reference/cli/api-keys.mdx +++ b/src/content/docs/reference/cli/api-keys.mdx @@ -1,12 +1,17 @@ --- -title: API keys for the Oz CLI +title: "API keys for the {{WARP_AGENT_CLI}}" description: >- - Create and manage API keys for authenticating the Oz CLI and cloud agents. + Create and manage API keys for authenticating the {{WARP_AGENT_CLI}} and cloud agents. sidebar: label: "API keys" --- +import { VARS } from '@data/vars'; -API keys let the Oz CLI and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments. +:::caution +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: + +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. ## Personal vs. agent keys @@ -17,11 +22,11 @@ Every API key is either a **personal API key** or an **agent API key**. ## Creating an API key -You can create an API key in either the [Oz web app](https://oz.warp.dev/settings) or the Warp app. Both surfaces produce keys that authenticate the CLI and SDK identically. +You can create an API key in either the {VARS.WEB_APP} or the Warp app. Both surfaces produce keys that authenticate the CLI and SDK identically. -### From the Oz web app (recommended) +### From the web app (recommended) -1. Open the [Oz web app settings page](https://oz.warp.dev/settings). +1. Open the {VARS.WEB_APP} settings page. 2. In the API keys section, click **Generate new token**. 3. Choose the type: * **Personal** — Tied to your individual Warp account. @@ -33,7 +38,7 @@ You can create an API key in either the [Oz web app](https://oz.warp.dev/setting ### From the Warp app 1. In the Warp app, click your profile photo in the top-right corner, then click **Settings**. -2. In the sidebar, expand **Cloud platform** and click **Oz Cloud API Keys**. +2. In the sidebar, expand **Cloud platform** and click **{VARS.WARP_AUTOMATION_PLATFORM} Cloud API Keys**. 3. In the API Keys section, click **+ Create API Key**. 4. Pick **Personal** for a personal key, or **Agent** / **Team** for an agent key tied to your team. (The toggle may still read **Team** in older versions of the desktop app.) 5. Name the key and choose an expiration (1 day, 30 days, 90 days, or never). @@ -86,13 +91,13 @@ API keys start with the prefix `wk-`. If your key doesn't have this prefix, it m ## Managing API keys -The [Oz web app settings page](https://oz.warp.dev/settings) and the Warp app's **Settings** > **Cloud platform** > **Oz Cloud API Keys** both list your active keys. Both surfaces show: +The {VARS.WEB_APP} settings page and the Warp app's **Settings** > **Cloud platform** > **{VARS.WARP_AUTOMATION_PLATFORM} Cloud API Keys** both list your active keys. Both surfaces show: * **Name** — The name you assigned when creating the key. * **Scope** — Personal keys show your user; agent keys show the cloud agent the key runs as. * **Expires at** — The key's expiration date, or "Never" if it doesn't expire. -The Warp app also shows additional metadata that isn't surfaced in the Oz web app: +The Warp app also shows additional metadata that isn't surfaced in the {VARS.WEB_APP}: * **Key** — A masked suffix (`wk-**xxxx`) to help identify the key. * **Created** — When the key was created. @@ -100,13 +105,13 @@ The Warp app also shows additional metadata that isn't surfaced in the Oz web ap ### Deleting API keys -To delete an API key, find it in either the Oz web app or the Warp app's API Keys list and click the delete icon next to the key. +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/). ## Manage API keys from the CLI -In addition to the web and Warp app surfaces, you can manage API keys directly with the [Oz 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}](/reference/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/reference/cli/artifacts.mdx index d8380416a..752cea237 100644 --- a/src/content/docs/reference/cli/artifacts.mdx +++ b/src/content/docs/reference/cli/artifacts.mdx @@ -6,8 +6,13 @@ description: >- sidebar: label: "Artifacts" --- +import { VARS } from '@data/vars'; -Artifacts are files that an agent produces during a run and uploads to Oz — 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. +:::caution +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: + +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. ## When to use artifacts @@ -17,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 [Oz API](/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`](/reference/cli/), or in the response from the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). ## `oz artifact get` @@ -73,5 +78,5 @@ oz artifact download "$ARTIFACT_UID" --out ./latest-report.html ## Related -* [Oz API & SDK](/reference/api-and-sdk/) - retrieve artifacts programmatically over HTTP. +* [{VARS.API_SDK_NAME}](/reference/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/reference/cli/federate.mdx index 7e92d5d19..f4059f598 100644 --- a/src/content/docs/reference/cli/federate.mdx +++ b/src/content/docs/reference/cli/federate.mdx @@ -6,6 +6,11 @@ description: >- sidebar: label: "Federated identity" --- +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). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: `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. @@ -35,7 +40,7 @@ oz federate issue-token \ ### Flags -* **`--run-id `** - The ID of the Oz run requesting the token. The token is bound to this run. +* **`--run-id `** - The ID of the {VARS.PLATFORM_RUN} requesting the token. The token is bound to this run. * **`--audience `** - The `aud` claim for the issued token. Set this to the value your cloud provider's identity pool expects (for example, an AWS IAM Identity Center audience or a GCP workload identity pool URL). * **`--duration `** - Requested token lifetime. Accepts human-readable durations like `15m`, `1h`, or `2h30m`. Defaults to `1h`. * **`--subject-template ...`** - Controls how the OIDC token's `sub` claim is formatted. Pass one or more components, which are joined to form the subject. Defaults to `principal` (for example, `user:my-user-id`). @@ -78,7 +83,7 @@ oz federate issue-token \ ## Using tokens with cloud providers -Once you have a token, exchange it for cloud credentials using your provider's standard OIDC federation flow. The exchange happens between the cloud provider and your script — Oz only issues the OIDC token. +Once you have a token, exchange it for cloud credentials using your provider's standard OIDC federation flow. The exchange happens between the cloud provider and your script — the {VARS.WARP_AUTOMATION_PLATFORM} only issues the OIDC token. A typical AWS flow: diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index 03838d7cb..a2076ce72 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -1,25 +1,26 @@ --- -title: Oz CLI reference +title: "{{WARP_AGENT_CLI}} reference" sidebar: - label: "Oz CLI" + label: "{{WARP_AGENT_CLI}}" description: >- - Use the Oz CLI to run, configure, and manage agents from the terminal. + Use the {{WARP_AGENT_CLI}} to run, configure, and manage agents from the terminal. --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { VARS } from '@data/vars'; -The Oz 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. - -:::note -**`warp-cli` is deprecated and has been replaced by `oz`.** If you have `warp-cli` installed, it will auto-update to `oz`. All the same commands are available, just replace `warp-cli` with `oz` in your scripts and workflows. +:::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). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. ::: -## What is the Oz CLI? +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. + +## What is the CLI? -The Oz CLI is the command-line tool that lets you run [Cloud Agents](/platform/) from anywhere, including terminals, scripts, automated systems, or services. +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**. -With the Oz CLI, you can: +With the {VARS.WARP_AGENT_CLI}, you can: * Run agents locally for development and debugging * Run agents on remote machines @@ -28,18 +29,18 @@ With the Oz CLI, you can: ## Installing the CLI -You can install the Oz CLI as part of the Warp desktop app, or as a standalone package. +You can install the {VARS.WARP_AGENT_CLI} as part of the Warp desktop app, or as a standalone package. ### Bundled with Warp -The Oz CLI is automatically distributed with the Warp desktop app and can be used right away in Warp. To make the CLI globally available, add it to your `PATH`. +The {VARS.WARP_AGENT_CLI} is automatically distributed with the Warp desktop app and can be used right away in Warp. To make the CLI globally available, add it to your `PATH`. - To add the Oz CLI to your `PATH`: + To add the {VARS.WARP_AGENT_CLI} to your `PATH`: 1. Open the [Command Palette](/terminal/command-palette/) (`Cmd+P`) - 2. In the search field, find and select the **Install Oz CLI Command** action. + 2. In the search field, find and select the **Install {VARS.WARP_AGENT_CLI} Command** action. :::note **Note:** Administrator permissions are required to install the CLI into `/usr/local/bin` . @@ -49,7 +50,7 @@ The Oz CLI is automatically distributed with the Warp desktop app and can be use In the Warp installer, select **Add Warp to PATH**. If you are installing for all users, this will put the CLI on the system path. Otherwise, the CLI is only added to the path for your account. - To run the Oz CLI on Linux, use the same command that you'd use to start Warp normally. If you installed Warp via a package manager, it should already be on the system `PATH`. + To run the {VARS.WARP_AGENT_CLI} on Linux, use the same command that you'd use to start Warp normally. If you installed Warp via a package manager, it should already be on the system `PATH`. @@ -113,7 +114,7 @@ Warp provides standalone packages for the CLI on macOS and Linux, without the Wa * aarch64: [`.deb`](https://app.warp.dev/download/cli?os=linux\&package=deb\&arch=aarch64), [`.rpm`](https://app.warp.dev/download/cli?os=linux\&package=rpm\&arch=aarch64), [pacman](https://app.warp.dev/download/cli?os=linux\&package=pacman\&arch=aarch64) - A standalone CLI package is not currently available on Windows. To use the Oz CLI on Windows, install the Warp app, which bundles the CLI. + A standalone CLI package is not currently available on Windows. To use the {VARS.WARP_AGENT_CLI} on Windows, install the Warp app, which bundles the CLI. You can install Warp using [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/): @@ -131,7 +132,7 @@ Regardless of your OS or installation method, the CLI command is `oz`. If you're ## Logging in -The Oz CLI supports two authentication methods, depending on where and how you're running agents. +The {VARS.WARP_AGENT_CLI} supports two authentication methods, depending on where and how you're running agents. * **Interactive login —** best for local machines where you have Warp installed and can authenticate through a browser. * **API keys** — best for automated or remote environments that need to authenticate without human interaction. @@ -201,7 +202,7 @@ $ oz agent run --prompt "analyze this codebase" ## Running agents -The Oz CLI offers two ways to run agents, depending on where you want the work to happen: +The {VARS.WARP_AGENT_CLI} offers two ways to run agents, depending on where you want the work to happen: **Use `oz agent run` when:** @@ -306,7 +307,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 [Oz API](/reference/api-and-sdk/). +When your team runs many agents across schedules, integrations, and ad-hoc triggers, `name` lets you answer questions like "how many distinct workflows are we running?" and "how often does this particular workflow run?" You can filter runs by name using the `name` query parameter on `GET /agent/runs` in the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/). **Examples:** @@ -392,7 +393,7 @@ The `--share` flag can be repeated, and uses the following syntax: ## Additional commands -The following commands are available for managing and inspecting Oz resources. +The following commands are available for managing and inspecting Warp resources. ### Managing named agents diff --git a/src/content/docs/reference/cli/integration-setup.mdx b/src/content/docs/reference/cli/integration-setup.mdx index a3099d474..1cef7f8c6 100644 --- a/src/content/docs/reference/cli/integration-setup.mdx +++ b/src/content/docs/reference/cli/integration-setup.mdx @@ -1,11 +1,16 @@ --- title: Integration setup description: >- - Learn how to set up environments and integrations so you can trigger Oz + Learn how to set up environments and integrations so you can trigger agents from external tools. sidebar: label: "Integration Setup" --- +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). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: 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: @@ -29,7 +34,7 @@ Warp integrations connect external tools, like Slack or Linear, to agents that r There are three main components to know: -* **Triggers** provide the context that tells Warp _what_ to run. A trigger could be a Slack message where you tag @Oz, or a Linear issue or comment. +* **Triggers** provide the context that tells Warp _what_ to run. A trigger could be a Slack message where you tag @warp, or a Linear issue or comment. * [**Integrations**](/platform/integrations/) are what connect the trigger surface (Slack, Linear) to Warp. An integration links the trigger to your [Warp team](/knowledge-and-collaboration/teams/) and handles posting results to the original tool, for example, replying in Slack. * **Environments** define how and where agents run your code. When an agent is triggered, Warp uses the environment to spin up a container, clone repositories, and execute the agent's workflow. @@ -50,7 +55,7 @@ Setting up an integration consists of three steps. 1. **Create an environment** for the agent to run your code. 2. **Authorize GitHub** so Warp can clone repositories, write code, debug issues, open pull requests, and more. -3. **Configure** the Oz app with an integration. +3. **Configure** the {VARS.WARP_AUTOMATION_PLATFORM} app with an integration. :::tip If setup fails, use the returned error code to narrow the fix. Common errors include: @@ -203,7 +208,7 @@ For full setup instructions, see [Team GitHub authorization](/platform/team-acce Once you have set up at least one environment, you can create integrations that connect it to Slack or Linear. :::note -For easier setup, use the [Oz web app](https://oz.warp.dev) to configure integrations with a guided flow. +For easier setup, use the {VARS.WEB_APP} to configure integrations with a guided flow. ::: Alternatively, use the CLI where `` is your environment ID: @@ -221,11 +226,11 @@ If you omit `--environment`, the CLI will show a list of environments and prompt The CLI then: 1. Links the integration to your Warp team and environment. -2. Opens a browser flow to install the Oz app into your Slack workspace or Linear workspace. +2. Opens a browser flow to install the {VARS.WARP_AUTOMATION_PLATFORM} app into your Slack workspace or Linear workspace. 3. Generates an **integration ID** you can later list or delete. :::note -The [GitHub integration](/platform/integrations/github/), which starts agents from `@oz-agent` mentions on issues and pull requests, isn't created with `oz integration create`. It's set up by installing the Oz by Warp GitHub App and enabling the GitHub organization in the Admin Panel. +The [GitHub integration](/platform/integrations/github/), which starts agents from `@warp-agent` mentions on issues and pull requests, isn't created with `oz integration create`. It's set up by installing the Oz by Warp GitHub App and enabling the GitHub organization in the Admin Panel. ::: **Additional `integration create` flags:** @@ -302,6 +307,6 @@ You now have everything needed to trigger agents from your team's tools. From he **Additional reading** * [Cloud Agents Overview](/platform/) -* [Oz Platform](/platform/overview/) +* [{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/) diff --git a/src/content/docs/reference/cli/mcp-servers.mdx b/src/content/docs/reference/cli/mcp-servers.mdx index f1e803ff6..f38fc2dfc 100644 --- a/src/content/docs/reference/cli/mcp-servers.mdx +++ b/src/content/docs/reference/cli/mcp-servers.mdx @@ -6,6 +6,11 @@ description: >- sidebar: label: "MCP servers" --- +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). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: 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`. @@ -102,7 +107,7 @@ $ oz agent run --mcp "904a8936-fa82-4571-b1d6-166c26197981" --prompt "use my MCP ``` :::note -For cloud agent workflows, use [Oz-managed secrets](/platform/secrets/) to store and inject credentials safely — secrets are stored in the cloud and referenced by name in your config. For local runs, a secrets manager CLI such as [`op`](https://developer.1password.com/docs/cli/get-started/), [`pass`](https://www.passwordstore.org/), or [`gcloud secrets versions access`](https://cloud.google.com/secret-manager/docs/create-secret-quickstart#secretmanager-quickstart-gcloud) can fetch secrets on remote hosts without exposing them in your shell history. +For cloud agent workflows, use [{VARS.WARP_AUTOMATION_PLATFORM}-managed secrets](/platform/secrets/) to store and inject credentials safely — secrets are stored in the cloud and referenced by name in your config. For local runs, a secrets manager CLI such as [`op`](https://developer.1password.com/docs/cli/get-started/), [`pass`](https://www.passwordstore.org/), or [`gcloud secrets versions access`](https://cloud.google.com/secret-manager/docs/create-secret-quickstart#secretmanager-quickstart-gcloud) can fetch secrets on remote hosts without exposing them in your shell history. ::: --- diff --git a/src/content/docs/reference/cli/quickstart.mdx b/src/content/docs/reference/cli/quickstart.mdx index 3950c22ae..3ca6ae54d 100644 --- a/src/content/docs/reference/cli/quickstart.mdx +++ b/src/content/docs/reference/cli/quickstart.mdx @@ -1,16 +1,21 @@ --- title: CLI quickstart description: >- - Set up and run your first cloud agent via the Oz CLI in less than 5 minutes. + Set up and run your first cloud agent via the {{WARP_AGENT_CLI}} in less than 5 minutes. sidebar: label: "Quickstart" --- import VideoEmbed from '@components/VideoEmbed.astro'; +import { VARS } from '@data/vars'; -This guide walks you through the essentials to get up and running with the Oz 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. +:::caution +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: + +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. -Watch this short demo of the Oz CLI workflow: - +Watch this short demo of the {VARS.WARP_AGENT_CLI} workflow: + ## 1. Install the CLI @@ -39,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 [Oz web app](https://oz.warp.dev/settings). 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 {VARS.WEB_APP}. See [API Keys](/reference/cli/api-keys/) for guidance on personal vs. [agent keys](/platform/agents/) and on security best practices. ::: ## 3. Run an agent @@ -68,7 +73,7 @@ If you haven't already created an environment, run `/create-environment` in Warp oz agent run-cloud --environment --prompt "Scan this repo for outdated dependencies" ``` -Replace `` with your environment ID, which you can find by running `oz environment list` on the Oz CLI. +Replace `` with your environment ID, which you can find by running `oz environment list` on the {VARS.WARP_AGENT_CLI}. ## 5. Add MCP context (optional) @@ -82,13 +87,13 @@ See [MCP Servers](/reference/cli/mcp-servers/) for all supported formats, includ ## Next steps -Once you've successfully set up and run your agent, explore other configurations and workflows with the Oz CLI: +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 Oz CLI using the [`oz help` command](/reference/cli/troubleshooting/#getting-help). +* Get up-to-date information about the {VARS.WARP_AGENT_CLI} using the [`oz help` command](/reference/cli/troubleshooting/#getting-help). * Run agents in CI with the [GitHub Actions quickstart](/platform/integrations/quickstart-github-actions/). -Continue reading the [Oz 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](/reference/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/reference/cli/skills.mdx index 1a2ca409b..f718c98b6 100644 --- a/src/content/docs/reference/cli/skills.mdx +++ b/src/content/docs/reference/cli/skills.mdx @@ -1,11 +1,16 @@ --- -title: "Skills via the Oz CLI" +title: "Skills via the {{WARP_AGENT_CLI}}" sidebar: label: "Skills" description: >- - Use skills with the Oz CLI to run agents from reusable skill definitions + Use skills with the {{WARP_AGENT_CLI}} to run agents from reusable skill definitions stored in your repositories. --- +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). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: [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/reference/cli/troubleshooting.mdx index 0f239add4..86e72c1f6 100644 --- a/src/content/docs/reference/cli/troubleshooting.mdx +++ b/src/content/docs/reference/cli/troubleshooting.mdx @@ -1,11 +1,16 @@ --- title: CLI Troubleshooting description: >- - Solutions for common Oz CLI errors — including authentication issues, agent + Solutions for common {{WARP_AGENT_CLI}} errors — including authentication issues, agent failures, environments, GitHub access, and Docker image issues. --- +import { VARS } from '@data/vars'; -Solutions for common Oz 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. +:::caution +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: + +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. ## Getting help diff --git a/src/content/docs/reference/cli/warp-drive.mdx b/src/content/docs/reference/cli/warp-drive.mdx index e72bf02cd..425e42565 100644 --- a/src/content/docs/reference/cli/warp-drive.mdx +++ b/src/content/docs/reference/cli/warp-drive.mdx @@ -6,8 +6,13 @@ description: >- sidebar: label: "Warp Drive Context" --- +import { VARS } from '@data/vars'; -Reference saved Warp Drive objects in Oz 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 ``, ``, or `` syntax. +:::caution +The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). See the [Warp Agent CLI docs](/agents/cli/) for the replacement. +::: + +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 ``, ``, or `` syntax. ## Reusing saved prompts diff --git a/src/content/docs/reference/index.mdx b/src/content/docs/reference/index.mdx index 4acfd0f23..59996046e 100644 --- a/src/content/docs/reference/index.mdx +++ b/src/content/docs/reference/index.mdx @@ -1,16 +1,17 @@ --- title: Technical reference description: >- - Technical reference documentation for the Oz CLI, API, and SDK. + Technical reference documentation for the {{WARP_AGENT_CLI}}, API, and SDK. --- +import { VARS } from '@data/vars'; -Technical reference documentation for the Oz 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. +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 [Oz CLI](/reference/cli/) lets you run and configure agents from any environment — locally, in CI pipelines, or on remote machines. +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 Oz CLI without human interaction, ideal for CI pipelines, headless servers, and containers. +- [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. @@ -20,6 +21,6 @@ The [Oz CLI](/reference/cli/) lets you run and configure agents from any environ ## API & SDK -The [Oz API](/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. +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/community/open-source-partnership.mdx b/src/content/docs/support-and-community/community/open-source-partnership.mdx index 8694c0a50..d704499e9 100644 --- a/src/content/docs/support-and-community/community/open-source-partnership.mdx +++ b/src/content/docs/support-and-community/community/open-source-partnership.mdx @@ -1,21 +1,22 @@ --- -title: Oz Open Source Partnership +title: "{{WARP_AUTOMATION_PLATFORM}} Open Source Partnership" description: >- Warp supports high-impact open source projects with free agent credits - through the Oz Open Source Partnership program. + through the {{WARP_AUTOMATION_PLATFORM}} Open Source Partnership program. --- +import { VARS } from '@data/vars'; -Warp is committed to supporting the open source community. Through the Oz Open Source Partnership program, we offer free agent usage credits to high-impact open source projects, helping maintainers and contributors accelerate their development workflows. +Warp is committed to supporting the open source community. Through the {VARS.WARP_AUTOMATION_PLATFORM} Open Source Partnership program, we offer free agent usage credits to high-impact open source projects, helping maintainers and contributors accelerate their development workflows. ## What you get -* **Free Oz credits** - Receive complimentary credits to run agents on your open source project +* **Free {VARS.WARP_AUTOMATION_PLATFORM} credits** - Receive complimentary credits to run agents on your open source project * **Agent access** - Use cloud agents to automate tasks like code review, bug triage, documentation, and more across your repositories * **Ongoing support** - Warp partners with accepted projects to ensure they get the most value from agents ## Who can apply -The Oz Open Source Partnership program is designed for actively maintained, high-impact open source projects. When reviewing applications, we consider factors like community size, project activity, and the potential impact of agents on your workflow. +The {VARS.WARP_AUTOMATION_PLATFORM} Open Source Partnership program is designed for actively maintained, high-impact open source projects. When reviewing applications, we consider factors like community size, project activity, and the potential impact of agents on your workflow. :::note Have questions about the program? Reach out to us at [support@warp.dev](mailto:support@warp.dev). @@ -26,5 +27,5 @@ Have questions about the program? Reach out to us at [support@warp.dev](mailto:s Tell us about your open source project by filling out the [application form](https://tally.so/r/LZWxqG). We'll review your submission and follow up with next steps. :::note -The Oz Open Source Partnership program provides free agent credits for open source projects. This is separate from Warp's open source client — the Warp client is published under AGPL v3 at [`warpdotdev/warp`](https://github.com/warpdotdev/warp); see [Contributing to Warp](/support-and-community/community/contributing/). For sponsorship opportunities for your project, reach out to [partnerships@warp.dev](mailto:partnerships@warp.dev). +The {VARS.WARP_AUTOMATION_PLATFORM} Open Source Partnership program provides free agent credits for open source projects. This is separate from Warp's open source client — the Warp client is published under AGPL v3 at [`warpdotdev/warp`](https://github.com/warpdotdev/warp); see [Contributing to Warp](/support-and-community/community/contributing/). For sponsorship opportunities for your project, reach out to [partnerships@warp.dev](mailto:partnerships@warp.dev). ::: diff --git a/src/content/docs/support-and-community/index.mdx b/src/content/docs/support-and-community/index.mdx index b835139d4..fff6f15a9 100644 --- a/src/content/docs/support-and-community/index.mdx +++ b/src/content/docs/support-and-community/index.mdx @@ -4,6 +4,8 @@ description: >- Contact Warp support, join the community, and find help for bugs, billing, and enterprise issues. --- +import { VARS } from '@data/vars'; + ## Contact support ### Subscribers and Enterprise @@ -53,7 +55,7 @@ We host [live events](https://luma.com/warpdotdev) year-round — product demos, * [**Warp Preview**](/support-and-community/community/warp-preview-and-alpha-program/) — Try experimental features before anyone else. Your feedback directly shapes what ships. * [**Refer a Friend**](/support-and-community/community/refer-a-friend/) — Send Warp to a developer you think would love it. Earn themes, swag, and gift cards. -* [**Oz Open Source Partnership**](/support-and-community/community/open-source-partnership/) — Free agent credits for high-impact open source projects. +* [**{VARS.WARP_AUTOMATION_PLATFORM} Open Source Partnership**](/support-and-community/community/open-source-partnership/) — Free agent credits for high-impact open source projects. :::note **Ambassador program** 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 5c72466ff..9234449d4 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 @@ -5,6 +5,7 @@ sidebar: description: >- Details on Warp credits and how they are calculated. --- +import { VARS } from '@data/vars'; ### What are Warp credits? @@ -129,7 +130,7 @@ The following scenarios use compute credits: * **First-party integrations** - Running agents through Slack or Linear integrations * **Cloud agent runs** - Using `oz agent run-cloud` via the CLI -* **Oz API** - Running agents through Warp's Oz API +* **{VARS.API_SDK_NAME}** - Running agents through Warp's API * **Cloud Mode** - Running an agent from Cloud Mode in the Warp app #### Not eligible for compute credits @@ -155,7 +156,7 @@ The following scenarios do **not** use platform credits: * **Local agents on Free, Build, or Max plans** don't use platform credits, regardless of inference source. * **Local agents on Business or Enterprise using Warp-managed inference** don't use platform credits because Warp is already paying for the model call through AI credits. * **Regular terminal usage** doesn't use platform credits. Shell commands and non-AI Warp features don't consume credits. -* **Third-party agent CLIs run directly** don't use platform credits when you run `claude`, `codex`, or another agent CLI outside of Oz. +* **Third-party agent CLIs run directly** don't use platform credits when you run `claude`, `codex`, or another agent CLI outside of Warp. For a full breakdown of how platform credits work, see [platform credits](/support-and-community/plans-and-billing/platform-credits/). diff --git a/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx b/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx index f3db59233..0708f7030 100644 --- a/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx @@ -4,6 +4,7 @@ description: >- Platform credits cover Warp's platform layer on every cloud agent run and on local runs with customer-supplied inference. Learn when they apply. --- +import { VARS } from '@data/vars'; Platform credits cover Warp's platform infrastructure for coordinating, observing, and integrating agent runs. They apply to every cloud agent run, plus local agent runs on Business and Enterprise plans that use customer-supplied inference such as BYOK, a custom inference endpoint, or BYOLLM. @@ -20,7 +21,7 @@ BYOK and customer-supplied inference (custom inference endpoints, plus BYOLLM) a Each credit bucket covers a different layer of the infrastructure Warp provides. Credit types and where an agent runs (local or cloud) are independent — each agent run consumes from whichever credit types apply to it. * **AI credits** cover inference: the LLM call itself. Consumed when Warp pays for the model call through Warp-managed providers. Used by agent conversations, [Generate](/agents/local-agents/generate/), [AI Autofill](/knowledge-and-collaboration/warp-drive/workflows/#ai-autofill), and other AI features. See [credits](/support-and-community/plans-and-billing/credits/) for how AI credits are calculated. -* **Compute credits** cover compute: the sandbox an agent runs in. Consumed when an agent run uses Warp-hosted compute. In practice this is cloud agent runs (Slack and Linear integrations, `oz agent run-cloud`, the Oz API, and Cloud Mode in the Warp app); local agent runs use your own machine and don't consume compute credits. See [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits). +* **Compute credits** cover compute: the sandbox an agent runs in. Consumed when an agent run uses Warp-hosted compute. In practice this is cloud agent runs (Slack and Linear integrations, `oz agent run-cloud`, the {VARS.API_SDK_NAME}, and Cloud Mode in the Warp app); local agent runs use your own machine and don't consume compute credits. See [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits). * **Platform credits** cover Warp's platform layer: run lifecycle, integrations, dashboard, APIs, and observability. Apply to every cloud agent run, plus local agent runs on Business and Enterprise plans that use customer-supplied inference. The three buckets are independent and a single run can consume from more than one. A Warp-managed cloud agent run, for example, consumes AI credits for the model call, compute credits for the hosted compute, and platform credits for the platform infrastructure that runs the agent. @@ -37,7 +38,7 @@ Whether platform credits apply depends on where the agent runs and who's paying ### Uses platform credits -* **Cloud agents on any plan** use platform credits for every cloud agent run, regardless of which agent runs the task (Warp Agent, Claude Code, or Codex), inference source (Warp-managed, BYOK, or BYOLLM), or compute source (Warp-hosted or self-hosted workers). Warp's platform infrastructure coordinates every cloud agent run. +* **Cloud agents on any plan** use platform credits for every cloud agent run, regardless of which agent runs the task (Warp Agent, Claude Code, or Codex), inference source (Warp-managed, BYOK, or BYOLLM), or compute source (Warp-hosted or self-hosted workers). Warp's platform infrastructure coordinates every cloud agent run. [Warp Factories](/factories/) runs are cloud agent runs, so a factory's agents draw platform credits the same way. * **Local agents on Business or Enterprise with customer-supplied inference** use platform credits when the local agent run uses [BYOK](/agents/inference/bring-your-own-api-key/), a [custom inference endpoint](/agents/inference/custom-inference-endpoint/), or BYOLLM. Warp isn't paying for the model call, but Warp's platform infrastructure is still running the local agent. BYOK and customer-supplied inference are subject to plan-size eligibility — see the callout above. ### Doesn't use platform credits @@ -45,7 +46,7 @@ Whether platform credits apply depends on where the agent runs and who's paying * **Local agents on Free, Build, or Max plans** don't use platform credits, regardless of whether you use Warp-managed inference or BYOK. * **Local agents on Business or Enterprise using Warp-managed inference** don't use platform credits because Warp is already paying for the model call through AI credits. * **Regular terminal usage** doesn't use platform credits. Shell commands and non-AI Warp features don't consume credits. -* **Third-party agent CLIs run directly** don't use platform credits when you run `claude`, `codex`, or another agent CLI without going through Oz. +* **Third-party agent CLIs run directly** don't use platform credits when you run `claude`, `codex`, or another agent CLI without going through Warp. ## Where platform credits appear 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 4b53cf1b7..adc2e4d8a 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 @@ -6,6 +6,7 @@ description: >- Frequently asked questions about upgrading, managing billing, refunds, and invoicing with Warp's paid plans. --- +import { VARS } from '@data/vars'; ### How can I upgrade and subscribe to a Warp plan? @@ -254,7 +255,7 @@ The waterfall on the owner's account 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 on the owner's 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 Oz 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](/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. :::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. @@ -282,7 +283,7 @@ Warp doesn’t currently offer discounts for students or non-profits. We recomme For open source teams, two paths are available: -* The [Oz Open Source Partnership](/support-and-community/community/open-source-partnership/) program offers free agent credits to high-impact open source projects. +* The [{VARS.WARP_AUTOMATION_PLATFORM} Open Source Partnership](/support-and-community/community/open-source-partnership/) program offers free agent credits to high-impact open source projects. * Warp's client itself is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE-AGPL), so you can build, run, and contribute to it directly. See [Contributing to Warp](/support-and-community/community/contributing/) for the flow. ### Where is Warp Drive data for my team stored? @@ -347,7 +348,7 @@ For lighter-weight routing through any OpenAI-compatible endpoint (OpenRouter, L ### What features are available during multi-harness orchestration beta? -Multi-harness orchestration is currently in beta and available to all users. You can use the [Warp Agent](/platform/harnesses/warp-agent/) alongside [Claude Code](/platform/harnesses/claude-code/) and [Codex](/platform/harnesses/codex/) in Oz cloud environments, and mix and match harnesses across workflows. +Multi-harness orchestration is currently in beta and available to all users. You can use the [Warp Agent](/platform/harnesses/warp-agent/) alongside [Claude Code](/platform/harnesses/claude-code/) and [Codex](/platform/harnesses/codex/) in {VARS.WARP_AUTOMATION_PLATFORM} cloud environments, and mix and match harnesses across workflows. [Agent Memory](/agents/agent-memory/) is currently in Research Preview. It lets preferences, project knowledge, and learnings from past sessions carry across harnesses and future agent runs. [Contact our sales team](https://www.warp.dev/contact-sales) to request access. diff --git a/src/content/docs/terminal/comparisons/index.mdx b/src/content/docs/terminal/comparisons/index.mdx index 16f221008..e665ba579 100644 --- a/src/content/docs/terminal/comparisons/index.mdx +++ b/src/content/docs/terminal/comparisons/index.mdx @@ -4,13 +4,14 @@ description: >- Compare Warp's performance and terminal feature support against other popular terminal emulators like iTerm2, Alacritty, and WezTerm. --- +import { VARS } from '@data/vars'; Warp is a modern terminal built in Rust with GPU rendering, agent support, and a code-editor-style input. Use this section to see how Warp stacks up against other popular terminals on raw performance and feature coverage. ## How Warp differs * **Open source under AGPL v3** — Warp's client lives at [`warpdotdev/warp`](https://github.com/warpdotdev/warp). You can read the code, build from source, and contribute. See [Contributing to Warp](/support-and-community/community/contributing/) for the flow. -* **Built-in agents** — Warp ships with Warp Agent (powered by Oz) and supports third-party CLI agents like Claude Code, Codex, and Gemini CLI from the same terminal. +* **Built-in agents** — Warp ships with the Warp Agent (powered by the {VARS.WARP_AUTOMATION_PLATFORM}) and supports third-party CLI agents like Claude Code, Codex, and Gemini CLI from the same terminal. * **Modern editing** — Cursor placement, multi-line input, block-based output, and integrated code review work like a text editor instead of a traditional terminal emulator. * **Cross-platform Rust core** — Warp ships on macOS, Linux, and Windows from a single Rust + GPU-rendered codebase. diff --git a/src/content/docs/terminal/input/classic-input.mdx b/src/content/docs/terminal/input/classic-input.mdx index 5e2ad62e2..2e01dccd4 100644 --- a/src/content/docs/terminal/input/classic-input.mdx +++ b/src/content/docs/terminal/input/classic-input.mdx @@ -6,6 +6,7 @@ description: >- box. --- import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { VARS } from '@data/vars'; Classic Input corresponds to the **Shell (PS1)** option under **Settings** > **Appearance** > **Input**. It provides a traditional terminal experience with support for shell customizations like PS1 prompts, oh-my-zsh themes, same-line prompts, and more. @@ -94,7 +95,7 @@ Warp input occasionally shows hints within the input editor in a light grey text ## How to run commands in Agent Mode -Once you have typed your question or task in the input, press `Enter` to execute your AI query. Agent Mode will send your request to Oz and begin streaming output in the form of an AI block. +Once you have typed your question or task in the input, press `Enter` to execute your AI query. Agent Mode will send your request to the {VARS.WARP_AUTOMATION_PLATFORM} and begin streaming output in the form of an AI block. Unlike a chat panel, Agent Mode can complete tasks for you by running commands directly in your session. @@ -112,12 +113,12 @@ If the suggested command fails and you want to resolve the error, you can start If Agent Mode doesn't have enough context to assist with a task, it will ask permission to run a command and read the output of that command. -You must explicitly agree and press `Enter` to run the requested command. When you hit enter, both the command input and the output will be sent to Oz. +You must explicitly agree and press `Enter` to run the requested command. When you hit enter, both the command input and the output will be sent to the {VARS.WARP_AUTOMATION_PLATFORM}. If you do not wish to send the command or its output to AI, you can click Cancel or press `Ctrl+C` to exit Agent Mode and return to the traditional command line.
-![Oz asks permission to run a command and read the output.](../../../../assets/terminal/warp-ai-permissions.png) +![The agent asks permission to run a command and read the output.](../../../../assets/terminal/warp-ai-permissions.png)
Agent command approval prompt.
@@ -128,6 +129,6 @@ Once a requested command is executed, you can click to expand the output and vie
Viewing command details.
-If a requested command fails, Oz detects it. Agent Mode is self-correcting. It will request another command until it completes the task for you. +If a requested command fails, the {VARS.WARP_AUTOMATION_PLATFORM} detects it. Agent Mode is self-correcting. It will request another command until it completes the task for you. Warp lets you choose from a curated list of LLMs for use in Agent Mode. By default, Warp uses **Auto (Responsive)**, which routes to the highest-quality, fastest available model. You can switch to other supported models — see [Model choice](/agents/inference/model-choice/) for the full list. diff --git a/src/data/vars.ts b/src/data/vars.ts index 4647ca315..eea706942 100644 --- a/src/data/vars.ts +++ b/src/data/vars.ts @@ -7,13 +7,48 @@ // Use the future/conceptual name as the key; the value holds the current string. export const VARS = { - // Platform — keys named for upcoming Warp branding; values are current Oz names - WARP_AUTOMATION_PLATFORM: "Oz", // value → "Warp Automation Platform" at rename - WARP_AGENT_CLI: "Oz CLI", // value → "Warp Agent CLI" at rename - WEB_APP: "Oz web app", // future name TBD - WEB_APP_URL: "https://oz.warp.dev", // value → "https://app.warp.dev" at rename - DASHBOARD: "Oz dashboard", // future name TBD - PLATFORM_RUN: "Oz run", // future name TBD + // Platform — renamed 8/18. The remaining Oz-valued keys below are the + // deliberate 9/15 holdouts: the `oz` binary and the Oz v1 webapp keep their + // names until that date, so they are NOT stale, they are pending. + // + // IMPORTANT: "Automation Platform" is a common-noun phrase, not a proper + // noun like "Oz" was. Referential uses need a definite article in the prose + // ("with the {VARS.WARP_AUTOMATION_PLATFORM}", "The {VARS.…} provides"); + // 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 9/15, then "Warp Agent CLI" + WEB_APP: "Oz web app", // legacy Oz v1 webapp (oz.warp.dev) — holds until 9/15 + WEB_APP_URL: "https://oz.warp.dev", // holds until 9/15, then "https://app.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 + // product, a "factory" is an instance, and a bare capitalized "Factory" is + // never a proper noun (AGENTS.md -> Warp Factories terminology). + // + // "Runs page" was the other candidate and reads better in isolation, but it + // names a single page in the web app. This surface is defined as unified + // across the Warp app and web, and its Warp-app half is the Agent Management + // Panel, not a Runs page. The descriptive term keeps that meaning. + // + // Lowercase common noun, so capitalize only at the start of a sentence or + // bullet -- which the variable cannot do, so avoid putting it there. + DASHBOARD: "cloud agent dashboard", + // Renamed per HYC (8/17): the platform-level default is the plain + // descriptive phrase, not a branded one. Factory-specific pages should write + // "factory run" directly rather than reaching for this variable. + // + // 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 9/15, then "Warp API & SDK" + + // 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. + // Not rename-sensitive: this is a new reference, not a flip of existing + // Oz-branded text, so it isn't in style_lint.py's RENAME_SENSITIVE_VAR_STRINGS. + 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). diff --git a/src/pages/api.astro b/src/pages/api.astro index 8f8e012b7..79c45a4d9 100644 --- a/src/pages/api.astro +++ b/src/pages/api.astro @@ -199,7 +199,7 @@ const specBaseUrl = (specObject.servers as Array<{ url?: string }> | undefined)? -

Warp & Oz HTTP API reference

+

Warp Automation Platform HTTP API reference