> For the complete documentation index, see [llms.txt](https://docs.warp.dev/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Managing factory secrets

Create and rotate team secrets for Warp Factories, and grant agents access through the web app or definition files.

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](https://platform.warp.dev), 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](https://docs.warp.dev/factories/infrastructure-and-security/#credential-boundaries). For private Amazon ECR images, use [Configuring AWS ECR credentials](https://docs.warp.dev/factories/secrets/aws-ecr/) 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](https://platform.warp.dev), 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](#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](#using-definition-files) instead.

1.  In the [Warp Factories web app](https://platform.warp.dev), 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](https://docs.warp.dev/factories/factory-as-code/#where-the-definition-lives).
    
2.  In `agents/reporting/agent.md`, add a `secrets` list to the frontmatter.
    
    ```markdown title="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](https://docs.warp.dev/factories/factory-as-code/#secrets).

### 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](https://docs.warp.dev/factories/secrets/aws-ecr/).

## 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](https://platform.warp.dev), 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](https://docs.warp.dev/platform/secrets/#updating-a-secret).

Webhooks pick up the new value when their definition is reapplied. See [Manage webhooks](https://docs.warp.dev/factories/webhooks/#manage-webhooks) for the rotation procedure.

## 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](https://platform.warp.dev), 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](#factory-wide-and-inherited-access). 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](https://platform.warp.dev), 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](https://docs.warp.dev/factories/factory-agents/configuration/) - Edit runtime settings and harness authentication
-   [Definitions as code](https://docs.warp.dev/factories/factory-as-code/)
-   [Infrastructure and security](https://docs.warp.dev/factories/infrastructure-and-security/)
-   [Configuring AWS ECR credentials](https://docs.warp.dev/factories/secrets/aws-ecr/) - Pull private images on Warp-hosted Linux runners
-   [Legacy cloud agent secrets](https://docs.warp.dev/platform/secrets/) - Manage secrets with the supported `oz secret` commands