> For the complete documentation index, see [llms.txt](/llms.txt). > Markdown versions of each page are available by appending .md to any URL. # Cloud agent secrets Securely store, scope, and inject credentials for Warp cloud agents across CLI, Slack, Linear, and scheduled runs—without ever exposing secret values. Cloud agents often need to interact with external systems such as APIs, databases, cloud providers, or internal tooling. To do this safely, Warp provides Warp-managed **agent secrets**, a secure way to store, scope, and inject credentials into cloud agent runs without exposing secret values to users or logs. Warp-managed secrets are designed to work across [cloud agent](/agent-platform/cloud-agents/overview/) and [integration](/agent-platform/cloud-agents/integrations/) triggers (CLI, Slack, Linear, and schedules), support both team-wide and personal credentials, and give engineering and security teams visibility into what agents can access. **Warp-managed secrets are useful when:** - 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 ### Common use cases - Run SQL queries against BigQuery or Metabase to answer questions like “what changed in last night’s pipeline run” or “how many users hit this error today,” using a read-only service account or API token. - Call cloud or infrastructure CLIs to take small, predefined remediation steps when an alert fires, such as restarting a service, scaling a deployment, or clearing a stuck job, using tightly scoped credentials. - List and review all API keys, service accounts, and tokens that cloud agents can access to verify scopes, rotation policies, and ownership match internal security requirements. * * * ### How Warp-managed secrets work 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. 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.** Key properties of secrets: - **Scoped** to either a team or an individual user - Secret values are **never readable after creation** (only metadata is visible) - **Automatically set** for cloud agent runs when in scope ### Secret scopes Each secret has a scope that determines who can use it. #### Team secrets Team secrets are shared across the entire team and are available to all cloud agents running on behalf of the team. **Key characteristics:** - Always injected into cloud agent runs, regardless of how the agent is triggered (CLI, Slack, Linear, or scheduled runs) - Available to agents running with or without a specific user context - 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 [cloud agent](/agent-platform/cloud-agents/agents/) instead of giving every run access to it. **For example:** - Use a Metabase service account or read-only API token, not a personal Metabase API key - Use cloud provider service accounts with minimal required permissions - Use integration-specific tokens created for automation 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 [cloud agent](/agent-platform/cloud-agents/agents/), so only runs executing as that cloud agent receive them. The secret itself still lives in the team’s secret scope; the cloud agent only references it by name. #### Personal secrets Personal secrets belong to an **individual user**. - Only available to cloud agents triggered by that user - Not accessible to teammates or user-less triggers - Useful for personal API keys or credentials tied to an individual account * * * ## 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. You can create secrets interactively or from a file. **Create a team secret interactively** ``` oz secret create --team METABASE_API_KEY ``` You will be prompted to enter the value securely in the terminal. **Create a personal secret from a file** ``` oz secret create --personal --value-file api_key.txt METABASE_API_KEY ``` This is useful for long values such as JSON blobs or private keys. #### Adding descriptions Descriptions help with auditing and rotation tracking. ``` oz secret create --team \ --description "Rotate every 2 weeks; owned by platform team" \ MY_SECRET ``` Descriptions are visible in listings but never expose the secret value. #### Updating a secret Updating a secret replaces its value and/or description while keeping the same name and scope. **Update a secret value interactively** ``` oz secret update --team --value METABASE_API_KEY ``` You will be prompted to enter the new value securely in the terminal. **Update a secret value from a file** ``` oz secret update --team \ --value-file new_api_key.txt \ METABASE_API_KEY ``` This is the recommended way to rotate credentials. **Update a secret’s description (`-d`)** ``` oz secret update --team \ --description "Rotated 2026-02-26; owned by platform team" \ METABASE_API_KEY ``` #### Deleting a secret To permanently remove a secret, use `oz secret delete`: ``` oz secret delete --team METABASE_API_KEY ``` You will be prompted for confirmation before the secret is deleted. Add `--force` to skip the confirmation prompt. Replace `--team` with `--personal` to delete a personal secret. ``` oz secret delete --team --force METABASE_API_KEY ``` Caution Deleting a secret is permanent. Any cloud agent runs that depend on the deleted secret will no longer receive it as an environment variable. #### Listing secrets You can list all secrets you have access to. ``` oz secret list ``` Example output: ``` NAME SCOPE LAST UPDATEDMETABASE_API_KEY team 1 week agoGCP_SERVICE_ACCOUNT_JSON team yesterdayMY_MCP_SERVER_TOKEN personal 10:00am ``` **Secret values are never displayed.** ### How secrets are made available to cloud agents 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: ``` METABASE_API_KEY=******** ``` * * * ### Secret availability by trigger type Which secrets an agent receives depends on how the agent was triggered. #### User-initiated triggers When an agent is triggered by a specific user, such as: - Oz CLI - Slack mentions - Linear updates **The agent receives:** - All team-level secrets - The triggering user’s personal secrets It **does not receive personal secrets** belonging to other team members. When an agent is triggered without a user context, such as: - [Scheduled (cron) agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) - Fully automated [integrations](/agent-platform/cloud-agents/integrations/) The agent receives: - Team-level secrets only Caution 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 [cloud agents](/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: - Secret values cannot be read or exported after creation - All secrets are explicitly scoped to a team or user - Engineering and security leads can list all secrets available to them - Rotation is handled by updating secrets in place - Cloud agents only receive secrets that are in scope for the trigger **Teams remain responsible for:** - Choosing appropriate scopes for each secret - Limiting permissions on external systems (for example, read-only API keys) - Rotating credentials according to internal policies - Managing which agents and triggers exist within their environment