Add a secret as an operator
The vault requires PostgreSQL andMESH_AGENT_MASTER_KEY. From the agent’s page,
open Vault → Manage vault and choose Add secret.
- Give the entry a name the agent can refer to, such as
SENTRY_TOKEN. - Add a short description explaining its intended use. Names and descriptions are visible to the model, so keep the secret value out of both.
- Paste the value into the secret field and save.
- Tell the agent which entry to use, without pasting the value into chat.
Provide a secret through a drop link
When an agent needs a missing credential, it can callvault_request with a name
and description, then share a one-time URL in the conversation. Open the link,
check which agent and entry it names, paste the value, and choose Hand it over.
You do not need a Formation account or sign-in. The value goes straight into the vault;
it is not added to the conversation as a message. Formation queues a run so the agent
can confirm receipt in the same thread. If it is already working there, that
confirmation waits until the conversation is idle.
Drop links require PUBLIC_URL as well as the vault’s database and master key.
vault_request is offered only in a turn with a durable conversation and anchor
message. It returns url and expires_at, and refuses a name already in the
vault unless the agent sets replace: true. The agent should check vault_list
before requesting a value.
Each link accepts a value once, for 15 minutes. After that, Send me a new
link remains available until 72 hours after that link was issued, subject
to a limit of five renewals per request. The agent posts the replacement in
the original conversation; the expired page does not display it. Each replacement
gets fresh expiry times. Opening or previewing a link does not consume it.
An expired page can request another replacement if delivery failed, within those
limits. Repeated requests while its renewal is pending or running have no extra
effect. Once any link in the request is used, its other links stop working. Used
or revoked links, expired links with no renewals left, and links older than
72 hours show the same invalid-link page; ask the agent for a new request in the
conversation.
Treat the URL as a credential: anyone holding it can submit a value for that
entry, although they cannot read a stored value. Operators can inspect outstanding
requests under Open drop links on the Vault page and revoke individual links.
The list shows metadata and expiry times, never the token.
How an agent uses a secret
The agent can manage entries with:
There is no tool that returns a plaintext value. The agent passes an entry name
to one of these supported use sites:
The corresponding browser or workspace capability must already be available to
the agent. The vault does not enable either one. Workspace calls may request up
to 16 entries, using their exact stored names; environment variable suffixes are
uppercased. Formation refuses a command if two requested names map to the same
environment variable, such as
token and TOKEN; request only one of them.
For example, a command can read MESH_SECRET_SENTRY_TOKEN from its environment
instead of embedding a token in a command argument. Formation redacts exact delivered
values from workspace output and withdraws the per-command entries from its grant
file when the command returns. Rotation takes effect on the next use; forgetting
or replacing an entry does not tear down a running sandbox.
What the vault protects
Values are encrypted at rest in their own table. Formation derives a vault-specific key from the installation master key using HKDF-SHA256, then uses authenticated encryption bound to the agent and entry name. Vault rows have no plaintext-derived hint. Public drop lookups use a hash of the token. Renewal workers also keep an encrypted token so a retry can recover the same URL and expiry. Key rotation and verification cover both vault entries and these renewal tokens; follow secrets and recovery for backup and key handling. Using an entry by reference avoids putting its value directly into the tool’s model-visible arguments and stored tool result. It is still delivered to the browser page or command that needs it. A website can expose what is typed, and a command can transform or send an environment value. Exact-value redaction is not a security boundary against code with access to the secret. Only provide credentials appropriate for the work and tools entrusted to that agent. Browser observations can show visible input values or website content after a fill. Avoid treating the vault as a guarantee that a website cannot reflect a secret into an observation. Operator reads of the vault itself never return it.Current boundaries
Plaintext reveal, TOTP generation, and secret injection into arbitrary MCP tool arguments are unavailable. Earlier design notes described these as possible extensions; they are not setup steps or supported tools.Operator API
These routes require access to the agent; writes also require write permission. All responses useCache-Control: no-store.
The public drop endpoints use the link token as authorization and need no operator
session. See the operator API reference for their
contracts, validation, and error responses. The implementation is in
internal/vault, internal/admin/vault.go, internal/admin/vault_drops.go,
internal/webbrowser, and tools/workspace.