Agents > Oz Cloud Agents & Orchestration

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 and integration 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 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.

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

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.

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 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:

In the Oz web app (oz.warp.dev), open the Secrets page.
Click Add secret to open the Add secret side pane.
Enter a Name (for example, OPENAI_API_KEY). This becomes the environment variable name injected into runs.
Enter the Value. The value is encrypted in your browser before it is sent to the server; Warp never sees the plaintext.
Optionally, enter a Description to help teammates identify the secret later.
Choose a Scope — Team to share the secret with everyone on the team, or Personal to keep it scoped to your user.
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

Listing secrets

You can list all secrets you have access to.

oz secret list

Example output:

NAME                         SCOPE      LAST UPDATED
METABASE_API_KEY             team       1 week ago
GCP_SERVICE_ACCOUNT_JSON     team       yesterday
MY_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
Fully automated integrations

The agent receives:

Team-level secrets only

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, 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 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 to attach secrets to an environment:

In the Oz web app (oz.warp.dev), open the Environments page.
Click an existing environment to edit it, or click New environment to create one.
In the environment form, open the Secrets section.
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.
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.
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.
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 for the exact field and shape.

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