diff --git a/.agents/references/terminology.md b/.agents/references/terminology.md index addeab3..17bf101 100644 --- a/.agents/references/terminology.md +++ b/.agents/references/terminology.md @@ -93,6 +93,15 @@ 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. + *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. + *Usage note:* Lowercase common noun. Capitalize the first letter only at the start of a sentence or bullet. + +- **Handoff** — The feature for moving an agent's 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 directions. + *Usage note:* Capitalize as a feature name. Use lowercase "hand off" / "handed off" only as a verb. + ## Coding terms (Warp features) - **Code** — Warp's coding experience for agent-assisted changes (editing, diffs, code review). @@ -236,9 +245,11 @@ For the summary of the most critical terms (core features, Oz terms, terms to av ## Billing and credits - **Add-on Credits** — capitalized as a product feature name -- **Cloud Agent Credits** — capitalized as a billing feature name +- **compute credits** — lowercase common noun; capitalize the first letter only at the start of a sentence or bullet. The compute bucket, consumed when an agent run uses Warp-hosted compute. Use alongside AI credits and platform credits when describing credit types. +- **cloud agent credits** — lowercase common noun; capitalize the first letter only at the start of a sentence or bullet. Credits consumed by cloud agents, in contrast with local agent credits. Refers to the same compute bucket as compute credits; choose the term that fits the framing. +- **platform credits** — lowercase common noun; capitalize the first letter only at the start of a sentence or bullet. The platform-infrastructure bucket, consumed for every cloud agent run plus local runs with customer-supplied inference. - **credits** — the unit of usage for AI features in Warp (lowercase, not "AI credits") -- **plan credits** — credits included with a subscription plan +- **Warp credits** — credits included with a subscription plan. Use in user-facing copy rather than "plan credits." ## External product names diff --git a/.agents/skills/style_lint/style_lint.py b/.agents/skills/style_lint/style_lint.py index b2369a8..644ef86 100644 --- a/.agents/skills/style_lint/style_lint.py +++ b/.agents/skills/style_lint/style_lint.py @@ -35,15 +35,18 @@ # Feature names that are correctly Title Case (exceptions to sentence-case rule) PROPER_FEATURE_NAMES = { "Admin Panel", "Agent Management Panel", "Agent Mode", "Agent Profiles", - "Auto-detection Mode", "Cloud Agent Credits", "Cloud Agents", + "Auto-detection Mode", "Cloud Agents", "Codebase Context", "Code Review", "Command Palette", "Global Rules", - "Oz CLI", "Oz Platform", "Project Rules", "Slash Commands", - "Terminal Mode", "Universal Input", "Warp Drive", "Warp Platform", + "Oz CLI", "Oz Platform", "Project Rules", + "Slash Commands", "Terminal Mode", "Universal Input", "Warp Drive", + "Warp Platform", } # Terminology: wrong → right (case-sensitive checks) PRODUCT_CASING = { "Warp Terminal": ("Warp", "Use 'Warp' unless specifically distinguishing from Oz"), + "Cloud Agent Credits": ("cloud agent credits", "Use lowercase 'cloud agent credits' (host-context) or 'compute credits' (bucket-context); capitalize first letter only at start of a sentence/bullet"), + "Platform Credits": ("platform credits", "Use lowercase 'platform credits'; capitalize first letter only at start of a sentence/bullet/heading"), "agent mode": ("Agent Mode", "Capitalize as a feature name"), "agent management panel": ("Agent Management Panel", "Capitalize as a UI surface name"), "warp drive": ("Warp Drive", "Capitalize as a feature name"), diff --git a/AGENTS.md b/AGENTS.md index 2a642c7..5398408 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -558,6 +558,8 @@ 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. +- **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. ### Oz terminology @@ -615,8 +617,10 @@ Product feature names retain their standard capitalization. Match the exact casi ### Billing and credits - **credits** (lowercase, not "AI credits") - the unit of usage for AI features in Warp - **Add-on Credits** (capitalized as a product feature name) -- **Cloud Agent Credits** (capitalized as a billing feature name) -- **plan credits** - credits included with a subscription plan +- **compute credits** (lowercase common noun; capitalize the first letter only at the start of a sentence or bullet) - the compute bucket; consumed when an agent run uses Warp-hosted compute. Used alongside AI credits and platform credits when describing credit types. +- **cloud agent credits** (lowercase common noun; capitalize the first letter only at the start of a sentence or bullet) - credits consumed by cloud agents (in contrast with local agent credits). Refers to the same compute bucket as compute credits; pick the term that fits the framing. +- **platform credits** (lowercase common noun; capitalize the first letter only at the start of a sentence or bullet) - the platform-infrastructure bucket +- **Warp credits** - credits included with a subscription plan. Use in user-facing copy rather than "plan credits." - Use "credit" or "credits" without the "AI" prefix throughout documentation ### UI elements diff --git a/src/content/docs/agent-platform/agent-memory/index.mdx b/src/content/docs/agent-platform/agent-memory/index.mdx new file mode 100644 index 0000000..2701051 --- /dev/null +++ b/src/content/docs/agent-platform/agent-memory/index.mdx @@ -0,0 +1,79 @@ +--- +title: Agent Memory (Research Preview) +description: >- + Agent Memory is a persistent, cross-harness memory layer for agents in + Oz, including the Warp Agent, Claude Code, and Codex. +sidebar: + label: "Agent Memory (Research Preview)" +--- +:::caution +Agent Memory is in **research preview** and is enabled per team for design partners. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access for your team. +::: + +Agent Memory is a persistent memory layer that lives on Oz and is shared across every supported agent harness — the built-in Warp Agent, Claude Code, Codex, and others as they're added. Agents read from and write to it 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 it. + +Memory creation and retrieval are asynchronous and run in the background, so they don't consume tokens or add latency to the active task. + +[Join the Agent Memory waitlist](https://warp.dev/oz/agent-memory#waitlist) + +## Key features + +* **Cross-harness memory** — One memory layer 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 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. +* **Agent-scoped, shareable stores** — By default, each agent has its own memory store. Stores can also be shared across multiple agents, or across an entire team, when the same knowledge should travel with the work. +* **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. +* **Fully accessible via API** — Memories and stores can be read, created, updated, and deleted through the [Oz API](/reference/api-and-sdk/). +* **Traceability** — For any agent run, you can see which memories influenced it. +* **Auditability** — Every change to a memory is recorded, so the full history of any memory can be inspected. +* **Self-hostable** — Enterprises can run Agent Memory on a [self-hosted Oz](/agent-platform/cloud-agents/self-hosting/) instance to meet security, privacy, and compliance requirements. + +## Where Agent Memory runs + +Agent Memory is part of Oz. Storage, memory creation, and retrieval all run on the same Oz instance that hosts your agents — either Warp-hosted Oz (the default) or a [self-hosted Oz](/agent-platform/cloud-agents/self-hosting/) instance that your team operates inside its own perimeter. The same memory is accessible from any agent you run on Oz: + +* The local Warp Agent. +* Cloud agents triggered from the CLI, web app, schedules, or integrations. +* Third-party harnesses running as cloud agents — Claude Code, Codex, and others as they're added. (Running third-party harnesses locally isn't supported during the research preview.) + +Memory stays bound to its owner (a user or a team), independent of which harness reads or writes. + +## Memory stores + +A memory store is a named collection of memories. By default, each agent has its own store and writes to it as it runs. Stores can also be shared across multiple agents when they need the same knowledge, and across teammates when knowledge should travel with the team. + +* **Personal stores** — Owned by a user. Hold preferences, working notes, and individual patterns. +* **Team stores** — Owned by a team. Hold shared knowledge like deployment runbooks, code review conventions, or on-call procedures. Every team member, and any agent the team authorizes, can read from the same store. + +Use multiple stores to keep contexts separate, and share stores across agents when needed. For example, a code review agent can have its own store of review patterns, while a repo-specific store of architectural decisions is shared between the code review agent and a Sentry triage agent so both reason about the same codebase. + +## Automatic memory 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. + +* **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, and it lands in 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](/agent-platform/capabilities/rules/) or [Codebase Context](/agent-platform/capabilities/codebase-context/). You don't need to write retrieval queries or pre-load memory. + +## Attaching memory to your agents + +Attach stores to agents with read-only or read-write access. Each attachment can include per-store instructions that tell the agent how and when to use the store — for example, "Reference this store for team naming conventions" or "Write a new memory after each successful deployment." Without instructions, the agent can access the store but won't know when to read from or write to it. + +## Join the waitlist + +Agent Memory is rolling out to design partner teams during research preview. [Join the waitlist](https://warp.dev/oz/agent-memory#waitlist) to request access. + +## Related pages + +* [Codebase Context](/agent-platform/capabilities/codebase-context/) — Let agents understand your codebase through semantic indexing. +* [Rules](/agent-platform/capabilities/rules/) — Define global and project-level guidelines that shape agent behavior. +* [Skills](/agent-platform/capabilities/skills/) — Reusable, scoped instructions that teach agents how to perform specific tasks. +* [Agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/) — Control what permissions and autonomy agents have. +* [Cloud agents overview](/agent-platform/cloud-agents/overview/) — Run background agents with team-wide observability. +* [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Run Oz, and Agent Memory along with it, on your own infrastructure. +* [Oz API and SDK](/reference/api-and-sdk/) — Read, create, update, and delete memories and stores programmatically. diff --git a/src/content/docs/agent-platform/capabilities/skills.mdx b/src/content/docs/agent-platform/capabilities/skills.mdx index 6dbc30e..4270b92 100644 --- a/src/content/docs/agent-platform/capabilities/skills.mdx +++ b/src/content/docs/agent-platform/capabilities/skills.mdx @@ -411,6 +411,10 @@ Warp maintains a public collection of ready-to-use skills in the [warpdotdev/oz- These same skills also appear as suggested agents in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), where you can run them directly in the cloud. +## Suggested skills from Agent Memory + +Promoting recurring patterns from [Agent Memory](/agent-platform/agent-memory/) into reviewable skill drafts is in design as part of the research preview. See the Agent Memory page for current status. + ## Invoking skills with a prompt You can pass additional context or instructions to a skill when invoking it with a slash command. diff --git a/src/content/docs/agent-platform/cli-agents/claude-code.mdx b/src/content/docs/agent-platform/cli-agents/claude-code.mdx index b765baa..f86c461 100644 --- a/src/content/docs/agent-platform/cli-agents/claude-code.mdx +++ b/src/content/docs/agent-platform/cli-agents/claude-code.mdx @@ -13,6 +13,10 @@ 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](/agent-platform/cloud-agents/harnesses/claude-code/). +::: + ## Setting up notifications Warp supports agent notifications for Claude Code through a plugin. Once installed, Warp surfaces in-app and desktop alerts when Claude Code needs your input — such as command approval, code review, or error intervention. @@ -70,5 +74,6 @@ Claude Code supports the full set of Warp's agent integration features: * [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) — step-by-step setup guide * [Claude Code in Warp](https://warp.dev/agents/claude-code) — product overview * [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) +* [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness * [OpenCode](/agent-platform/cli-agents/opencode/) * [Codex](/agent-platform/cli-agents/codex/) diff --git a/src/content/docs/agent-platform/cli-agents/codex.mdx b/src/content/docs/agent-platform/cli-agents/codex.mdx index e4f0b1a..bacc38a 100644 --- a/src/content/docs/agent-platform/cli-agents/codex.mdx +++ b/src/content/docs/agent-platform/cli-agents/codex.mdx @@ -13,6 +13,10 @@ 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](/agent-platform/cloud-agents/harnesses/codex/). +::: + ## Setting up notifications Codex supports native notifications that Warp surfaces as in-app and desktop alerts — such as when Codex completes a task, encounters an error, or needs your input. @@ -45,5 +49,6 @@ Codex supports the full set of Warp's 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://warp.dev/agents/codex) — product overview * [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) +* [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness * [Claude Code](/agent-platform/cli-agents/claude-code/) * [OpenCode](/agent-platform/cli-agents/opencode/) diff --git a/src/content/docs/agent-platform/cli-agents/overview.mdx b/src/content/docs/agent-platform/cli-agents/overview.mdx index 9fbad2f..c3fe721 100644 --- a/src/content/docs/agent-platform/cli-agents/overview.mdx +++ b/src/content/docs/agent-platform/cli-agents/overview.mdx @@ -11,6 +11,10 @@ Warp auto-detects supported CLI agents and enhances them with IDE-level features This feature set is also known as **universal agent support**. +:::note +Claude Code and Codex are also supported as harnesses in Oz for cloud orchestration. See [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/). +::: + ## Supported agents Warp currently supports the following CLI coding agents: diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx new file mode 100644 index 0000000..902e84c --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -0,0 +1,103 @@ +--- +title: Agent identities +description: >- + Agent identities are team-scoped bot accounts that own and execute cloud + agent runs. Use them to separate workflows, scope credentials, and attribute + automated work. +sidebar: + label: "Agent identities" +--- + +An **agent identity** is a team-scoped identity that can own and execute cloud agent runs. Every Warp team starts with a single default agent identity. Creating additional agent identities lets you separate workflows, scope credentials, and attribute automated runs to a specific bot account instead of a person. + +Agent identities are useful when you want to: + +* **Separate workflows** - Give the deploy bot, the dependency-update bot, and the code-review bot distinct identities so runs are easier to filter and audit. +* **Scope credentials** - Attach a specific set of managed secrets and skills to one identity so its runs receive only the configuration that workflow needs. +* **Attribute automated work** - Bind an API key to an agent identity so CI pipelines and webhooks show up as that bot in run history rather than as a teammate. + +## How agent identities work + +Each team has one default agent identity. Headless runs (such as team API key runs that don't specify an identity) execute under this default. User-triggered runs default to running as the calling user — surfaced as **Quick run** in the web app — unless you pick a specific agent identity. You can create additional agent identities on top of the default and run as any of them. Identities are team-scoped, so every member of a team can see and use the same set of agent identities. + +You can attach the following configuration to an agent identity: + +* **Description** - A short, human-readable summary teammates see when picking the identity. +* **Managed secrets** - References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the identity should have access to. +* **Skills** - Skill specs (for example, `org/repo:path/to/SKILL.md`) the identity comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments. + +Skill specs are stored in their normalized fully-qualified form, and managed secret references are validated against the team's secret scope at attach time. If a secret is missing or a skill repo is not accessible to the team's GitHub App installation, the request is rejected before anything is saved. + +## Service accounts and agent identities + +"Agent identity" is the user-facing name for what Warp's CLI and REST API internally model as a **service account**. The two terms refer to the same underlying record: + +* When `oz whoami` reports a principal of `service_account:`, that principal is an agent identity on your team. +* When [`oz federate issue-token`](/reference/cli/federate/) emits a subject component like `service_account:my-sa-id`, the value identifies the agent identity the run is executing as. + +You don't need to distinguish the two terms in day-to-day use — pick the agent identity in the UI or pass its UID to the API, and the CLI surfaces the corresponding `service_account:` principal. + +## Supporting multiple agent identities + +Most teams start with the default agent identity and add more as their automation matures. Creating additional agent identities is worth it when distinct workflows have meaningfully different scopes — for example, a `ci-runner` identity that only needs read-only repo access, an `on-call` identity that holds production deploy credentials and is restricted to incident playbooks, and a `nightly-jobs` identity used by scheduled cleanups. Scoping each identity to a single workflow gives every run the minimum credentials it needs, keeps audit trails attributable to the right bot, and lets you revoke or rotate one workflow's access without touching the rest. + +## Plan limits + +Every team starts with a default agent identity. Additional identities are subject to plan-based limits — see [warp.dev/pricing](https://warp.dev/pricing) for current limits per plan. + +When a team is over its plan limit (for example, after downgrading), the extra identities remain visible in the list but are marked as unavailable. Unavailable identities cannot be used to start runs, cannot have new API keys generated for them, and cannot be edited. + +## Managing agent identities + +You can create, list, update, and delete agent identities through the public API. The full request and response shapes — including error codes — live on the [API Reference](/api) page; the operations to look for are `createAgent`, `listAgents`, `updateAgent`, and `deleteAgent` under the **agent** tag. + +The endpoints behave as follows: + +* **Create** - `POST /agent/identities` with a `name` and optional `description`, `secrets`, and `skills`. Returns `201` with the new identity's `uid`, `name`, and `available` flag. +* **List** - `GET /agent/identities` returns every agent identity on the team, including the default. Each entry includes an `available` flag indicating whether it is within the plan limit. +* **Update** - `PUT /agent/identities/{uid}` replaces individual fields. Omitting a field preserves the current value; passing an empty string or empty array clears it. +* **Delete** - `DELETE /agent/identities/{uid}` soft-deletes the identity and atomically deletes every API key bound to it. The default agent identity cannot be deleted. + +### Caller requirements + +A few constraints apply across every endpoint: + +* **Team-scoped** - Agent identities belong to a team. The caller must be a member of exactly one team. If the caller is on zero teams or multiple teams, the request is rejected. +* **Human callers only** - Only human users can create, update, or delete an agent identity. A request authenticated as an agent identity itself is rejected. +* **Availability is enforced on use** - Over-plan-limit identities are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs. + +## API keys bound to an agent identity + +A team API key can be bound to a specific agent identity at creation time. Calls authenticated with that key run as the chosen identity. The team is resolved automatically from the identity — you don't need to specify a team when generating the key. + +To create a key bound to an agent identity, choose the identity when creating the team API key. See [API Keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys. + +Once the key exists, the CLI and SDK authenticate as that agent identity for every call. There is no extra flag to set; the binding is on the key itself. + +## Running as an agent identity + +There are two ways to run a cloud agent as a specific agent identity: + +* **Authenticate with a key bound to the identity** - Every run started with that key executes as the bound agent identity. This is the typical path for CI pipelines and scheduled work. +* **Pass `agent_identity_uid` on `POST /agent/runs`** - For one-off runs, send the agent identity's `uid` in the request body. The field is only valid for team-owned runs. + +When neither path is used, headless runs (team API key runs without an identity) execute under the team's default agent identity. User-triggered runs (Warp app, personal API key, Slack, Linear) execute as the calling user — surfaced as **Quick run** in the web app. + +## Where agent identities appear in the product + +Agent identities surface across several Oz surfaces: + +* **Agents page** - The Agents page in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) is where teams view, create, edit, and delete agent identities. The same page lists the skills available to your team. +* **Agent picker** - Forms that start a new run or schedule include an **Agent** dropdown. **Quick run** is the default option (runs execute as the calling user); selecting an agent identity runs as that identity instead. +* **Run filters and detail** - The Runs view lets you filter by agent identity, and individual run detail pages show which identity executed the run. +* **Admin Panel** - Billing usage in the [Admin Panel](/knowledge-and-collaboration/admin-panel/) attributes credits consumed by agent identity runs to the team rather than to a person. + +## Related pages + +* [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) - Manage the team-managed secrets you can attach to an agent identity. +* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - When to use an agent identity for automation versus a personal identity. +* [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the agent identity endpoints. +* [API Keys](/reference/cli/api-keys/) - Create keys bound to a specific agent identity. +* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run, including ones executing as an agent identity. +* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - The web surface where you manage agent identities and inspect their runs. +* [Admin Panel](/knowledge-and-collaboration/admin-panel/) - Team-level billing and access controls. diff --git a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx index 2611d40..c83a962 100644 --- a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx +++ b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx @@ -22,7 +22,7 @@ Cloud agent setups usually have four moving parts: ### 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 just need a reliable, cloud-connected agent runner. +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 @@ -53,7 +53,7 @@ Use this when you already have a system that schedules work (CI, dev boxes, inte #### Minimal setup checklist * A Warp team -* A service account (recommended for automation) +* An [agent identity](/agent-platform/cloud-agents/agents/) (recommended for automation) * The Oz CLI installed on the runner / box * Any needed credentials (often via secrets + environment variables) @@ -83,7 +83,7 @@ Use this when you want Oz to run agent workloads on Warp-managed infrastructure, * **First-party integrations (Slack, Linear, etc.)** that create tasks automatically from external events. * **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. +* **On-demand cloud jobs** using CLI commands like `oz agent run-cloud`. #### Example recipe: daily dead-code cleanup @@ -103,7 +103,7 @@ Use this when you want Oz to run agent workloads on Warp-managed infrastructure, If a task is naturally divisible: -* Launch multiple cloud agents via oz agent run-cloud, each with: +* Launch multiple cloud agents via `oz agent run-cloud`, each with: * A shard of the repo (directory/module ownership) * A shard of the prompt (one responsibility) * Aggregate results (PRs, notes, plans) in whatever system you prefer. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx new file mode 100644 index 0000000..157138b --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx @@ -0,0 +1,66 @@ +--- +title: Handoff from cloud to cloud +description: >- + Send a follow-up to a finished cloud run. The run continues with the prior + workspace state restored, so the agent picks up where it left off. +sidebar: + label: "Cloud to cloud" +--- + +Hand off a cloud agent run to a fresh cloud session when the original session has ended but you still want to push the same unit of work further. The run continues in the same conversation, with the prior session's workspace state restored, so the agent picks up where it left off instead of starting fresh. + +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 [management view](/agent-platform/cloud-agents/managing-cloud-agents/). + +## What carries over + +When you send a follow-up to a run whose session has ended, the run continues with: + +* **The same conversation** - The follow-up is appended to the same conversation. From your perspective, the run is one continuous conversation across sessions. +* **The prior workspace state** - The prior session's repository changes (tracked and untracked) are restored before the agent answers your follow-up. For git-managed sessions, the new session continues on the same Git branch. +* **Stable run identity** - The run's ID, task, creator, environment, schedule trigger, and integration source are preserved. Compute usage is recorded per session but rolls up to the same run. + +If applying any change fails, the agent reports what couldn't be applied and proceeds with what it could rather than starting over silently. + +## Prerequisites + +* **An ended cloud agent run** - The run must be in a terminal state — for example, succeeded, failed, or canceled — and have an associated agent conversation. Blocked runs that are waiting on user input or approval can't be continued via cloud-to-cloud handoff; respond to the prompt on the original run instead. Very old runs that predate the agent conversation model can't be continued via handoff. +* **A snapshot from the prior session** - Cloud agent runs capture a workspace snapshot at the end of each session. If the prior session couldn't capture one (for example, due to a transient storage error), the run still continues, just without restored workspace state. +* **Access to the run** - You need permission to submit follow-ups for the run. For team runs, this is typically any team member. Cloud runs that originated from a local-to-cloud handoff can be continued only by the user who created them, not by other team members. + +:::caution +Cloud-to-cloud handoff relies on a snapshot from the prior session. Older cloud runs that don't have a snapshot on file can't be handed off; start a new run instead. +::: + +## Sending a follow-up + +You don't take a separate "hand off" action — you send a follow-up from the Warp app, and the run continues. The handoff happens automatically when the original session has ended. + +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. +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. + +### Third-party agent runtimes + +Cloud-to-cloud handoff also works for supported third-party agent runtimes, but the affordance is a **Continue** button followed by an input prompt instead of the standard follow-up input. Click **Continue** on the ended run (from the conversation details panel or the artifacts shown after the run) and enter the next message you want the agent to act on. + +## Inspecting a run that's been handed off + +The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions. Click into the run to see the full transcript: each session appears in order, and you can scan the transcript to see where one session ended and the next began. Per-session timestamps aren't currently exposed in the API; the transcript is the source of truth. + +## Troubleshooting + +**The run continued but no workspace state was restored.** +The prior session didn't capture a snapshot. This is rare but possible — snapshot capture is best-effort. The run still continues with the same conversation, so the agent has the full transcript context even without the workspace state. + +**The run is in a terminal state with no conversation and follow-ups are rejected.** +Very old runs predate the agent conversation model and can't be continued via handoff. Start a new cloud agent run with the prompt you want, referencing the prior run if needed. + +## Related pages + +* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. +* [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/) - Promote a local conversation to a cloud run. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Find runs to send follow-ups to. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx new file mode 100644 index 0000000..584a427 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/index.mdx @@ -0,0 +1,52 @@ +--- +title: Handoff between local and cloud agents +description: >- + Move agent work between a local Warp session and the cloud, or continue a + finished cloud run with workspace state restored, without re-explaining the + task. +sidebar: + label: "Handoff overview" +--- + +Handoff lets you move a unit of agent work between a local Warp session and the cloud, or continue a finished cloud run, without re-explaining the task. The receiving agent picks up the conversation history, your workspace state, and any conversation attachments from the prior session. + +## Directions of handoff + +Handoff supports three directions: + +* **Local to cloud** - Promote a local Warp Agent conversation to a cloud agent run when you need more compute, longer-running work, or parallel variants of the same task. The cloud agent starts from your conversation history and a snapshot of your uncommitted workspace changes. See [Handoff from local to cloud](/agent-platform/cloud-agents/handoff/local-to-cloud/). +* **Cloud to cloud** - Send a follow-up to a cloud run after its session has ended. The run continues in the same conversation, with the prior session's workspace state restored. See [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/). +* **Cloud to local** - Fork a cloud conversation into a local Warp session with **Continue locally** or `/continue-locally`. See [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/#5-fork-the-session-to-your-local-warp). + +### Third-party agent runtime coverage + +Handoff coverage depends on which agent is running the conversation: + +* **Cloud to cloud** works for both the Warp Agent and supported third-party agent runtimes. For supported third-party agent runtimes, the affordance is a **Continue** button followed by an input prompt, instead of the streamlined follow-up flow you get with the Warp Agent. +* **Local to cloud** works for the Warp Agent. It isn't available for supported third-party agent runtimes. + +## What carries over + +Handoff preserves enough state that the receiving agent can resume the work, not only read about it. + +* **Conversation history** - The receiving agent sees the full transcript of the prior session. Local-to-cloud forks the conversation so the source isn't modified; cloud-to-cloud continues in the same conversation. +* **Workspace state** - Local-to-cloud and cloud-to-cloud capture the prior session's repository changes (tracked and untracked) and apply them in the receiving run before the agent answers the next prompt. The cloud-to-local direction doesn't currently apply workspace patches to your local checkout; review the cloud agent's branch or pull request artifact to inspect those changes. +* **Conversation attachments** - Files attached during the prior session remain available to the receiving agent. + +Handoff is best-effort. When the receiving agent can apply the prior session's changes cleanly, it picks up where the prior agent left off. When it can't, the agent reports what failed and proceeds with what it could rather than starting over silently. + +## When to use handoff + +Each direction has a clear motivating workflow. + +* **Local to cloud** - Use when a local conversation has grown into work that's better done in the cloud: long-running tasks you don't want to keep your laptop awake for, parallel variants of the same task, or steering work from another device once it's running. +* **Cloud to cloud** - Use when a cloud agent finished and you want to send a follow-up without losing the prior workspace state. Also useful when a Slack-triggered or scheduled run completes and someone on the team wants to push it further. +* **Cloud to local** - Use when a cloud agent has done the heavy lifting and you want to take over locally to verify, iterate, or polish before shipping. + +## Related pages + +* [Cloud agents overview](/agent-platform/cloud-agents/overview/) - What cloud agents are, when to use them, and how they fit into the Oz Platform. +* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the management view alongside local conversations. +* [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`. +* [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them. +* [Environments](/agent-platform/cloud-agents/environments/) - The runtime context a cloud agent runs in after a handoff. diff --git a/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx new file mode 100644 index 0000000..76c636f --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/handoff/local-to-cloud.mdx @@ -0,0 +1,67 @@ +--- +title: Handoff from local to cloud +description: >- + Promote a local Warp Agent conversation to a cloud agent run with the full + transcript and your uncommitted workspace changes — without re-explaining + the task. +sidebar: + label: "Local to cloud" +--- + +Hand off a local Warp conversation to a cloud agent run when the work outgrows your local session. The cloud agent inherits a fork of your local conversation and a snapshot of your uncommitted workspace changes, so it picks up where you left off instead of starting fresh. + +Use this handoff direction when: + +* You have a long-running task and don't want to keep your laptop awake. +* You want to fan out variants of the same task across multiple cloud agents in parallel. +* You want to walk away and check on the agent from a different device. +* You want the agent to keep working while you start a new conversation locally. + +## What the cloud agent receives + +When you hand off from local to cloud, the receiving cloud agent inherits: + +* **A forked conversation** - Warp forks your local conversation so the cloud agent inherits the full transcript without modifying the source. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) for related sync behavior. +* **A workspace snapshot** - Warp captures your uncommitted repository changes — both tracked modifications and untracked files — and packages them for the cloud agent. The cloud agent applies them before answering your follow-up. +* **Conversation attachments** - Files attached to the local conversation remain available in the cloud run. + +If applying any change fails in the cloud run, the cloud agent reports what couldn't be applied and proceeds with what it could rather than silently dropping changes. + +## Prerequisites + +* **An active local conversation** - Have an [Agent](/agent-platform/local-agents/overview/) conversation open in Warp with the work you want to hand off. +* **A configured environment** - The cloud agent needs an [environment](/agent-platform/cloud-agents/environments/) that includes the same repositories you're working in locally. The environment's repos must match your local checkout so the workspace snapshot applies cleanly. +* **Cloud conversation storage enabled** - In the Warp app, go to **Settings** > **Privacy** and turn on **Store AI conversations in the cloud** so the conversation can be forked. See [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/). +* **Sufficient credits** - Cloud agent runs consume credits. See [Credits](/support-and-community/plans-and-billing/credits/) for how credit usage works, and [Access, billing, and identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for team-specific credit requirements. + +## Handing off a conversation to the cloud + +1. **Open the handoff flow from your active conversation.** With the local conversation focused, press `&` or run the `/handoff` slash command. Either entry point opens the handoff flow scoped to the current conversation. The `/cloud-agent` slash command always starts a fresh cloud conversation and isn't an entry point for handoff. +2. **Choose the environment for the cloud run.** Pick the one whose repositories match the directories your local conversation has been editing. If you don't have a matching environment yet, create one and add the repos you've been working in. +3. **Add a follow-up prompt and submit.** Enter the next message you want the cloud agent to act on. + +:::note +The cloud agent runs with the same model your local conversation was using. Changing the model during handoff isn't supported. +::: + +After you submit, the cloud agent applies your workspace snapshot and addresses your follow-up. The local conversation stays untouched — 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. + +## Troubleshooting + +**The cloud agent reports that some changes couldn't be applied.** +The most common cause is a repository mismatch between your local checkout and the environment. The workspace snapshot is generated against your local repo's current state; the environment must be on a compatible branch and commit for the changes to apply cleanly. Switch the environment's repo to the branch you were on locally and retry the handoff. + +**The cloud agent doesn't see my uncommitted changes.** +Cloud conversation storage must be enabled for handoff to work. In the Warp app, open **Settings** > **Privacy** and confirm **Store AI conversations in the cloud** is on. Otherwise, the conversation can't be forked and the run falls back to starting fresh. + +**The conversation doesn't appear in the cloud run.** +The source conversation may not have finished syncing to the cloud when you triggered the handoff. Wait a moment and retry. If the problem persists, check the conversation panel to confirm the conversation has a cloud-synced indicator. + +## Related pages + +* [Handoff overview](/agent-platform/cloud-agents/handoff/) - What handoff is, the directions it supports, and what carries over. +* [Handoff from cloud to cloud](/agent-platform/cloud-agents/handoff/cloud-to-cloud/) - Continue a finished cloud run with workspace state restored. +* [Environments](/agent-platform/cloud-agents/environments/) - Configure the repos, image, and setup commands the cloud agent starts in. +* [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) - Run your first cloud agent from scratch. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx new file mode 100644 index 0000000..a16b1fc --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/authentication.mdx @@ -0,0 +1,122 @@ +--- +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. +sidebar: + label: "Authentication" +--- + +Third-party cloud agents — [Claude Code](#connecting-claude-code-credentials) and [Codex](#connecting-codex-credentials) — call their provider directly, so you need to store credentials as Warp-managed secrets before launching a run. This page walks through the one-time setup for each. + +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. + +:::note +[Bring Your Own Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) configured in the Warp desktop app applies to local agent runs only. Cloud runs of Claude Code and Codex always use Warp-managed secrets. +::: + +## Connecting Claude Code credentials + +Claude Code is Anthropic's agentic coding tool. For more on Claude Code authentication, see [Anthropic's Claude Code auth docs](https://code.claude.com/docs/en/authentication). + +### Create an Anthropic API key + +1. Go to the [Anthropic Console](https://platform.claude.com/login?returnTo=/?) and sign in (or create an account). +2. Navigate to **API keys** and create a new key. +3. Make sure your account has API credits — Claude Code runs are billed against your Anthropic API balance. + +Oz also supports Bedrock-routed credentials (**Anthropic Bedrock API key** and **Anthropic Bedrock access key**) if your team consumes Anthropic models through AWS. + +### Store the key in Oz + +#### Warp desktop app + +In Cloud Mode, click the key icon above the input and add your Anthropic credential. + +#### Oz web app + +Start a new run, choose **Claude Code** as the harness, and add a new key in the harness auth secrets dropdown. + +#### Oz CLI + +```bash +oz secret create claude api-key --team +``` + +Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. + +**Expected outcome.** `oz secret list` shows the new secret with the matching Anthropic credential type. The value is never displayed. + +## Connecting Codex credentials + +Codex is OpenAI's coding agent. For more on Codex authentication, see [OpenAI's Codex auth docs](https://developers.openai.com/codex/auth). + +:::caution +A ChatGPT subscription (Plus, Pro, Team) does not include API access. You need a separate OpenAI API key with API credits. +::: + +### Create an OpenAI API key + +1. Go to the [OpenAI Platform](https://platform.openai.com/) and sign in (or create an account). +2. Navigate to **API keys** and click **Create new secret key**. +3. Make sure your account has API credits — Codex runs are billed against your OpenAI API balance, not a ChatGPT subscription. + +### Store the key in Oz + +#### Warp desktop app + +In Cloud Mode, click the key icon above the input and add your OpenAI credential. + +#### Oz web app + +Start a new run, choose **Codex** as the harness, and add a new key in the harness auth secrets dropdown. + +#### Oz CLI + +```bash +oz secret create codex api-key --team +``` + +Add `--description "..."` to record rotation notes or owner info. Replace `--team` with `--personal` to make the secret available only to your own runs. + +**Expected outcome.** `oz secret list` shows the new secret with the matching OpenAI credential type. The value is never displayed. + +## Managing harness auth secrets + +Auth secrets follow the same management commands as any other Warp-managed secret. See [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) for the full reference. Common tasks: + +```bash +# List secrets you can see +oz secret list + +# Rotate a secret value (prompts for the new value) +oz secret update --team --value ANTHROPIC_API_KEY + +# Update the description +oz secret update --team --description "Rotated 2026-05-12; owned by platform team" ANTHROPIC_API_KEY + +# Delete a secret (irreversible) +oz secret delete --team ANTHROPIC_API_KEY +``` + +:::caution +Deleting an auth secret breaks any scheduled or integration-triggered run that references it by name. Update the schedules and integrations to point at a new secret first. +::: + +## 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. + +**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. + +**The selected harness is disabled.**\ +Your team admin has disabled the harness for your workspace. Contact your admin or pick a different harness for the run. + +## Related pages + +* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — overview of third-party harnesses in Oz. +* [Claude Code in Warp](/agent-platform/cli-agents/claude-code/) — run Claude Code locally in the Warp terminal. +* [Codex CLI in Warp](/agent-platform/cli-agents/codex/) — run Codex locally in the Warp terminal. +* [Cloud agent secrets](/agent-platform/cloud-agents/secrets/) — the full Warp-managed secrets reference. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx new file mode 100644 index 0000000..c869e47 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/claude-code.mdx @@ -0,0 +1,55 @@ +--- +title: Claude Code with Oz +description: >- + Run Claude Code with Oz. Strong at code review, deep bug investigation, large + feature planning, and frontend or UI work. +sidebar: + label: "Claude Code" +--- + +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 — 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](/agent-platform/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. +* **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 code-review-heavy or judgment-heavy steps within a larger orchestration. + +## Available models + +The Claude Code harness exposes Anthropic's coding-tuned model lineup. Common picks: + +* `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. + +## Credentials and billing + +Claude Code calls Anthropic directly using credentials your team provides. Oz supports three Anthropic credential types, stored as [Warp-managed secrets](/agent-platform/cloud-agents/secrets/): + +* **Anthropic API key** - For direct Anthropic API access. +* **Anthropic Bedrock API key** - For Bedrock-routed inference using an API key. +* **Anthropic Bedrock access key** - For Bedrock-routed inference using AWS access credentials. + +Anthropic bills your account directly for inference. Warp still meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run's sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the orchestration layer. + +For setup steps, see [Connecting Claude Code credentials](/agent-platform/cloud-agents/harnesses/authentication/#connecting-claude-code-credentials). + +## 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. +* **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](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex. +* [Authentication](/agent-platform/cloud-agents/harnesses/authentication/) — store Anthropic credentials as Warp-managed secrets. +* [Warp Agent with Oz](/agent-platform/cloud-agents/harnesses/warp-agent/) — Oz's default harness, the only one that can orchestrate Claude Code subagents. +* [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness. +* [Claude Code in Warp](/agent-platform/cli-agents/claude-code/) — Claude Code in your local Warp terminal. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx new file mode 100644 index 0000000..600ea9a --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/codex.mdx @@ -0,0 +1,54 @@ +--- +title: Codex with Oz +description: >- + Run Codex with Oz. Strong at codebase migrations, release coordination, batch + test generation, and backend or DevOps automation. +sidebar: + label: "Codex" +--- + +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 — 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](/agent-platform/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. +* **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. + +## Available models + +The Codex harness exposes OpenAI's Codex-tuned and general coding models. Common picks: + +* `default` - Lets Codex pick its own recommended model based on your OpenAI account access. +* `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 older 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). + +## Credentials and billing + +Codex calls OpenAI directly using credentials your team provides. Oz supports one credential type today, stored as a [Warp-managed secret](/agent-platform/cloud-agents/secrets/): + +* **OpenAI API key** - The Codex harness authenticates to OpenAI using this key for every run. + +OpenAI bills your account directly for inference. Warp still meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run's sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the orchestration layer. + +For setup steps, see [Connecting Codex credentials](/agent-platform/cloud-agents/harnesses/authentication/#connecting-codex-credentials). + +## 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. +* **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](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex. +* [Authentication](/agent-platform/cloud-agents/harnesses/authentication/) — store OpenAI credentials as Warp-managed secrets. +* [Warp Agent with Oz](/agent-platform/cloud-agents/harnesses/warp-agent/) — Oz's default harness, the only one that can orchestrate Codex subagents. +* [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness. +* [Codex CLI in Warp](/agent-platform/cli-agents/codex/) — Codex in your local Warp terminal. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx new file mode 100644 index 0000000..b7e0064 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx @@ -0,0 +1,49 @@ +--- +title: Harnesses in Oz +description: >- + Run Claude Code or Codex as cloud agents. Both inherit the same triggers, + environments, secrets, and observability as Warp Agent. +sidebar: + label: "Overview" +--- + +Oz can run third-party agents — [Claude Code](/agent-platform/cloud-agents/harnesses/claude-code/) and [Codex](/agent-platform/cloud-agents/harnesses/codex/) — as cloud agents alongside Warp Agent. You choose the harness (agent runtime) that fits the task; the platform around the run stays the same. + +## What stays the same + +Third-party harnesses inherit the same Oz platform features as Warp Agent: + +* **Triggers** — Slack, Linear, schedules, CI, and API [triggers](/agent-platform/cloud-agents/triggers/) launch any harness. +* **Environments and secrets** — Reuse the same [environments](/agent-platform/cloud-agents/environments/) and [agent secrets](/agent-platform/cloud-agents/secrets/). +* **Skills and Rules** — Saved [Skills](/agent-platform/capabilities/skills/) and [Rules](/agent-platform/capabilities/rules/) apply across harnesses. +* **Observability** — Every run produces a transcript and shareable session in the [Oz dashboard](/agent-platform/cloud-agents/managing-cloud-agents/). + +## Billing + +Claude Code and Codex each call their provider directly using credentials you supply, and the provider bills your account for inference. Warp meters [compute credits](/support-and-community/plans-and-billing/credits/#compute-credits) for the run's sandbox and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the orchestration layer. + +## How to switch harnesses + +### Warp desktop app + +In Cloud Mode, choose a harness from the **Agent harness** dropdown above the input. + +:::note +You can enter Cloud Mode by creating a new **Cloud Agent** tab or by using the `/cloud-agent` slash command. +::: + +### Oz web app + +On the new run or new schedule pane, choose the harness in the **Harness** field. + +### API and SDK + +Set the `harness` field on the agent config. See the [API reference](/reference/api-and-sdk/) for the exact field names. + +## Related pages + +* [Warp Agent with Oz](/agent-platform/cloud-agents/harnesses/warp-agent/) — Oz's default first-party harness. +* [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness. +* [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness. +* [Authentication](/agent-platform/cloud-agents/harnesses/authentication/) — connect credentials and launch Claude Code or Codex. +* [Third-party CLI agents in the Warp terminal](/agent-platform/cli-agents/overview/) — run Claude Code, Codex, and other CLI agents locally. diff --git a/src/content/docs/agent-platform/cloud-agents/harnesses/warp-agent.mdx b/src/content/docs/agent-platform/cloud-agents/harnesses/warp-agent.mdx new file mode 100644 index 0000000..1dcc137 --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/harnesses/warp-agent.mdx @@ -0,0 +1,69 @@ +--- +title: Warp Agent with Oz +description: >- + Warp Agent is Oz'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" +--- + +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 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. + +## Key features + +* **Multi-model auto-routing** - Routes between Anthropic, OpenAI, Google, and Fireworks-hosted models. Choose a specific model, or let Warp pick via `auto`, `auto-efficient`, `auto-genius`, or `auto-open`. See [Model choice](/agent-platform/capabilities/model-choice/) for the full catalog. +* **Full terminal and tool access** - Runs commands, edits files, reads logs, executes tests, navigates repos, and calls MCP servers — the same toolbelt Warp Agent uses locally. +* **Platform-native context** - Reads [Codebase Context](/agent-platform/capabilities/codebase-context/), applies [Rules](/agent-platform/capabilities/rules/), reuses saved [Skills](/agent-platform/capabilities/skills/), and respects Memory and Warp Drive context with no extra setup. +* **Multi-repo execution** - Clones every repo configured on the [environment](/agent-platform/cloud-agents/environments/) and works across them in a single run. +* **Cross-harness orchestration parent** - A Warp Agent parent run can spawn Claude Code or Codex [subagents](/agent-platform/cloud-agents/overview/) and coordinate their outputs. Other harnesses cannot act as parents in a multi-harness orchestration. +* **No extra credentials** - Warp Agent uses your existing Warp account and credits. There's no separate API key to configure. + +## 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](/agent-platform/cloud-agents/environments/), triggers, observability, and team governance around the run, and the transcript is inspectable in real time and replayable afterward from the [Oz dashboard](/agent-platform/cloud-agents/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. + +### Available models + +Warp Agent supports the full Warp model catalog. Configure the model per [Agent Profile](/agent-platform/capabilities/agent-profiles-permissions/), or pick one at run time. See [Model choice](/agent-platform/capabilities/model-choice/) for the supported model IDs, including the `auto`, `auto-efficient`, `auto-genius`, and `auto-open` routing options. + +### Cross-harness orchestration + +Warp Agent is the orchestration host for multi-harness runs. A typical pattern: + +1. A Warp Agent parent run analyzes a task and breaks it into subtasks. +2. The parent dispatches Claude Code subagents for code-review-heavy steps and Codex subagents for high-volume edits. +3. The parent collects results, resolves conflicts, and returns a single final output (a PR, a report, a Slack reply). + +Subagents run in the same environment as the parent and share the same secrets, MCP servers, and integrations. The transcript shows the full tree, so reviewers can see exactly which subagent did what. + +## When to choose Warp Agent + +* The task spans multiple repos, languages, or domains. +* You want model auto-routing instead of pinning one provider. +* The run needs to orchestrate other harnesses as subagents. +* You want the deepest integration with Warp's platform features (Skills, Rules, Memory, Codebase Context). +* You're not sure which harness fits — Warp Agent is the safe default and can delegate to other harnesses when it decides that's the better fit. + +## Starting a Warp Agent run + +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. +* **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](/agent-platform/cloud-agents/quickstart/). + +## Related pages + +* [Harnesses in Oz](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex. +* [Claude Code with Oz](/agent-platform/cloud-agents/harnesses/claude-code/) — Claude Code as a cloud harness. +* [Codex with Oz](/agent-platform/cloud-agents/harnesses/codex/) — Codex as a cloud harness. +* [Model choice](/agent-platform/capabilities/model-choice/) — the model catalog Warp Agent routes across. +* [Agent Profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/) — configure the default model, autonomy, and tool access for Warp Agent. +* [Skills as agents](/agent-platform/cloud-agents/skills-as-agents/) — turn a saved skill into a reusable Warp Agent run. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx index 4036cdd..f19a284 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/cloud-providers.mdx @@ -187,8 +187,8 @@ Replace `` with the UID of your Warp team. This is the last component panel URL is `https://app.warp.dev/admin/abc123def456`, your team UID would be `abc123def456`. :::caution -If you do not set an attribute condition, then _any_ agent will be able to use your Workload -Identity Federation provider, even if they do not belong to your team. +If you do not set an attribute condition, then _any cloud agent_ will be able to use your Workload +Identity Federation provider, even if it does not belong to your team. ::: ### Step 2: Configure IAM policies diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx index 5cafabb..3f112fd 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx @@ -66,7 +66,7 @@ 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 (any type of Warp credits work). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. +* **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](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email as your Linear workspace. * **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx index 44d19b0..b37d510 100644 --- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx +++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx @@ -7,7 +7,7 @@ description: >- pull requests. --- -The Slack integration lets your team trigger Oz cloud agents directly from Slack conversations. Tag @Oz 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. +The Slack integration lets your team trigger cloud agents directly from Slack conversations. Tag @Oz 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. ### Overview @@ -82,7 +82,7 @@ Because PRs are created as you, the workflow slots seamlessly into your team’s ### 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 (any type of Warp credits work). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. +* **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](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email used in your Slack workspace. * **GitHub authorization** - You must authorize the **Warp GitHub app** the first time you trigger a Slack integration request. diff --git a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx index c5a96f1..087b5d6 100644 --- a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx @@ -99,3 +99,10 @@ In both _Personal_ and _All_ views, you can open the filter menu and filter by: * Status This is the fastest way to isolate "everything that failed today," "runs from Slack," or "what a specific teammate triggered via integrations." + +## Related pages + +* [Cloud agents overview](/agent-platform/cloud-agents/overview/) — What cloud agents are and when to use them. +* [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) — Open and inspect a remote cloud agent run. +* [Handoff between local and cloud agents](/agent-platform/cloud-agents/handoff/) — Move agent work between local and cloud, or continue a finished cloud run. +* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) — Manage runs and schedules from any browser. diff --git a/src/content/docs/agent-platform/cloud-agents/overview.mdx b/src/content/docs/agent-platform/cloud-agents/overview.mdx index ec6a882..4c35494 100644 --- a/src/content/docs/agent-platform/cloud-agents/overview.mdx +++ b/src/content/docs/agent-platform/cloud-agents/overview.mdx @@ -113,15 +113,15 @@ Cloud agents and [integrations](/agent-platform/cloud-agents/integrations/) run [Bring Your Own Key (BYOK)](/support-and-community/plans-and-billing/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. ::: -#### For Cloud Agents via CLI/API +#### For cloud agents via CLI/API Individual users can run cloud agents without being on a team. Requirements: -* You need at least 20 credits (any type: normal Warp credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), or Build plan credits) +* You need at least 20 credits available * Cloud agents run on Warp-hosted infrastructure * Self-hosted agents require a team subscription -#### For Integrations (Slack/Linear) +#### For integrations (Slack/Linear) Integrations require you to be part of a [Warp team](/knowledge-and-collaboration/teams/) and additional requirements: @@ -130,9 +130,7 @@ Integrations require you to be part of a [Warp team](/knowledge-and-collaboratio * Not supported: Pro, Turbo, Lightspeed, legacy Business * Your plan must support Add-on Credits. * **Credit requirements** - * Your team must have at least 20 credits available (any type of Warp credits work) to run cloud agents and integrations. - * Usage is billed based on credit type and team configuration. - * Normal credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), and [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) all work. + * Your team must have at least 20 credits available to run cloud agents and integrations. For more details, see [Access, Billing, and Identity Permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/). @@ -146,6 +144,8 @@ If your credit balance reaches zero, cloud agent runs will not be able to execut * [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) — run your first cloud agent with an environment in ~10 minutes. * [Oz Platform](/agent-platform/cloud-agents/platform/) — CLI, Oz API/SDK, orchestration, tasks, environments, hosts, integrations, and more. +* [Harnesses](/agent-platform/cloud-agents/harnesses/) — pick between Warp Agent, Claude Code, and Codex for any cloud agent run. +* [Agent identities](/agent-platform/cloud-agents/agents/) — team-scoped bot accounts that own and execute cloud agent runs. * [Skills as Agents](/agent-platform/cloud-agents/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. * [Environments](/agent-platform/cloud-agents/environments/) — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks. diff --git a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx index eebe417..6d29a54 100644 --- a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx +++ b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx @@ -1,5 +1,5 @@ --- -title: Oz Web App for cloud agents +title: Oz web app for cloud agents description: >- Use the Oz web app to manage cloud agents, view runs, create schedules, and configure environments and integrations from any browser or mobile device. @@ -19,10 +19,10 @@ Watch this short demo to create an environment and run an agent using the Oz web ## Quick reference -
PagePathWhat you can do
Dashboard/dashboardQuick actions, suggested agents, recent agents, and featured reads
Runs/runsView all runs, filter by status/source/creator, start new runs, inspect transcripts
Agents/agentsBrowse skills from your environments, view suggested skills, dispatch skills as agents
Schedules/schedulesCreate scheduled agents, pause/enable schedules, view run history
Environments/environmentsCreate and manage environments with repos, Docker images, and setup commands
Integrations/integrationsConnect Slack and Linear to trigger agents from external tools
+
PagePathWhat you can do
Dashboard/dashboardQuick actions, suggested agents, recent agents, and featured reads
Runs/runsView all runs, filter by status/source/creator, start new runs, inspect transcripts
Agents/agentsBrowse skills from your environments, manage agent identities, dispatch skills as agents
Schedules/schedulesCreate scheduled agents, pause/enable schedules, view run history
Environments/environmentsCreate and manage environments with repos, Docker images, and setup commands
Secrets/secretsCreate and manage Warp-managed secrets for cloud agent runs
Integrations/integrationsConnect Slack and Linear to trigger agents from external tools
-![The Oz Web App's management view.](../../../../assets/agent-platform/oz-web-app-runs-view.png) +![The Oz web app's management view.](../../../../assets/agent-platform/oz-web-app-runs-view.png)
The Oz web app management view.
@@ -119,7 +119,12 @@ The skill provides base instructions; your prompt adds context for this particul ## Agents -The **Agents** page (`/agents`) shows all skills available from your environments, plus suggested skills from Warp's public [oz-skills repository](https://github.com/warpdotdev/oz-skills). +The **Agents** page (`/agents`) covers two related but distinct concepts: + +* **Skills** - Reusable instruction sets stored in repositories that an agent can execute. Browse skills available from your environments, plus suggested skills from Warp's public [oz-skills repository](https://github.com/warpdotdev/oz-skills). +* **Agent identities** - Team-scoped bot accounts that own and execute runs. The same page is where teams create and manage agent identities, attach descriptions and secrets to them, and bind API keys to a specific identity. + +For the full reference on agent identities — including plan limits, the REST endpoints, and how to run as a specific identity — see [Agent identities](/agent-platform/cloud-agents/agents/). ### Skill details @@ -128,7 +133,7 @@ Each skill displays:
FieldDescription
NameThe skill's identifier
DescriptionWhat the skill does
EnvironmentsWhich environments have access to this skill
-![The Agents page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-agents.png) +![The Agents page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-agents.png)
The Agents page in the Oz web app.
@@ -142,15 +147,43 @@ Click any skill to view its details, then click **Run** to start an agent with t For more details on how skills work with cloud agents, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). ::: -### Creating new agents +### Creating new skills -Click **New agent** to create a new skill. The guided flow helps you define the skill's instructions, which are then available for future runs. +Click **New skill** to create a new skill. The guided flow helps you define the skill's instructions, which are then available for future runs.
-![Creating a new agent skill in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-new-agent.png) -
Creating a new agent skill in the Oz web app.
+![Creating a new agent skill in the Oz web app.](../../../../assets/agent-platform/oz-web-app-new-agent.png) +
Creating a new skill in the Oz web app.
+### Agent identities + +Agent identities are managed from the same Agents page. From the agent-identities view, you can: + +* **Create an agent identity** - Give it a name, an optional description, a default model and harness, and the secrets and skills runs as that identity should receive. +* **Edit an existing identity** - Update its description, attached secrets, attached skills, or default configuration. +* **Delete an identity** - Soft-deletes the identity and atomically deletes every API key bound to it. The default agent identity cannot be deleted. + +When you start a new run or schedule from the web app, the form's **Agent** dropdown lets you pick which agent identity should execute the run. **Quick run** is the default option and runs as your own user. See [Agent identities](/agent-platform/cloud-agents/agents/) for the full reference. + +#### Creating an agent identity + +Click **New agent** to open the **New agent** side pane. The pane is split into collapsible sections; only the name is required. Walk through the fields in order: + +1. **Name** (required) — A short, scriptable identifier for the identity, such as `featureFlagRemover` or `deploy-bot`. +2. **Description** (optional) — A summary teammates see when picking the identity in run pickers. +3. **Prompt** (optional) — Additional instructions appended to every run started as this identity. +4. **Skills** — Use the multi-select to attach one or more skill specs the identity comes preloaded with. +5. **Base harness** — Choose the execution harness for this identity's runs: Oz (the default) or a supported third-party CLI agent. +6. **Base model** — When the chosen harness uses Warp's model picker, select the primary model the identity uses. You can leave this empty to fall back to the team default. +7. **Harness auth secret** — When the chosen harness needs its own authentication (for example, a third-party CLI agent), pick the Warp-managed secret to authenticate with. Can be overridden per run. +8. **Secrets** — Open the **Secrets** section and select the [Warp-managed secrets](/agent-platform/cloud-agents/secrets/) this identity should receive at run time. +9. **Memory stores** — Attach the memory stores this identity should read from or write to. + +Click **Create agent** to save. The new identity appears on the Agents page and is immediately available in run and schedule pickers. To edit an existing identity later, click it in the list, then click **Edit**. + +For the conceptual model — plan limits, the REST endpoints, and how API keys are bound to an identity — see [Agent identities](/agent-platform/cloud-agents/agents/). + --- ## Schedules @@ -164,7 +197,7 @@ Each schedule displays:
FieldDescription
NameA descriptive name for the scheduled task
FrequencyHuman-readable description of the cron schedule (e.g., "Every Monday at 10am")
Next runWhen the schedule will next execute
EnvironmentWhich environment the scheduled agent runs in
AgentWhich skill the schedule uses (if any)
StatusWhether the schedule is active or paused
-![The Schedules page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-schedules.png) +![The Schedules page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-schedules.png)
The Schedules page in the Oz web app.
@@ -210,7 +243,7 @@ Each environment displays:
FieldDescription
NameThe environment's identifier
Docker imageThe container image used for execution
RepositoriesWhich repos the agent can access
Setup commandsCommands run before the agent starts
-![The Environments page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-environments.png) +![The Environments page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-environments.png)
The Environments page in the Oz web app.
@@ -242,7 +275,7 @@ The **Integrations** page (`/integrations`) lets you configure first-party integ
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
-![The Integrations page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-integrations.png) +![The Integrations page in the Oz web app.](../../../../assets/agent-platform/oz-web-app-integrations.png)
The Integrations page in the Oz web app.
@@ -259,6 +292,7 @@ For detailed integration setup instructions, see [Slack](/agent-platform/cloud-a ## Related resources * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — Learn about cloud agents and when to use them +* [Agent identities](/agent-platform/cloud-agents/agents/) — Team-scoped bot accounts that own and execute runs * [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) — Run agents based on reusable skill definitions * [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [Environments](/agent-platform/cloud-agents/environments/) — Configure runtime context for cloud agents diff --git a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx index c5b1bb6..7cd15eb 100644 --- a/src/content/docs/agent-platform/cloud-agents/quickstart.mdx +++ b/src/content/docs/agent-platform/cloud-agents/quickstart.mdx @@ -157,7 +157,7 @@ Use official Docker Hub images like `node`, `python`, or `rust` for best compati Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `. **Not enough credits to run cloud agents**\ -Your team needs at least 20 credits available (any type of Warp credits work). Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. +Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. **More resources** diff --git a/src/content/docs/agent-platform/cloud-agents/secrets.mdx b/src/content/docs/agent-platform/cloud-agents/secrets.mdx index e2caff3..28e5622 100644 --- a/src/content/docs/agent-platform/cloud-agents/secrets.mdx +++ b/src/content/docs/agent-platform/cloud-agents/secrets.mdx @@ -13,7 +13,7 @@ Warp-managed secrets are designed to work across [cloud agent](/agent-platform/c **Warp-managed secrets are useful when:** -* An cloud agent needs to call an API or CLI that does not support OAuth +* A cloud agent needs to call an API or CLI that does not support OAuth * You are using [MCP servers](/agent-platform/cloud-agents/mcp/) that expect static tokens or keys * An agent needs credentials for tools like cloud CLIs, databases, monitoring systems, or internal services * You want centralized auditing and control over what credentials agents can access @@ -30,7 +30,7 @@ Warp-managed secrets are designed to work across [cloud agent](/agent-platform/c Warp provides a set of CLI commands for creating, updating, and listing secrets. Secret values are stored securely and cannot be retrieved once created. -At runtime, **Warp sets the relevant secrets as environment variables** for each cloud agent run, based on who triggered the agent and how it was triggered. +At runtime, **Warp sets the relevant secrets as environment variables** for each cloud agent run, based on who triggered the agent and how it was triggered. :::note Secret values are available only to the agent process (and any subprocesses it spawns) during execution, and **can’t be viewed or retrieved afterward.** @@ -57,7 +57,7 @@ Team secrets are shared across the entire team and are available to all cloud ag * Ideal for shared infrastructure credentials, service accounts, and read-only API keys :::note -Because team secrets are broadly available and may be used by fully automated or scheduled agents, they should generally be created **using bot or service accounts**, rather than credentials tied to an individual person. +Because team secrets are broadly available and may be used by fully automated or scheduled agents, they should generally be created **using bot or service accounts**, rather than credentials tied to an individual person. When you want a credential to be available to one workflow only, attach it to an [agent identity](/agent-platform/cloud-agents/agents/) instead of giving every run access to it. ::: **For example:** @@ -68,6 +68,10 @@ Because team secrets are broadly available and may be used by fully automated or This ensures credentials remain valid as team membership changes, permissions are tightly scoped, and ownership and rotation align with internal security policies. +:::note +Team secrets can also be attached directly to an [agent identity](/agent-platform/cloud-agents/agents/), so only runs executing as that identity receive them. The secret itself still lives in the team's secret scope; the agent identity only references it by name. +::: + #### Personal secrets Personal secrets belong to an **individual user**. @@ -78,9 +82,27 @@ Personal secrets belong to an **individual user**. --- +## Creating secrets in the Oz web app + +The [Oz web app](/agent-platform/cloud-agents/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. +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. +5. Optionally, enter a **Description** to help teammates identify the secret later. +6. Choose a **Scope** — **Team** to share the secret with everyone on the team, or **Personal** to keep it scoped to your user. +7. Click **Create secret**. + +The new secret appears in the Secrets list immediately. Its value is never readable from the UI after creation; to rotate the value, edit the secret and submit a new one. + +--- + ## Managing agent secrets with the Oz CLI -Secrets are managed using the oz secret command family. +Secrets are managed using the `oz secret` command family. You can create secrets interactively or from a file. @@ -181,7 +203,7 @@ MY_MCP_SERVER_TOKEN personal 10:00am ### How secrets are made available to cloud agents -When an cloud agent starts, Warp determines which secrets are in scope and sets them as environment variables in the agent’s execution environment. +When a cloud agent starts, Warp determines which secrets are in scope and sets them as environment variables in the agent’s execution environment. Today, secrets are provided as environment variables using the secret name as the variable name. For example: @@ -225,6 +247,48 @@ Personal secrets are never injected in these cases. --- +## Scoping secrets to environments and runs + +Owner scoping (team versus personal) controls **which secrets exist** for a caller. Two additional layers — environments and individual runs — let you narrow **which of those secrets are actually injected** for a given execution. Together with [agent identities](/agent-platform/cloud-agents/agents/), these layers form a broader access-scoping model where each layer contributes the secrets a run ends up with at execution time. + +### Environment-level scoping + +A [cloud environment](/agent-platform/cloud-agents/environments/) can declare its own list of secrets. When a run uses that environment, the environment's attached secrets are added to the run's allowlist by default. The run can still narrow the allowlist further by passing its own `secrets` list, which then takes precedence. Use this when a workflow's runtime needs a known, fixed set of credentials — for example, an `ops-tools` environment that only needs `DEPLOY_TOKEN` and `PAGERDUTY_API_KEY`. + +#### Attach secrets to an environment + +Use the environment form in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) to attach secrets to an environment: + +1. In the Oz web app (oz.warp.dev), 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. +5. Click **Save**. + +#### Attachment semantics + +Environment-attached secrets behave as follows at run time: + +* **Secret names, not values** - The environment stores references by name. Underlying values stay in the team or personal secret scope, so rotating a value takes effect on the next run without re-attaching the secret. +* **Owner scope still applies** - A run only receives an attached secret if the trigger's owner scope already allows it. Personal secrets are still skipped for triggers without a user context, as described under [Secret availability by trigger type](#secret-availability-by-trigger-type). +* **Resolved at run start** - Warp resolves the environment's attached secrets when the run starts. If a referenced secret has been deleted or renamed since attachment, the run continues and the missing reference is surfaced in the run detail view. + +### Run-level scoping + +Individual runs can override which secrets the run receives by listing them on the run's config: + +* **Default (no list provided)** - The run inherits every secret the creator or team has access to that is in scope for the trigger, exactly as described under [Secret availability by trigger type](#secret-availability-by-trigger-type). +* **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. + +:::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. +::: + +--- + ### Auditing and security considerations Warp is designed to make secret usage auditable and predictable: diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx index bbeab5a..93bde90 100644 --- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx +++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx @@ -18,7 +18,7 @@ Cloud agents can be used in two ways: **Individual users** (without a team): * Can run cloud agents via CLI or API -* Can use normal Warp credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), or a Build plan with available credits +* Can use Warp credits, including [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) * Agents run on Warp-hosted infrastructure * Cannot use integrations (Slack, Linear) or self-hosted agents @@ -27,7 +27,7 @@ Cloud agents can be used in two ways: * Can use integrations (Slack, Linear) to trigger agents * Can self-host agents on their own infrastructure (Enterprise only) * Share team-level configuration (environments, secrets, integrations) -* Team must be on Build, Max, or Business plan with at least 20 credits (any type) for cloud agents and integrations +* Team must be on Build, Max, or Business plan with at least 20 credits for cloud agents and integrations --- @@ -38,7 +38,7 @@ Individual users can run cloud agents via the CLI or API without being part of a **How it works:** * Run agents using `oz agent run-cloud` or the Oz API -* Credits are drawn from your normal Warp credits, Cloud Agent Credits (if available), or Build plan credits +* Credits are drawn from your Warp credits (including cloud agent credits, when applicable) * Agents execute on Warp-hosted infrastructure **What you can do:** @@ -76,12 +76,12 @@ Integrations and [cloud agents](/agent-platform/cloud-agents/overview/) run insi Your team must meet the following requirements to run integrations: -* You must be on a plan that supports **[Reload Credits (Add-on Credits)](/support-and-community/plans-and-billing/add-on-credits/)**. +* You must be on a plan that supports **[Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/)**. * Supported: **Build, Max, Business** * Not supported: Pro, Turbo, Lightspeed, legacy Business. -* Your team needs at least **20 credits** available to run cloud agents and integrations (any type of Warp credits work) +* Your team needs at least **20 credits** available to run cloud agents and integrations -When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits in a specific order. It starts with any [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits) the user has, then moves to the user's base credits, followed by the team's Reload Credits, and finally the user's own Reload Credits. Enterprises may have different payment options and credit plans that affect this flow. If all applicable credit sources are exhausted, integrations and cloud agents will not work until credits are added. +When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits in a specific order. It starts with any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then moves to the user's base credits, followed by the team's Add-on Credits, and finally the user's own Add-on Credits. Enterprises may have different payment options and credit plans that affect this flow. If all applicable credit sources are exhausted, integrations and cloud agents will not work until credits are added. :::note If you're on an Enterprise plan, please reach out to [warp.dev/contact-sales](https://warp.dev/contact-sales) with any billing questions related to integrations. @@ -212,12 +212,12 @@ How credits are consumed depends on how the agent run is triggered and authentic **User-triggered runs** (CLI with personal API key, Slack, Linear, or the Warp app): * Runs are tied to the triggering user's identity -* Credits are consumed starting with any credit grants specifically allocated for cloud agent usage, then the user's base credits, followed by the team's Reload Credits, and finally the user's own Reload Credits +* Credits are consumed starting with any credit grants specifically allocated for cloud agent usage, then the user's base credits, followed by the team's Add-on Credits, and finally the user's own Add-on Credits **Team API key runs** (fully automated or headless workflows): * Runs are not tied to any individual user -* Only the team's Reload Credit pool is used—no individual base credits are available +* Only the team's Add-on Credit pool is used—no individual base credits are available * Ideal for CI/CD pipelines, scheduled tasks, and other automated workflows * For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Oz by Warp GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. @@ -236,7 +236,7 @@ All triggers and instructions used by cloud agents are defined and controlled by #### Staying aware of usage -Because triggers and instructions are configured by your team, any credits used when an agent runs are billed to your team's Reload Credit balance. +Because triggers and instructions are configured by your team, any credits used when an agent runs are billed to your team's Add-on Credit balance. * It’s the team’s responsibility to manage triggers, confirm they behave as intended, and monitor usage. * Reviewing triggers, prompts, and agent behavior periodically helps ensure that credit usage aligns with expectations. diff --git a/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx b/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx index 41698cb..68af4ce 100644 --- a/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx +++ b/src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx @@ -71,6 +71,8 @@ If you still want to continue the conversation or work on the code, you can clic #### 5. Fork the session to your local Warp +Forking is the cloud-to-local direction of [Handoff between local and cloud agents](/agent-platform/cloud-agents/handoff/) — see that page for the other directions (local-to-cloud and cloud-to-cloud). + Forking brings the cloud agent conversation into your local machine, so you can pick up where the agent left off. Once forked: diff --git a/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx b/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx index 43b33c0..9a97d15 100644 --- a/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx +++ b/src/content/docs/agent-platform/getting-started/agents-in-warp.mdx @@ -6,7 +6,7 @@ description: >- --- import VideoEmbed from '@components/VideoEmbed.astro'; -Warp includes Oz agents that help you write code, debug issues, and complete terminal workflows from natural language prompts. Agents operate with full context from your codebase, Warp Drive, and connected tools while you control their autonomy, permissions, and model choices. +Warp's agents help you write code, debug issues, and complete terminal workflows from natural language prompts. They operate with full context from your codebase, Warp Drive, and connected tools while you control their autonomy, permissions, and model choices. diff --git a/src/content/docs/agent-platform/local-agents/cloud-conversations.mdx b/src/content/docs/agent-platform/local-agents/cloud-conversations.mdx index 07a983b..9e32fcd 100644 --- a/src/content/docs/agent-platform/local-agents/cloud-conversations.mdx +++ b/src/content/docs/agent-platform/local-agents/cloud-conversations.mdx @@ -136,3 +136,4 @@ When you delete a conversation, it is removed permanently and immediately. Make * [Conversation Forking](/agent-platform/local-agents/interacting-with-agents/conversation-forking/) - Branch conversations to explore different directions. * [Session Sharing](/agent-platform/local-agents/session-sharing/) - Collaborate in real time on a live Agent session. * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) - Run agents in the cloud from triggers, schedules, or integrations. +* [Handoff between local and cloud agents](/agent-platform/cloud-agents/handoff/) - Promote a local conversation to a cloud agent run, or continue a finished cloud run. diff --git a/src/content/docs/enterprise/support-and-resources/billing.mdx b/src/content/docs/enterprise/support-and-resources/billing.mdx index 5a76c76..b9f9146 100644 --- a/src/content/docs/enterprise/support-and-resources/billing.mdx +++ b/src/content/docs/enterprise/support-and-resources/billing.mdx @@ -31,11 +31,11 @@ Credit allocations vary by contract. Contact your account manager for details on ## Cloud agent billing -Cloud agents consume credits that include a small hosting fee in addition to AI usage costs. +Cloud agents consume AI credits for inference, compute credits for the sandbox they run in, and platform credits for the orchestration layer. See [Credits](/support-and-community/plans-and-billing/credits/) for the full breakdown of how each credit type is metered. ### How credits are consumed -On Enterprise plans, both local and cloud agent usage draw from the same team credit pool. There are no separate "cloud agent credits" or "local credits" — all agent usage consumes from your available credit sources. +On Enterprise plans, local and cloud agent usage both draw from the same team credit pool across all three credit types (AI credits, compute credits, and platform credits). The credit type a run consumes depends on what infrastructure it uses, not on whether it's local or cloud. For team API key runs (e.g., CI/CD pipelines, scheduled tasks), credits also draw from the team's shared pool since these runs are not tied to any individual user. diff --git a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx index 531b94d..72433c1 100644 --- a/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx +++ b/src/content/docs/reference/api-and-sdk/troubleshooting/errors/external-authentication-required.mdx @@ -101,7 +101,7 @@ This error includes extra fields beyond the standard response format: 2. Ensure the app has access to all repositories listed in `inaccessible_repos`. 3. Retry the task. -If you are using a **team API key** (service account), ensure the Warp GitHub App is installed on the organization that owns the repositories. +If you are using a **team API key** bound to an [agent identity](/agent-platform/cloud-agents/agents/), ensure the Warp GitHub App is installed on the organization that owns the repositories. ### Account matching failed diff --git a/src/content/docs/reference/cli/federate.mdx b/src/content/docs/reference/cli/federate.mdx index 4f1e0fa..ecfcc9d 100644 --- a/src/content/docs/reference/cli/federate.mdx +++ b/src/content/docs/reference/cli/federate.mdx @@ -1,7 +1,7 @@ --- title: Federated identity tokens description: >- - Issue short-lived OIDC identity tokens from a running Oz agent so it can + Issue short-lived OIDC identity tokens from a running agent so it can authenticate to cloud providers without long-lived credentials. sidebar: label: "Federated identity" @@ -9,7 +9,7 @@ sidebar: `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. -This command can only be called from inside a running Oz agent session — typically as part of a [skill](/agent-platform/capabilities/skills/), a tool, or a script the agent executes while a run is in progress. +This command can only be called from inside a running agent session — typically as part of a [skill](/agent-platform/capabilities/skills/), a tool, or a script the agent executes while a run is in progress. ## When to use federation @@ -44,7 +44,7 @@ oz federate issue-token \ The subject claim is what your cloud provider's policy will match on, so pick the combination that gives you the IAM granularity you need. Supported components: -* **`principal`** - The acting principal, like `user:my-user-id` or `service_account:my-sa-id`. +* **`principal`** - The acting principal, like `user:my-user-id` or `service_account:my-sa-id`. A `service_account:` principal corresponds to an [agent identity](/agent-platform/cloud-agents/agents/) on your team. * **`scoped_principal`** - The principal scoped to a team, like `principal:my-team-id/user:my-user-id`. * **`email`** - The principal's email, like `email:user@warp.dev`. * **`teams`** - The principal's team, like `teams:my-team-id`. diff --git a/src/content/docs/reference/cli/index.mdx b/src/content/docs/reference/cli/index.mdx index a2d6fd3..8602220 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -158,7 +158,7 @@ Use `oz whoami` to print information about the currently authenticated principal oz whoami ``` -The output includes your user or service account ID, display name, email, and team (when available). For machine-readable output, set `--output-format json` or `--output-format text`. +The output includes your user or service account ID, display name, email, and team (when available). When the CLI is authenticated as a service account principal, that principal is an [agent identity](/agent-platform/cloud-agents/agents/) on your team. For machine-readable output, set `--output-format json` or `--output-format text`. ```sh # JSON output for scripts diff --git a/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx b/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx index 8b032f0..193616e 100644 --- a/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/add-on-credits.mdx @@ -71,7 +71,7 @@ The limit resets automatically at the start of each calendar month, so you can m When your monthly credit balance renews: -1. Warp first consumes your included monthly plan credits (e.g., Build plan credits). +1. Warp first consumes your included monthly credits (e.g., Build plan credits). 2. After those are used, Warp continues to draw from any available Add-on Credits. 3. If your Add-on Credits run out and Auto reload is enabled, Warp will automatically purchase more up to your monthly limit. diff --git a/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx b/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx index 37db3d1..b3c9539 100644 --- a/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/bring-your-own-api-key.mdx @@ -15,6 +15,10 @@ BYOK provides greater flexibility in model access and ensures Warp **never consu BYOK is currently only available on Warp's paid plans, starting with Build. Learn more about plans and pricing [warp.dev/pricing](https://www.warp.dev/pricing). ::: +:::caution +BYOK and customer-supplied inference (BYOLLM via Amazon Bedrock or Google Vertex, plus custom endpoints) are available to individual users and organizations with 10 or fewer employees or users on any plan. Organizations with more than 10 employees or users must be on a Warp Business or Enterprise plan to use BYOK or customer-supplied inference. See Warp's [Terms of Service](https://www.warp.dev/terms-of-service) for details. +::: + ## How does BYOK work? When you add your own model API keys in Warp, those keys are stored **locally on your device** and are **never synced to the cloud**. @@ -113,6 +117,8 @@ Warp itself never stores your LLM API keys. ### BYOK on Enterprise and Business plans +Organizations with more than 10 employees or users must be on a Warp Business or Enterprise plan to use BYOK or customer-supplied inference. See Warp's [Terms of Service](https://www.warp.dev/terms-of-service) for the full eligibility rule. + Currently, BYOK is configured at the **user level**, not the team or admin level: * Each team member can add and manage their own API keys locally. 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 f039eed..17f7a56 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 @@ -10,7 +10,13 @@ description: >- Any interaction with Warp's Agent consumes credits. Credits are primarily based on AI usage — the number of credits a task consumes varies based on the size and complexity of your codebase, the size of the task, the model you're using, the amount of context the agent needs to gather, and more. -Credits also include a small hosting fee, charged only when running agents in the cloud, hosted on Warp's infrastructure. For details on cloud agent credits, see [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits). +Warp meters credits across three types of infrastructure — inference, compute, and platform — each with its own bucket. 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. +* **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; 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 (BYOK or BYOLLM via Amazon Bedrock or Google Vertex). See [platform credits](/support-and-community/plans-and-billing/platform-credits/). + +All three buckets draw from the same Warp credit pool and [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/), so you can manage them as a single balance in the Warp app under **Settings** > **Billing and usage**. Each interaction consumes **at least one credit**, though more complex interactions may use **multiple credits**. Because of factors such as codebase size, model choice, number of tool calls, and the nature of LLMs, credit usage is **non-deterministic** — two similar prompts can still use a different number of credits. @@ -36,7 +42,7 @@ You can view your total credit usage, along with other billing details, in **Set #### Credit **limits and billing** * **Seat-level allocation**: On team plans, credit limits apply per seat — each team member has their own allowance. Individual users (not on a team) also have their own credit allocation. -* **Cloud Agent Credits**: Individual users can run cloud agents via CLI/API using their normal Warp credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), or a Build plan with available credits. Integrations (Slack, Linear) require team membership. +* **Cloud agents and integrations**: Individual users can run cloud agents via the CLI and API, drawing from their Warp credits. Slack and Linear integrations require team membership. * **Hitting the credit limits**: Once you hit your monthly credit limit, your access will depend on your plan. On the Free plan, AI access stops until your next billing cycle. On paid plans, you can continue using AI with usage-based billing via [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/). #### **Other features that use credits** @@ -111,22 +117,46 @@ Because cache results depend on model provider behavior and timing, two similar These are the most common factors affecting credit usage, though there are others. Understanding them can help you manage your credits more efficiently and get the most from your plan. -### Cloud Agent Credits +### Compute credits + +Compute credits cover Warp-hosted compute consumed by an agent run. In practice, cloud agent runs consume them because they run on Warp's compute; local agent runs typically don't, since they run on your own machine. + +Compute credits are sometimes referred to as **cloud agent credits** when the conversation is framed around cloud agents vs local agents — they're the same bucket described from a different angle. + +#### Eligible for compute credits + +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 +* **Cloud Mode** - Running an agent from Cloud Mode in the Warp app + +#### Not eligible for compute credits + +The following scenarios don't use compute credits because they don't run on Warp-hosted compute: + +* **Local agent runs** - Using `oz agent run` on your local machine +* **Self-hosted compute** - Using `oz agent run` on GitHub Actions, CI/CD pipelines, or other self-hosted infrastructure + +### Platform credits + +Platform credits cover Warp's platform infrastructure — run lifecycle, scheduling, integrations, dashboard, APIs, and observability — for every cloud agent run, plus local agent runs on Business and Enterprise plans that use customer-supplied inference. -Cloud Agent Credits are a type of credit consumed only by cloud agent runs — AI requests that run on Warp-hosted compute. +#### Eligible for platform credits -#### Eligible for Cloud Agent Credits +Platform credits are used in the following scenarios: -The following scenarios use Cloud Agent Credits: +* **Cloud agents on any plan** use platform credits for every cloud agent run, regardless of which agent runs the task or which inference source it uses. +* **Local agents on Business or Enterprise with customer-supplied inference** use platform credits when the local agent run uses [Bring Your Own API Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) or BYOLLM via Amazon Bedrock or Google Vertex. -* **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 -* **Cloud Mode** — Running an agent from Cloud Mode in the Warp app +#### Not eligible for platform credits -#### Not eligible for Cloud Agent Credits +The following scenarios do **not** use platform credits: -The following scenarios do **not** use Cloud Agent 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. -* **Local agent runs** — Using `oz agent run` on your local machine -* **Self-hosted compute** — Using `oz agent run` on GitHub Actions, CI/CD pipelines, or other self-hosted infrastructure +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/plans-pricing-refunds.mdx b/src/content/docs/support-and-community/plans-and-billing/plans-pricing-refunds.mdx index 4423f9d..9530739 100644 --- a/src/content/docs/support-and-community/plans-and-billing/plans-pricing-refunds.mdx +++ b/src/content/docs/support-and-community/plans-and-billing/plans-pricing-refunds.mdx @@ -20,6 +20,7 @@ Visit [warp.dev/pricing](https://warp.dev/pricing) to see the latest plans and w * [Credits](/support-and-community/plans-and-billing/credits/) — learn how credits are used and calculated across AI features. * [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) — purchase additional credits or enable automatic reloads at discounted rates. +* [Platform credits](/support-and-community/plans-and-billing/platform-credits/) — learn how platform credits cover Warp's platform infrastructure for cloud agent runs and local runs with customer-supplied inference. * [Bring Your Own API Key](/support-and-community/plans-and-billing/bring-your-own-api-key/) — connect your own model provider API keys for custom usage and billing. * [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/) — information for users on legacy plans with overages enabled. * [Pricing FAQs](/support-and-community/plans-and-billing/pricing-faqs/) — answers to common questions about plans, billing, and usage. Don’t have Warp yet? [Download Warp](https://warp.dev/download) and get started for free today. 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 new file mode 100644 index 0000000..3509ceb --- /dev/null +++ b/src/content/docs/support-and-community/plans-and-billing/platform-credits.mdx @@ -0,0 +1,63 @@ +--- +title: Platform credits +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. +--- + +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, Amazon Bedrock, or Google Vertex. + +Warp meters credits across three types of infrastructure: **inference** (the model call), **compute** (the sandbox an agent runs in), and **platform** (everything that runs around the agent — run lifecycle, integrations, dashboard, APIs, and observability). Each type maps to one credit bucket: [AI credits](/support-and-community/plans-and-billing/credits/), [Compute credits](/support-and-community/plans-and-billing/credits/#compute-credits), and platform credits. Credit types and where an agent runs (local or cloud) are independent. + +Customer-supplied inference covers [Bring Your Own API Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) and BYOLLM via Amazon Bedrock or Google Vertex. + +:::caution +BYOK and customer-supplied inference (BYOLLM via Amazon Bedrock or Google Vertex, plus custom endpoints) are available to individual users and organizations with 10 or fewer employees or users on any plan. Organizations with more than 10 employees or users must be on a Warp Business or Enterprise plan to use BYOK or customer-supplied inference. See Warp's [Terms of Service](https://www.warp.dev/terms-of-service) for details. +::: + +## The three credit buckets + +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](/agent-platform/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). +* **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. + +## How platform credits are measured + +Platform credits accrue while an agent is actively working on a task — from when the task starts running to when it finishes, fails, or is cancelled. Idle time, time spent waiting on user input, and time before the task starts don't accrue platform credits. + +See [warp.dev/pricing](https://warp.dev/pricing) for current rates. + +## When platform credits apply + +Whether platform credits apply depends on where the agent runs and who's paying for inference. + +### 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. +* **Local agents on Business or Enterprise with customer-supplied inference** use platform credits when the local agent run uses [BYOK](/support-and-community/plans-and-billing/bring-your-own-api-key/) or BYOLLM via Amazon Bedrock or Google Vertex. 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 + +* **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. + +## Where platform credits appear + +Platform credits appear in the same billing views as your other credit usage. + +* **Per-user credit totals** - In the Warp app, **Settings** > **Billing and usage** includes platform credits alongside AI credits and compute credits. +* **Admin usage breakdown** - For team admins, the Admin Panel billing view shows a per-bucket breakdown for each member and for the team as a whole. Platform credits appear as their own segment in the stacked usage bar, distinct from the AI credits and compute credits segments. +* **Add-on Credits and limits** - Platform credits draw from the same pools as your other usage — your monthly Warp credits first, then [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) once those are exhausted. + +## Related pages + +* [Credits](/support-and-community/plans-and-billing/credits/) - How AI credits are measured and calculated. +* [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) - Purchase additional credits or enable auto reload. +* [Bring Your Own API Key](/support-and-community/plans-and-billing/bring-your-own-api-key/) - Connect your own model provider keys. +* [Plans, pricing, and refunds](/support-and-community/plans-and-billing/plans-pricing-refunds/) - Compare plans and refund policies. 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 75040a3..df8c381 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 @@ -305,7 +305,7 @@ Add-on credits replace overages with a simpler, prepaid system. They’re up to #### Do credits rollover? -For existing users on legacy plans, plan credits on Pro, Turbo, and Lightspeed do not rollover. +For existing users on legacy plans, Warp credits on Pro, Turbo, and Lightspeed do not rollover. For the Build plan, credits will not rollover but Add-on credits will rollover and be valid for 12 months from the date of purchase. @@ -347,6 +347,6 @@ If you’re part of a larger team (up to 50 members) that needs advanced adminis For teams on the Build or Business plans, credits are managed at two levels: * **Included monthly credits**: Each seat on a paid plan receives 1,500 individual credits per month. These credits are tied to the user and reset every 30 days based on their subscription or renewal date. -* **Add-on Credits**: Once individual plan credits are used up, team members draw from a shared Add-on Credit balance that can be topped up and managed by team admins. +* **Add-on Credits**: Once individual credits are used up, team members draw from a shared Add-on Credit balance that can be topped up and managed by team admins. This shared model gives teams the flexibility to handle variable AI usage – heavy users can consume more when needed, while the entire team benefits from shared value and volume-based discounts. diff --git a/src/sidebar.ts b/src/sidebar.ts index c2e510a..cabd740 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -351,10 +351,31 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ }, 'agent-platform/cloud-agents/environments', { slug: 'agent-platform/cloud-agents/managing-cloud-agents', label: 'Managing cloud agents' }, + { slug: 'agent-platform/cloud-agents/agents', label: 'Agent identities' }, { slug: 'agent-platform/cloud-agents/oz-web-app', label: 'Oz web app' }, { slug: 'agent-platform/cloud-agents/skills-as-agents', label: 'Skills as agents' }, { slug: 'agent-platform/cloud-agents/viewing-cloud-agent-runs', label: 'Viewing cloud agent runs' }, + { + label: 'Handoff', + collapsed: true, + items: [ + { slug: 'agent-platform/cloud-agents/handoff', label: 'Overview' }, + { slug: 'agent-platform/cloud-agents/handoff/local-to-cloud', label: 'Local to cloud' }, + { slug: 'agent-platform/cloud-agents/handoff/cloud-to-cloud', label: 'Cloud to cloud' }, + ], + }, 'agent-platform/cloud-agents/secrets', + { + label: 'Harnesses', + collapsed: true, + items: [ + { slug: 'agent-platform/cloud-agents/harnesses', label: 'Overview' }, + { slug: 'agent-platform/cloud-agents/harnesses/warp-agent', label: 'Warp Agent' }, + { slug: 'agent-platform/cloud-agents/harnesses/claude-code', label: 'Claude Code' }, + { slug: 'agent-platform/cloud-agents/harnesses/codex', label: 'Codex' }, + { slug: 'agent-platform/cloud-agents/harnesses/authentication', label: 'Authentication' }, + ], + }, { slug: 'agent-platform/cloud-agents/mcp', label: 'MCP servers' }, { slug: 'agent-platform/cloud-agents/deployment-patterns', label: 'Deployment patterns' }, { slug: 'agent-platform/cloud-agents/warp-hosting', label: 'Warp-hosted agents' }, @@ -378,6 +399,12 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'agent-platform/cloud-agents/faqs', label: 'Cloud agent FAQs' }, ], }, + { + label: 'Memory (Research Preview)', + items: [ + { slug: 'agent-platform/agent-memory', label: 'Agent Memory' }, + ], + }, ], }, { @@ -502,6 +529,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ { slug: 'support-and-community/plans-and-billing/plans-pricing-refunds', label: 'Plans, Pricing, & Refunds' }, 'support-and-community/plans-and-billing/credits', 'support-and-community/plans-and-billing/add-on-credits', + { slug: 'support-and-community/plans-and-billing/platform-credits', label: 'Platform credits' }, 'support-and-community/plans-and-billing/bring-your-own-api-key', 'support-and-community/plans-and-billing/overages-legacy', 'support-and-community/plans-and-billing/pricing-faqs', diff --git a/vercel.json b/vercel.json index a2df40b..830d8d8 100644 --- a/vercel.json +++ b/vercel.json @@ -9572,6 +9572,11 @@ "source": "/oz", "destination": "/agent-platform/cloud-agents/overview/", "statusCode": 308 + }, + { + "source": "/agent-platform/capabilities/agent-memory", + "destination": "/agent-platform/agent-memory/", + "statusCode": 308 } ] }