Managing secrets for factory agents

Secrets give factory agents credentials for external services without putting values in prompts or definition files. For example, you can 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 agents access. The “Secrets” page covers your team, not one factory.

Secret ownership and agent access

Creating a team secret doesn’t automatically give every agent access. Attach the secret to an agent or include it in the factory configuration. Raw values are injected as environment variables using the secret name.

Personal secrets from legacy workflows aren’t listed in the factory secret picker.

Harness authentication and inference credentials use separate configuration. For private Amazon ECR images, use the ECR credential workflow instead of a raw-value secret.

Creating a raw-value secret

Prerequisites:

• A credential for the external service, preferably from a minimally scoped service account.
• Permission to create team secrets and, when granting access, to edit agent configuration and attach secrets.

Raw-value secrets supply API tokens and other credentials to tools during a run.

1. In the Warp Factories web app, click Secrets in the sidebar.
2. Click New, then Create secret. On an empty list, you can also click New secret.
3. At the top of the form, click Untitled and enter a name such as METABASE_API_KEY.
4. In the “Type” dropdown, choose Raw value, then enter the credential in the “Value” field.
5. Optionally, add a description identifying the credential’s purpose, owner, and rotation policy.
6. 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.
7. Click Save.

The secret appears in the team list with its stored value hidden. Its Agents tab lists the agents using it.

Factory selection updates current agents, not future agents. Configure inherited access through factory-wide and inherited access.

Granting agents access

Grant agents access to an existing team secret through the web app or definition files.

Using the web app

For a Warp-managed factory, edit the agent in the web app. Externally managed factories have read-only configuration here. Use definition files instead.

1. In the Warp Factories web app, click your factory in the sidebar to expand it, then click Agents.
2. Click the agent you want to give access to the secret.
3. In the agent’s Settings tab, next to “Secrets”, click Add secret.
4. In the secret picker, select the existing team secret, then click Add.
5. In the top-right corner of the agent’s settings page, click Save.

The agent’s settings now list the secret.

Using definition files

For the reporting agent, reference the existing METABASE_API_KEY secret by name. Never commit its value.

1. Open the factory definition where it’s managed.

2. In agents/reporting/agent.md, add a secrets list to the 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.

3. For a Warp-managed factory, save the definition. For an external repository, merge to its production branch through a pull request.

Factory-wide and inherited access

Choose the secret list based on which agents need access:

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

An empty execution-secret list doesn’t disable separately configured harness authentication or MCP credentials. See the definition reference.

Verifying access

After saving the configuration:

1. Start a new run and ask the agent to confirm that METABASE_API_KEY is set without printing its value.
2. Ask the agent to list Metabase dashboards with a permitted read-only request, without including credentials in its output.

The first check confirms injection. The second verifies authentication for that operation.

AWS ECR credentials

An “AWS ECR credential” lets a Warp-hosted Linux runner pull Amazon ECR images. Warp stores the role ARN and requests a short-lived token per run. Create the credential in the web app, not the legacy CLI.

Creating the ECR credential

1. In the Warp Factories web app, click Secrets, then click New > Create secret.
2. At the top of the form, click Untitled and enter a secret name such as ECR_PULL_CREDENTIAL.
3. In the “Type” dropdown, choose AWS ECR credential.
4. 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: "*".
5. Back in the secret form, enter the “IAM role ARN” and “AWS region”, then click Save.

Warp derives the registry host from the role’s account ID and region. Creation checks role assumption and token retrieval, not repository-specific pull permissions.

Attaching the credential to a runner

For a Warp-managed factory:

1. In the Warp Factories web app, click your factory in the sidebar to expand it, then click Settings.
2. In the “Runners” section, click the pencil button labeled Edit runner next to the Linux runner.
3. In the runner editor’s “Private image credential” dropdown, choose the ECR secret you created. Its registry host must match the image’s registry.
4. Click Save.

For an externally managed runner, set platform.linux.registryCredentialSecretName to the secret name in its YAML file and apply the change through a pull request. See runner file syntax.

The credential authenticates image pulls and isn’t injected into the agent environment. Self-hosted workers use backend-specific registry authentication instead.

To change ECR permissions, update the IAM role in AWS. To retire the credential, remove its runner references, then delete the team secret.

Rotating a raw-value secret

Replace a raw-value secret’s stored value without changing its name so existing agent references continue to work.

1. In the Warp Factories web app, click Secrets, then open the secret you want to rotate.
2. In the top-right corner, click the three vertical dots to open the actions menu, then click Edit.
3. In the “Value” field, enter the replacement credential, then click Save.

New runs use the updated value. Confirm the replacement works before revoking the old credential. For CLI rotation, see updating a secret.

Removing access or deleting a secret

Removing one agent’s access preserves the shared secret. Deleting the secret affects every agent, webhook, or runner that references it.

Removing a secret from one agent

For a secret attached directly to an agent in a Warp-managed factory:

1. In the Warp Factories web app, click your factory in the sidebar to expand it, then click Agents.
2. Open the agent and click its Settings tab.
3. Next to “Secrets”, click the remove button (×) on the secret you want to remove.
4. In the top-right corner, click Save.

For inherited access, change the relevant secret list. Removing a per-agent entry doesn’t remove a factory-wide grant. Apply externally managed changes through the repository.

Deleting a team secret

1. In the Warp Factories web app, click Secrets, then open the secret you want to delete.
2. In the top-right corner, click the three vertical dots to open the actions menu, then click Delete.
3. Confirm the deletion.

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.

Troubleshooting

A secret isn’t available to the agent

Confirm the secret belongs to the factory’s team and appears in the agent’s configuration. For read-only configuration, edit the external definition.

Use Raw value for execution secrets. If the variable is present but authentication fails, check the credential’s permissions and expiry.

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.

ECR role assumption fails

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.

ECR token retrieval fails

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.

ECR 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

• Configuring factory agents - Edit runtime settings and harness authentication
• Definitions as code
• Infrastructure and security
• Legacy cloud agent secrets - Manage secrets with the supported oz secret commands