From 84661af15329d7a49880d3fa34b27cd38d662e58 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 14:35:07 -0700 Subject: [PATCH 1/4] docs(agent-platform): add named agents page and cross-link from related pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a new dedicated page for named agents (agent identities) under cloud agents, and reconciles a handful of existing pages so that automation guidance and service-account references point to the new page. - New: src/content/docs/agent-platform/cloud-agents/agents.mdx — what a named agent is, plan limits, attaching descriptions/secrets/skills, REST endpoints, API keys bound to a named agent, running as a specific identity, and where named agents surface in the product. - Edit: agent-platform/cloud-agents/secrets.mdx — forward-links from the team-secrets recommendation and adds a brief note that secrets can be attached directly to a named agent. - Edit: agent-platform/cloud-agents/deployment-patterns.mdx — Pattern 1 checklist now references a named agent (recommended for automation) instead of an unscoped "service account". - Edit: agent-platform/cloud-agents/oz-web-app.mdx — reconciles the two meanings of the Agents page (skills browser + named-agent management) with a clear section split and a forward link. - Edit: reference/cli/index.mdx — keeps the literal `oz whoami` output intact and adds a one-line note pointing readers to the new agents page for what a service-account principal represents. - Edit: reference/cli/federate.mdx — keeps the literal `service_account:my-sa-id` example and adds a cross-reference to the new agents page. Hard rules: no edits to sidebar.ts, vercel.json, landing pages, or any pages owned by the five orchestration-launch PRs. Co-Authored-By: Oz --- .../agent-platform/cloud-agents/agents.mdx | 96 +++++++++++++++++++ .../cloud-agents/deployment-patterns.mdx | 2 +- .../cloud-agents/oz-web-app.mdx | 24 ++++- .../agent-platform/cloud-agents/secrets.mdx | 6 +- src/content/docs/reference/cli/federate.mdx | 2 +- src/content/docs/reference/cli/index.mdx | 2 +- 6 files changed, 124 insertions(+), 8 deletions(-) create mode 100644 src/content/docs/agent-platform/cloud-agents/agents.mdx 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 00000000..1498004f --- /dev/null +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -0,0 +1,96 @@ +--- +title: Named agents +description: >- + Named agents are team-scoped identities that own and execute cloud agent + runs. Use them to separate workflows, scope credentials, and attribute + automated work to a specific bot account. +sidebar: + label: "Named agents" +--- + +A **named agent** is a team-scoped identity that can own and execute Oz cloud agent runs. Every Warp team starts with a single default agent. Creating additional named agents lets you separate workflows, scope credentials, and attribute automated runs to a specific bot account instead of a person. + +Named agents 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 a named agent so CI pipelines and webhooks show up as that bot in run history rather than as a teammate. + +## How named agents work + +Each team has one default agent that runs receive automatically when no specific identity is chosen. You can create additional named agents on top of that 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 named agents. + +You can attach the following configuration to a named agent: + +* **Description** - A short, human-readable summary teammates see when picking the agent. +* **Managed secrets** - References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the agent should have access to. +* **Skills** - Skill specs (for example, `org/repo:path/to/SKILL.md`) the agent 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. + +## Plan limits + +Each plan caps the number of named agents (including the default) a team can have: + +* **Free** - 1 named agent. +* **Build** - 1 named agent. +* **Business** - 5 named agents. +* **Enterprise** - Unlimited. + +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 named agents + +You can create, list, update, and delete named agents 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`, `getAgent`, `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 agent's `uid`, `name`, and `available` flag. +* **List** - `GET /agent/identities` returns every named agent on the team, including the default. Each entry includes an `available` flag indicating whether it is within the plan limit. +* **Retrieve** - `GET /agent/identities/{uid}` returns a single agent by its UID. +* **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 agent and atomically deletes every API key bound to it. The default agent cannot be deleted. + +### Caller requirements + +A few constraints apply across every endpoint: + +* **Team-scoped** - Named agents 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 a named agent. A request authenticated as a named agent itself is rejected. +* **Availability is enforced on use** - Over-plan-limit agents are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs. + +## API keys bound to a named agent + +A team API key can be bound to a specific named agent at creation time. Calls authenticated with that key run as the chosen agent. The team is resolved automatically from the agent — you don't need to specify a team when generating the key. + +To create a key bound to a named agent, pass the agent's UID to the `generateApiKey` mutation. 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 named agent for every call. There is no extra flag to set; the binding is on the key itself. + +## Running as a named agent + +There are two ways to run a cloud agent as a specific named agent: + +* **Authenticate with a key bound to the agent** - Every run started with that key executes as the bound named agent. 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 named agent's `uid` in the request body. The field is only valid for team-owned runs. + +When neither path is used, runs execute under the default identity ("Quick run" in the web app). + +## Where named agents appear in the product + +Named agents 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 named agents. 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 a named agent runs as that identity instead. +* **Run filters and detail** - The Runs view lets you filter by named agent, 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 named-agent 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 a named agent. +* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - When to use a named agent for automation versus a personal identity. +* [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the named agent endpoints. +* [API Keys](/reference/cli/api-keys/) - Create keys bound to a specific named agent. +* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run, including ones executing as a named agent. +* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - The web surface where you manage named agents 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 d3ae1bff..b9e4bd60 100644 --- a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx +++ b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx @@ -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) +* A [named agent](/agent-platform/cloud-agents/agents/) (recommended for automation) * The Oz CLI installed on the runner / box * Any needed credentials (often via secrets + environment variables) 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 c572f6bc..1babf088 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 @@ -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). +* **Named agents** - Team-scoped identities that own and execute runs. The same page is where teams create and manage named agents, attach descriptions and secrets to them, and bind API keys to a specific identity. + +For the full reference on named agents — including plan limits, the REST endpoints, and how to run as a specific identity — see [Named agents](/agent-platform/cloud-agents/agents/). ### Skill details @@ -142,15 +147,25 @@ 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 skill in the Oz web app.
+### Named agents + +Named agents are managed from the same Agents page. From the named-agents view, you can: + +* **Create a named agent** - Give it a name, an optional description, a default model and harness, and the secrets and skills runs as that agent should receive. +* **Edit an existing agent** - Update its description, attached secrets, attached skills, or default configuration. +* **Delete an agent** - Soft-deletes the agent and atomically deletes every API key bound to it. The default agent cannot be deleted. + +When you start a new run or schedule from the web app, the form's **Agent** dropdown lets you pick which named agent should execute the run. **Quick run** is the default option and runs as your own user. See [Named agents](/agent-platform/cloud-agents/agents/) for the full reference. + --- ## Schedules @@ -259,6 +274,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 +* [Named agents](/agent-platform/cloud-agents/agents/) — Team-scoped identities 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/secrets.mdx b/src/content/docs/agent-platform/cloud-agents/secrets.mdx index e2caff37..ed9a4427 100644 --- a/src/content/docs/agent-platform/cloud-agents/secrets.mdx +++ b/src/content/docs/agent-platform/cloud-agents/secrets.mdx @@ -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 a [named agent](/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 a [named agent](/agent-platform/cloud-agents/agents/), so only runs executing as that agent receive them. The secret itself still lives in the team's secret scope; the named agent just references it by name. +::: + #### Personal secrets Personal secrets belong to an **individual user**. diff --git a/src/content/docs/reference/cli/federate.mdx b/src/content/docs/reference/cli/federate.mdx index 4f1e0fad..40ebec44 100644 --- a/src/content/docs/reference/cli/federate.mdx +++ b/src/content/docs/reference/cli/federate.mdx @@ -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 a [named agent](/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 f37ef770..7ba46c8a 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -156,7 +156,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 a [named agent](/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 From 2b7552acde4da162e65a585ed981afdefcd9f7e3 Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 15:03:29 -0700 Subject: [PATCH 2/4] docs(agent-platform): rename to agent identities; expand secrets and web-UI coverage Revises the previous "named agents" page and related cross-links to use "agent identity" consistently, and folds in three product surfaces that land alongside agent identities at launch. - agents.mdx: retitled to "Agent identities" and reframed throughout to use the canonical term. Plan-limit table replaced with a single sentence pointing readers to warp.dev/pricing while preserving the default-identity / over-limit visibility behavior. Adds two new subsections: a service-account-to-agent-identity mapping (covers service_account: in oz whoami and oz federate) and a rationale paragraph for supporting multiple identities (CI, on-call, scheduled jobs). - secrets.mdx: new "Creating secrets in the Oz web app" walkthrough alongside the existing oz secret CLI section. New "Scoping secrets to environments and runs" section covering environment-level scoping and run-level scoping (default-inherit / explicit list / empty-list opt-out), with cross-links to environments and the Oz API reference. Terminology references updated. - oz-web-app.mdx: adds Secrets to the quick-reference table, reframes the Agents-page disambiguation to use "agent identity," and adds a step-by-step walkthrough of the New agent side pane (name, description, prompt, skills, harness, model, harness auth secret, secrets, memory stores). Cross-links to agents.mdx for the conceptual reference. - deployment-patterns.mdx: Pattern 1 checklist now references "an agent identity." - reference/cli/index.mdx and reference/cli/federate.mdx: leave literal CLI output intact; one-line notes tying service_account principals to agent identities, with cross-links to agents.mdx. Co-Authored-By: Oz --- .../agent-platform/cloud-agents/agents.mdx | 106 ++++++++++-------- .../cloud-agents/deployment-patterns.mdx | 2 +- .../cloud-agents/oz-web-app.mdx | 38 +++++-- .../agent-platform/cloud-agents/secrets.mdx | 48 +++++++- src/content/docs/reference/cli/federate.mdx | 2 +- src/content/docs/reference/cli/index.mdx | 2 +- 6 files changed, 134 insertions(+), 64 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/agents.mdx b/src/content/docs/agent-platform/cloud-agents/agents.mdx index 1498004f..5fd5535c 100644 --- a/src/content/docs/agent-platform/cloud-agents/agents.mdx +++ b/src/content/docs/agent-platform/cloud-agents/agents.mdx @@ -1,96 +1,104 @@ --- -title: Named agents +title: Agent identities description: >- - Named agents are team-scoped identities that own and execute cloud agent - runs. Use them to separate workflows, scope credentials, and attribute - automated work to a specific bot account. + 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: "Named agents" + label: "Agent identities" --- -A **named agent** is a team-scoped identity that can own and execute Oz cloud agent runs. Every Warp team starts with a single default agent. Creating additional named agents lets you separate workflows, scope credentials, and attribute automated runs to a specific bot account instead of a person. +An **agent identity** is a team-scoped identity that can own and execute Oz 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. -Named agents are useful when you want to: +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 a named agent so CI pipelines and webhooks show up as that bot in run history rather than as a teammate. +* **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 named agents work +## How agent identities work -Each team has one default agent that runs receive automatically when no specific identity is chosen. You can create additional named agents on top of that 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 named agents. +Each team has one default agent identity that runs receive automatically when no specific identity is chosen. You can create additional agent identities on top of that 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 a named agent: +You can attach the following configuration to an agent identity: -* **Description** - A short, human-readable summary teammates see when picking the agent. -* **Managed secrets** - References (by name) to [team-managed secrets](/agent-platform/cloud-agents/secrets/) the agent should have access to. -* **Skills** - Skill specs (for example, `org/repo:path/to/SKILL.md`) the agent comes preloaded with. Shorthand specs like `repo:skill_name` are accepted when they resolve unambiguously against the team's cloud environments. +* **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. -## Plan limits +## 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. -Each plan caps the number of named agents (including the default) a team can have: +## 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 -* **Free** - 1 named agent. -* **Build** - 1 named agent. -* **Business** - 5 named agents. -* **Enterprise** - Unlimited. +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 named agents +## Managing agent identities -You can create, list, update, and delete named agents 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`, `getAgent`, `updateAgent`, and `deleteAgent` under the **agent** tag. +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`, `getAgent`, `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 agent's `uid`, `name`, and `available` flag. -* **List** - `GET /agent/identities` returns every named agent on the team, including the default. Each entry includes an `available` flag indicating whether it is within the plan limit. -* **Retrieve** - `GET /agent/identities/{uid}` returns a single agent by its UID. +* **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. +* **Retrieve** - `GET /agent/identities/{uid}` returns a single identity by its UID. * **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 agent and atomically deletes every API key bound to it. The default agent cannot be deleted. +* **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** - Named agents 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 a named agent. A request authenticated as a named agent itself is rejected. -* **Availability is enforced on use** - Over-plan-limit agents are returned by the list endpoint but cannot be used to update fields, generate new keys, or start new runs. +* **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 a named agent +## API keys bound to an agent identity -A team API key can be bound to a specific named agent at creation time. Calls authenticated with that key run as the chosen agent. The team is resolved automatically from the agent — you don't need to specify a team when generating the key. +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 a named agent, pass the agent's UID to the `generateApiKey` mutation. See [API Keys](/reference/cli/api-keys/) for the full key creation flow and for the difference between user-scoped and team-scoped keys. +To create a key bound to an agent identity, pass the identity's UID to the `generateApiKey` mutation. 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 named agent for every call. There is no extra flag to set; the binding is on the key itself. +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 a named agent +## Running as an agent identity -There are two ways to run a cloud agent as a specific named agent: +There are two ways to run a cloud agent as a specific agent identity: -* **Authenticate with a key bound to the agent** - Every run started with that key executes as the bound named agent. 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 named agent's `uid` in the request body. The field is only valid for team-owned runs. +* **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, runs execute under the default identity ("Quick run" in the web app). -## Where named agents appear in the product +## Where agent identities appear in the product -Named agents surface across several Oz surfaces: +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 named agents. 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 a named agent runs as that identity instead. -* **Run filters and detail** - The Runs view lets you filter by named agent, 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 named-agent runs to the team rather than to a person. +* **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 a named agent. -* [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) - When to use a named agent for automation versus a personal identity. -* [Oz API & SDK](/reference/api-and-sdk/) - Programmatic access to the named agent endpoints. -* [API Keys](/reference/cli/api-keys/) - Create keys bound to a specific named agent. -* [Federated identity tokens](/reference/cli/federate/) - Issue OIDC tokens from inside a run, including ones executing as a named agent. -* [Oz web app](/agent-platform/cloud-agents/oz-web-app/) - The web surface where you manage named agents and inspect their runs. +* [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 b9e4bd60..7d933f74 100644 --- a/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx +++ b/src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx @@ -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 [named agent](/agent-platform/cloud-agents/agents/) (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) 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 1babf088..e78c8369 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 @@ -19,7 +19,7 @@ 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) @@ -122,9 +122,9 @@ The skill provides base instructions; your prompt adds context for this particul 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). -* **Named agents** - Team-scoped identities that own and execute runs. The same page is where teams create and manage named agents, attach descriptions and secrets to them, and bind API keys to a specific identity. +* **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 named agents — including plan limits, the REST endpoints, and how to run as a specific identity — see [Named agents](/agent-platform/cloud-agents/agents/). +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 @@ -156,15 +156,33 @@ Click **New skill** to create a new skill. The guided flow helps you define the
Creating a new skill in the Oz web app.
-### Named agents +### Agent identities -Named agents are managed from the same Agents page. From the named-agents view, you can: +Agent identities are managed from the same Agents page. From the agent-identities view, you can: -* **Create a named agent** - Give it a name, an optional description, a default model and harness, and the secrets and skills runs as that agent should receive. -* **Edit an existing agent** - Update its description, attached secrets, attached skills, or default configuration. -* **Delete an agent** - Soft-deletes the agent and atomically deletes every API key bound to it. The default agent cannot be deleted. +* **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 named agent should execute the run. **Quick run** is the default option and runs as your own user. See [Named agents](/agent-platform/cloud-agents/agents/) for the full reference. +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 this identity uses by default (for example, the Oz harness 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** — When memory stores are available to your team, attach the ones 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/). --- @@ -274,7 +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 -* [Named agents](/agent-platform/cloud-agents/agents/) — Team-scoped identities that own and execute runs +* [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/secrets.mdx b/src/content/docs/agent-platform/cloud-agents/secrets.mdx index ed9a4427..96b8b715 100644 --- a/src/content/docs/agent-platform/cloud-agents/secrets.mdx +++ b/src/content/docs/agent-platform/cloud-agents/secrets.mdx @@ -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. When you want a credential to be available to one workflow only, attach it to a [named agent](/agent-platform/cloud-agents/agents/) instead of giving every run access to it. +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:** @@ -69,7 +69,7 @@ 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 a [named agent](/agent-platform/cloud-agents/agents/), so only runs executing as that agent receive them. The secret itself still lives in the team's secret scope; the named agent just references it by name. +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 just references it by name. ::: #### Personal secrets @@ -82,6 +82,24 @@ 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. @@ -229,6 +247,32 @@ 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, only those secrets are injected from the environment's contribution, regardless of every other team secret the caller has access to. 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 from the environment form in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) or when creating an environment with the CLI. See [Environments](/agent-platform/cloud-agents/environments/) for the full configuration reference. + +### 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/reference/cli/federate.mdx b/src/content/docs/reference/cli/federate.mdx index 40ebec44..fe638baa 100644 --- a/src/content/docs/reference/cli/federate.mdx +++ b/src/content/docs/reference/cli/federate.mdx @@ -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`. A `service_account:` principal corresponds to a [named agent](/agent-platform/cloud-agents/agents/) on your team. +* **`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 7ba46c8a..816674cf 100644 --- a/src/content/docs/reference/cli/index.mdx +++ b/src/content/docs/reference/cli/index.mdx @@ -156,7 +156,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). When the CLI is authenticated as a service account principal, that principal is a [named agent](/agent-platform/cloud-agents/agents/) on your team. 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 From 89854028812ccefa8647c681ad8d7749ba1121ed Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 16:09:34 -0700 Subject: [PATCH 3/4] =?UTF-8?q?docs(secrets):=20fix=20two=20'an=20cloud'?= =?UTF-8?q?=20=E2=86=92=20'a=20cloud'=20grammar=20typos?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pre-existing grammar slips picked up during the agent-identities PR audit. 'Cloud' starts with a consonant sound, so the article 'a' is correct. Co-Authored-By: Oz --- src/content/docs/agent-platform/cloud-agents/secrets.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/agent-platform/cloud-agents/secrets.mdx b/src/content/docs/agent-platform/cloud-agents/secrets.mdx index 96b8b715..7def86a1 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 @@ -203,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: From 14bf9b6a2dac8992439cbfdbc879b7e3cc62a3df Mon Sep 17 00:00:00 2001 From: Hong Yi Chen Date: Sat, 16 May 2026 16:31:51 -0700 Subject: [PATCH 4/4] docs(agent-identities): address audit findings - secrets.mdx: rephrase environment-level scoping as a default contribution to the run's allowlist (not a cap); drop the CLI environment-secret attachment claim; make the env-secret section self-contained with a web-UI walkthrough and attachment semantics - oz-web-app.mdx: fix the "Oz harness" noun-phrase slip in the base-harness bullet; drop the availability hedge on the memory-stores bullet while keeping the bullet Co-Authored-By: Oz --- .../cloud-agents/oz-web-app.mdx | 4 ++-- .../agent-platform/cloud-agents/secrets.mdx | 20 +++++++++++++++++-- 2 files changed, 20 insertions(+), 4 deletions(-) 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 e78c8369..99925717 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 @@ -174,11 +174,11 @@ Click **New agent** to open the **New agent** side pane. The pane is split into 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 this identity uses by default (for example, the Oz harness or a supported third-party CLI agent). +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** — When memory stores are available to your team, attach the ones this identity should read from or write to. +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**. diff --git a/src/content/docs/agent-platform/cloud-agents/secrets.mdx b/src/content/docs/agent-platform/cloud-agents/secrets.mdx index 7def86a1..e9180f30 100644 --- a/src/content/docs/agent-platform/cloud-agents/secrets.mdx +++ b/src/content/docs/agent-platform/cloud-agents/secrets.mdx @@ -253,9 +253,25 @@ Owner scoping (team versus personal) controls **which secrets exist** for a call ### Environment-level scoping -A [cloud environment](/agent-platform/cloud-agents/environments/) can declare its own list of secrets. When a run uses that environment, only those secrets are injected from the environment's contribution, regardless of every other team secret the caller has access to. 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`. +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 from the environment form in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) or when creating an environment with the CLI. See [Environments](/agent-platform/cloud-agents/environments/) for the full configuration reference. +#### 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