Credentials
Agents need credentials constantly — a model API key, a Notion token, a deploy token. The whole stack answers one question for each of them: is the code that uses this credential trusted to read it? That gives three tiers.
Held: the agent’s own credentials
Section titled “Held: the agent’s own credentials”Some credentials the agent is meant to hold — above all, the user’s model
key or CLI login. On a local host, the spawned CLI (claude, codex) simply
uses its own logged-in credentials. On a remote host, the config snapshot’s
auth map injects explicit keys as ordinary environment variables. Either way,
the value is readable inside the session, on purpose.
Requested: connection tokens, per operation
Section titled “Requested: connection tokens, per operation”Tokens for external accounts (GitHub, Notion, Atlassian, Google) are never
handed out wholesale. @claxedo/connections links an account once, then
features request a token per operation, by capability (docs,
work-source, channel, code-host) — never by hard-coding a provider, and
never caching the token:
- One connection can power several capabilities on one credential (an Atlassian
link serves Confluence
docsand Jirawork-source). - Capabilities are granted at connect time from what the credential actually covers — broadening them means reconnecting, not toggling a flag.
- A definitive provider rejection marks the credential errored and stops token serving until the user reconnects; transient failures just retry.
Consumers see { token, tokenType, fields? } and nothing else. Storage, HTTP
gates, and auth policy belong to your host — the kit reads no env and enforces
no policy.
Brokered: secrets a sandbox must use but never read
Section titled “Brokered: secrets a sandbox must use but never read”When a session runs in a cloud sandbox, some credentials must ride outbound
requests without ever being readable inside the sandbox (connection tokens,
deploy tokens — anything an agent could exfiltrate). @claxedo/sandbox-manager
passes these as brokered secrets: the raw value stays outside; the provider
injects it on egress, and only toward an allowlist of hosts.
The contract is fail-closed: a driver that cannot broker
(secretBrokering: "none") makes the manager refuse to provision —
status: "unavailable", error: "secret_brokering_unsupported" — rather than
silently downgrade the secret to readable env. Brokered values are never
logged, never written to labels, never captured in snapshots.
Who stores what
Section titled “Who stores what”Long-term credential storage is a control-plane concern — the packages
move credentials, they don’t keep them. Your server stores connection
credentials behind the two @claxedo/connections storage ports, decides which
sessions get which auth entries, and chooses what to broker into which
sandbox.