Vaults and credentials

Where a session's tool credentials live. The broker uses them at call time; the engine and the model never see them.

An agent that can only talk is not much use. The moment it reaches a real system it needs a real credential — and the one place that credential must never end up is in the model’s context.

A vault is a workspace-scoped store of credentials. A session names the vaults it may draw from; when a tool call goes out, the broker matches it against those vaults, attaches the credential, and makes the call. The engine is handed the broker’s URL and a run token, never a secret.

Creating a vault

subako vault create --display-name "Acme production"
subako vault list

--metadata takes a JSON file of arbitrary data to store alongside the vault — a tenant id, a region, whatever your own routing needs.

Adding a credential

The payload is read from stdin as JSON, so secrets stay out of your shell history and out of the process list.

subako vault add-credential <vault-id> \
  --protocol mcp \
  --target https://mcp.acme.example/sse \
  --display-name "Acme MCP" < credential.json

The protocol is stated, never defaulted. It decides how --target is read, and a vault holds each target once per protocol at a time: adding a second live credential for a target it already holds is refused with credential target already exists.

The payload arrives on stdin as JSON, and names its auth_scheme — which says what the rest of its fields are:

{ "auth_scheme": "static_bearer", "token": "..." }

oauth is the other scheme; it carries access_token, and optionally expires_at and a refresh block.

Listing and deleting

subako vault credentials <vault-id>

Credentials are listed, never their payloads. There is no read-back: a secret goes in and only the broker sees it again.

subako vault delete-credential <vault-id> <credential-id>
subako vault delete <vault-id>

Both ask you to type the id back; --yes skips that for scripts. Deleting a credential purges its secret and frees the target it claimed, so the same target can be given a new credential — that is how you rotate one. Deleting a vault takes every credential in it and purges all of their secrets.

Why the session names the vaults

Vaults are named per session, not baked into an agent version. One published version can therefore serve one customer against their production vault and another against a sandbox, with nothing republished in between — the version says what the agent may do, and the session says whose credentials it does it with.