Secrets

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:

• An 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.

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.

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

---

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

Caution

Personal secrets are never injected in these cases.

---

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