Managing secrets for factory agents

Secrets give factory agents credentials for external services without putting values in prompts or definition files. For example, give a reporting agent a read-only METABASE_API_KEY so it can query your team’s dashboards.

Create secrets in the Warp Factories web app, then grant access to the agents that need them. The Secrets page is team-wide, not specific to the factory you have selected.

Secret ownership and agent access

Factory secrets belong to your team. Creating a secret doesn’t give every factory agent access: execution secrets must be attached to an agent or included through its factory configuration. Raw values are injected as environment variables using the secret name.

Use service-account credentials with the minimum external permissions the task needs. Personal secrets from the legacy workflows aren’t listed in the factory secret picker. For those workflows, see legacy cloud agent secrets.

Execution secrets are separate from other credentials:

• Harness authentication - Connect Claude Code or Codex through the agent’s authentication settings, not its execution-secret list. See configuring a third-party harness.
• Inference credentials - Configure team-managed provider keys separately. See credential boundaries.
• Private image credentials - Select these on a runner to pull its container image. They aren’t injected into the agent environment.

Creating a secret

Have the external service’s credential ready. To grant it to agents, you also need permission to edit their configuration and attach secrets.

1. In the Warp Factories web app, open Secrets in the sidebar.
2. Click New, then Create secret. On an empty list, you can also click New secret.
3. Enter a name such as METABASE_API_KEY. In the “Type” dropdown, choose Raw value, then enter the credential in “Value”.
4. Optionally, add a description identifying the credential’s purpose, owner, and rotation policy.
5. To grant the secret to the current agents in a Warp-managed factory, choose that factory under “Available to agents”. Leave this empty to configure individual agents separately.
6. Click Save.

The secret appears in the team list. Its stored value stays hidden; editing replaces the value rather than revealing it. Open the secret’s Agents tab to see which agents use it.

Factory selection during creation updates the selected factories’ current agents. It isn’t a default for future agents. For inherited access, use definition files.

Granting a secret to one agent

For a Warp-managed factory, attach only the secrets that agent needs:

1. In the factory dashboard, select your factory, click Agents, and open the agent.
2. In the agent’s Settings tab, find “Secrets” and click Add secret.
3. Select the existing team secret and save the agent’s changes with Save.

The agent’s settings now list the secret. For a factory managed in an external repository, edit its definition files instead; the dashboard configuration is read-only.

To check access without revealing a value, ask the agent to confirm that the named environment variable is set without printing it. Don’t ask it to print the environment.

Configuring access in definition files

Create the secret first, then reference its name in your existing factory definition. Never commit its value.

To grant METABASE_API_KEY only to a reporting agent, add a secrets list to that agent’s frontmatter:

agents/reporting/agent.md

---
description: Answers questions about dashboard metrics
secrets:
  - METABASE_API_KEY
---

Use the read-only Metabase credential to query dashboard metrics.
Never print credentials or include them in outputs.

Secret lists have three levels:

• Factory-wide secrets - Adds the named secrets to every agent.
• agentDefaults.secrets - Supplies the list for agents without their own override.
• Per-agent secrets - Replaces the default list. An empty list removes inherited defaults, but not factory-wide secrets.

Harness authentication and credentials required by attached MCP servers are configured separately; an empty execution-secret list doesn’t disable those credentials. See the definition reference for the exact fields.

Rotating a secret

Keep the same name so existing agent references continue to work.

1. In the Warp Factories web app, open Secrets and click the secret.
2. Open the actions menu and click Edit.
3. In “Value”, enter the replacement credential, then click Save.

New runs resolve the updated value. Revoke the old credential in the external service after confirming the replacement works. To script updates with the legacy CLI, see updating a secret.

Removing access or deleting a secret

To stop one agent using a secret, remove the reference from that agent’s configuration. Check factory-wide and inherited lists too; removing a per-agent entry doesn’t remove a factory-wide grant.

To delete the secret itself, open it from Secrets, choose Delete from the actions menu, and confirm. Deletion affects every agent, webhook, or runner that references that secret.

Caution

Deleting a secret is permanent. Remove or replace dependent references before deleting it, and revoke the credential in the external service if it must no longer be usable.

AWS ECR credentials

Use an AWS ECR credential when a Warp-hosted Linux runner pulls an image from Amazon Elastic Container Registry. Warp stores the role ARN, not a password, and requests a short-lived pull token for each run. Create this credential in the web app, not the legacy CLI.

1. In the Warp Factories web app, open Secrets and click New > Create secret.
2. In the “Type” dropdown, choose AWS ECR credential and enter a name.
3. In the registry’s AWS account, create an IAM role with the trust and permissions policies shown in the form. If you restrict repository read actions to a repository ARN, keep ecr:GetAuthorizationToken on Resource: "*".
4. Back in the secret form, enter the “IAM role ARN” and “AWS region”, then click Save.
5. In the runner’s “Private image credential” dropdown, choose the secret. Its registry host must match the image’s registry.

Warp derives the registry host from the role’s account ID and AWS region, and checks role assumption and token retrieval when you create the secret. Creation doesn’t check repository-specific pull permissions.

The credential authenticates image pulls, not commands inside the run. Self-hosted workers use their backend’s registry authentication; see private container registries.

Delete the secret to stop Warp using that reference. Change the IAM role to update its ECR permissions.

Troubleshooting

A secret isn’t available to the agent

Check that the secret exists in the factory’s team and is attached through the agent’s effective configuration. A personal secret won’t appear in the factory picker. If configuration is read-only, change the external definition files.

For a raw execution secret, use Raw value, not a harness-auth or image-pull credential type. Check the external credential’s permissions and expiry if the variable is present but authentication fails.

A secret value is too large

Each injected NAME=value entry must fit within 128 KiB (131,072 bytes), including the terminating null byte. The value budget excludes the bytes used by the name, =, and null byte; credentials that expand into several variables are checked per variable.

Store larger payloads in an object store or external secret manager and keep only the fetch credential in Warp.

Warp could not assume the IAM role

Check that the role exists, the ARN is correct, and its trust policy matches the form, including your team’s sts:ExternalId. AWS returns AccessDenied for missing roles and trust-policy denials. For other errors, check that AWS STS is available in the registry’s region.

Warp assumed the role, but could not get an ECR token

Confirm that the role allows ecr:GetAuthorizationToken on Resource: "*". For access denials, check permissions boundaries and AWS Organizations service control policies. For other failures, confirm that the AWS region matches the registry.

Image pulls fail

Confirm that the role grants ecr:BatchCheckLayerAvailability, ecr:BatchGetImage, and ecr:GetDownloadUrlForLayer for the repository, and that the credential’s registry host matches the image’s registry.

Related pages

• Factory agents - Configure an agent’s runtime and authentication
• Definitions as code - Manage secret references in version control
• Infrastructure and security - Understand credential boundaries
• Legacy cloud agent secrets - Manage secrets with the supported oz secret commands