The Account Keychain

The keychain holds the logins your agents work with: an API key for a service, a username and password, a token, an authenticator seed. You enter a value once, grant it to the agents that need it, and the value is delivered into those agents' sessions. No screen and no API call reads it back afterwards.

Three credential surfaces exist and they do different jobs:

• The keychain is account-owned and granted per agent. Use it for the third-party services an agent signs into while it works.
• Environment secrets belong to one environment and are referenced from its manifest as ${secrets.NAME}. Use them for build and service configuration.
• Agent credentials, the GitHub identity and model keys, are what the agent runs as. They are not keychain entries.

Add a Credential

Open the agent's page and find the Logins section, which is where the account keychain appears on that page, then choose Add credential. If the account already holds the credential, Grant existing hands the agent the one that exists instead of typing a second copy.

1. Name it something you will recognize in a list, for example Mixpanel (read-only).
2. Pick the kind. The kind changes nothing about how the value is stored. It tells the agent what it is holding.
3. Paste the value and save. For a login, also enter the username, which is stored in the clear so the agent can tell which account it is signing in as.

Adding and granting a credential is open to any member of the account. What protects a value is that nothing returns it after entry, not a role gate on who may hand out names.

What the Agent Gets

The agent gets a reference, which is derived from the name you chose and is not a secret. Mixpanel (read-only) becomes KEYCHAIN_MIXPANEL_READ_ONLY. The dialog shows the reference before you save, so you can put it in a playbook or a handbook page ahead of the credential existing.

The value reaches the agent as a shell variable in the commands it runs itself:

curl -H "Authorization: Bearer $KEYCHAIN_MIXPANEL_READ_ONLY" https://api.example.com/events

A login pair adds a companion variable for the username, KEYCHAIN_MIXPANEL_READ_ONLY_USERNAME.

Two boundaries are worth knowing:

• The value lands only in the commands the agent issues. It is not in the environment block your services and setup steps inherit, and it is not baked into a snapshot.
• A credential arrives at the start of a session. A grant made while a session is running reaches the agent on its next one.

Signing Into a Website

When an agent drives its browser, it types a stored credential by naming it rather than by producing the value. The secret goes from the sandbox into the field, so it never appears in the session transcript that the model and the task record both hold.

You do not configure this. Granting the credential is enough, and the agent's acknowledgement names the credential and no value. If an agent names a credential it has not been granted, the call is refused and the refusal names the credentials it does hold.

A Value That Reaches the Record Is Replaced by Its Name

A granted value can still surface inside a turn by accident: a command echoes an Authorization header, a failed sign-in prints the body it sent, a verbose tool logs its whole request. Wherever that happens, Wallfacer swaps the value for the credential's reference before the turn is written down. One record reads [redacted:credential:KEYCHAIN_TRELLO] in the sandbox log, in the session's events, and in the transcript the agent reads back on its next turn.

What the swap covers, and what it does not:

• It matches the values granted to this agent, and nothing else. Wallfacer does not guess at secrets by their shape. A key you pasted into a file yourself is not covered; the same key stored on the keychain and granted is.
• Very short values are left alone. A value under eight bytes is not matched, because replacing every occurrence of a four-character string ruins the output it was meant to protect.
• A login's companion username is not redacted. It is stored in the clear, shown in the app, and returned by the API, and it is usually an address that appears in git commits and unrelated service output anyway.
• The set never reaches the model. Values are delivered to the shell the agent's commands run in, and removed from the environment the model's own process starts with. A command the agent issues is the only route to a value.

Time-Based Codes

Store an authenticator seed as a Time-based code credential, either the bare base32 secret or the otpauth:// URI the service shows next to its QR code. Wallfacer reads the digit count, period, and algorithm from the URI and defaults to six digits on a thirty-second period.

The seed itself is never delivered anywhere. When a login asks for a code, one is minted from the seed at that moment, and every mint is recorded with the agent and the session that asked for it. Other kinds are recorded once per session they are delivered into, which is the weaker claim and the honest one: a key handed to a session produces no further signal as the agent uses it.

Storing a seed beside the password it protects means the platform holds both factors, which reduces that account's two-factor protection to one factor for anything the agent can reach. It is the same trade a password manager that stores your codes makes. Where the service offers a scoped API key, use that instead.

Replace, Revoke, and Who Else Holds It

Each credential in the section shows its kind, when it was added or granted, and which other agents hold it. Three actions sit beside it:

• Replace value rotates the secret without removing the working one. Sessions already running keep the old value until they end.
• Revoke takes the credential away from this agent. The agent's next session starts without it, including a session that reuses a sibling task's computer. The credential stays on the account for the agents that still hold it.
• Give to another agent grants the same credential to a second agent, with no second copy of the value.

Nothing on any of these paths displays the value. Save a copy somewhere safe before you paste it in, because the entry field is the last place you will see it.

An Agent Can Save a Login It Creates

When an agent's own work produces a login, for example it signs up for a service or a service issues it an API key, the agent stores that credential on the keychain itself and reports it back by name. The value is minted and stored inside the agent's own shell, so it never enters the conversation.

The rules the agent follows are worth knowing, because they are what you should expect from it:

• It stores only values its own work created.
• It never asks you to paste a secret into a conversation. A secret you hold goes in through the app.
• It tells you the name of what it stored and never the value.

Through the API

The keychain is CRUD under /v1/accounts/{account_id}/credentials, with grants addressed by agent under /v1/accounts/{account_id}/credentials/{credential_id}/grants/{agent}. To see what one agent holds, call GET /v1/accounts/{account_id}/agents/{agent_user_id}/credentials.

Responses carry the name, reference, kind, grant dates, and how each credential is audited. No route returns the value or anything derived from it. See the API Reference for exact fields.

Storing or replacing a value can fail with 502 and errors[].code: "kms_error", which means the key service that seals credential values could not complete the request. Nothing was stored and an existing credential is unchanged, so retry the same request.

Related

• Agents for the page the Logins section lives on.
• The Agent's Browser for the sign-in flow those credentials are typed into.
• Environments and Secrets for secrets that configure a build rather than sign an agent in.
• Settings for account-level integrations and API tokens.