Credential Vault & BrokeringNEW
How Sophon stores service credentials encrypted and brokers access so agents never see raw secrets.
Sophon needs tokens for dozens of services — Gmail, GitHub, Slack, cloud providers — but the LLM driving your agent should never touch a raw secret. The credential vault solves both halves of that problem: it stores every credential encrypted at rest, and it brokers access so the token is injected at the network boundary, not into the prompt.
This is the same default-safe posture as Approval Gates: the agent operates on capabilities, not credentials.
Where credentials live
Credentials live inside your data directory under ~/.sophon, written by the LocalVaultBackend. Each credential is serialized to JSON, encrypted, and stored as a single .vault file in ~/.sophon/vault/. The storage key is scoped per user as {userId}_{serviceId}, which is how multi-tenant deployments keep one user's tokens strictly isolated from another's.
A stored credential (CredentialData) can hold an access token, a refresh token, a static API key, an expiry timestamp, and an Extra bag for service-specific fields. OAuth-connected services also keep their refresh token here so the runtime can renew expired access tokens automatically.
The vault backend is pluggable via the Sophon:Vault:Provider setting (local, hashicorp, aws, or azure). The local provider is the default and is what Personal-tier installs use.
Encryption at rest
The local backend never writes plaintext. It delegates encryption to an IKeyProtector, chosen per platform:
| Platform | Protector | Mechanism |
|---|---|---|
| Windows | DpapiKeyProtector | DPAPI ProtectedData scoped to CurrentUser — tied to your Windows account |
| Other OSes | Base64KeyProtector | AES-256-CBC with a random key persisted at ~/.sophon/security/vault.key |
On Windows the encryption is bound to your OS user account, so the ciphertext cannot be decrypted by another account or on another machine. On non-Windows platforms the AES key in security/vault.key is what protects the data — it is included in backups, and without it the encrypted credentials cannot be recovered.
Never paste an API key, token, or password directly into a chat message. Anything you type into a conversation becomes part of the LLM context — exactly what the vault exists to avoid. Always add credentials through Connections (Dashboard, sophon connect, or the API) so they go straight into the encrypted vault.
The broker model
Brokering is what keeps raw tokens out of the model. When a tool needs to call an external service, the runtime — not the LLM — fetches the token from ICredentialVault.GetAccessTokenAsync(serviceId, userId), makes the API call outside the model context, and returns only the sanitized result back to the agent.
For sandboxed skills this is expressed in the skill's manifest.json. A skill declares the credentials it requires and how it wants to use them:
"credentials": [
{ "service": "google-calendar", "scopes": ["calendar.readonly"], "access": "proxy" }
]Two access modes are supported:
"access": "proxy"(default, most secure) — the sandbox returns an API-call instruction; the runtime executes it with the real token outside the sandbox and passes the response back in. The skill never holds the secret."access": "injected"(opt-in) — the runtime injects a short-lived, scoped token into the container for the duration of one execution. This is flagged during marketplace review and reserved for skills that genuinely cannot use the proxy.
Because of this, even a compromised skill cannot exfiltrate a credential — at worst it can abuse the specific authorized call for the short lifetime of its broker token.
Connection scopes
Scopes are bound at connect time, not at call time. When you start an OAuth connection, Sophon uses the scopes you request, falling back to the service's DefaultScopes if none are given. The resulting token therefore carries only the permissions you granted, and the access mode in a skill manifest narrows what that skill can do with it.
Connection lifecycle — connect, test, refresh, revoke — is managed through the connection service and surfaced identically across the Dashboard, the sophon connect CLI, and the REST API. See Connections for the full setup walkthrough and the list of supported services.
What this guarantees
- The LLM prompt and context window never contain a raw token.
- Credentials are encrypted on disk with platform-native key protection.
- In multi-tenant mode, each user's credentials are isolated by vault key scoping.
- Every credential access can be recorded in the audit trail.
For the broader hardening picture — approvals, sandboxing, and desktop control — see the Security Overview and the Threat Model.