Managing factory secrets

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 Configuring AWS ECR credentials 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

ECR credentials authenticate private image pulls, not agent tools. For IAM setup, runner attachment, and troubleshooting, see Configuring AWS ECR credentials.

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.

Related pages

• Configuring factory agents - Edit runtime settings and harness authentication
• Definitions as code
• Infrastructure and security
• Configuring AWS ECR credentials - Pull private images on Warp-hosted Linux runners
• Legacy cloud agent secrets - Manage secrets with the supported oz secret commands