Credential vault

Overview

The usual way an agent gets a secret is the worst way: you paste it into the chat. From that moment the value lives in the conversation transcript — stored, indexed, searchable, and replayed into every subsequent request. Deleting the message does not un-index it.

The C3 vault removes that step. You store the secret once; the agent refers to it by name. When a command actually needs the value, C3 decodes it into the subprocess environment and nowhere else.

What this is not

• Not a team secret manager. It is local, single-user, and backed by your OS keyring. It does not sync, rotate, or issue short-lived credentials. If you need Vault or AWS Secrets Manager, use those — and store their bootstrap token here.
• Not a substitute for scoping your tokens. The vault controls where a value travels inside C3. It cannot reduce what the token itself is allowed to do.
• Not obfuscation dressed as encryption. Values sit in the OS keyring, which is exactly as strong as your OS login. Anything C3 could decode on its own would be reversible by anyone holding the code.

Quick start

c3 creds set NPM_TOKEN

c3 creds list

c3_shell(cmd='npm publish',
         env_creds='NPM_TOKEN')

Anything shared across every project — a personal GitHub PAT, an OpenAI key — belongs in the global vault:

c3 creds set OPENAI_API_KEY --global

Bulk-import an existing .env file (each line becomes an entry of type env):

c3 creds import .env
c3 creds import .env --global

Where values live

C3 adds secrets.enc and cred_state.json to .c3/.gitignore when the first credential is stored, so they cannot be committed even in projects that deliberately track .c3/.

Fingerprints

A fingerprint is the first 8 hex characters of sha256(value), computed live on request and never persisted. It answers "is the thing in the vault the thing I think it is?" — compare two machines, or confirm a rotation actually replaced the value — without revealing anything about it.

Scopes & overriding

Overriding is the mechanism for per-environment values. Keep a personal GITHUB_TOKEN in the global vault, then give one client project its own project-scoped GITHUB_TOKEN; work in that project resolves to the local one, everything else still gets the global.

The Hub shows the relationship from both directions: a project entry that wins over a global carries overrides global, and the global entry it beats carries overridden ×N with the project names on hover.

How agents use them

Three injection paths, all of which decode at the subprocess boundary:

1. Explicit env vars

c3_shell(cmd='npm publish', env_creds='NPM_TOKEN')
c3_shell(cmd='terraform apply', env_creds='AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY')

Each named entry is exported into the child process under its env_var (defaulting to the entry name).

2. Inline templates

c3_shell(cmd='curl -H "Authorization: Bearer {{cred:API_KEY}}" https://api.example.com')

{{cred:NAME}} is expanded server-side, after the model has produced the command string. The model writes the placeholder; it never writes the secret.

3. Auto-inject

An entry flagged inject is exported into every c3_shell run in its scope without being named. Convenient for a token every build step needs — and correspondingly broader, since any command that runs there can read it from the environment.

Echo redaction

Any value decoded during a session is tracked process-locally, and output is scrubbed on the way back: a command that echoes the secret returns [cred:NAME] instead. This is a safety net, not a guarantee — a transformed value (base64-encoded, split across lines, hashed) will not match and will pass through.

Exposure flags

Two per-entry switches, both off by default, that control how far a value is allowed to travel. The Hub's settings drawer groups them under Exposure and spells out the blast radius of each.

Reach for agent_readable only when the agent genuinely must reason about the value itself — pasting a key into a config file it is authoring, say. For "run this command with my token", injection is both sufficient and strictly safer.

Hub UI

Run c3 hub and open the Credentials tab in the top bar. It manages the global vault and every registered project from one place. The same manager appears in each project's drill panel and in the per-project dashboard, so there is one interface to learn.

Two sub-tabs

The settings drawer

Click any credential — or press ↵ on a focused row — to open its settings drawer. This is the only surface that edits an existing entry or replaces a value.

Context menu

Right-click any credential row for the full action set. The same menu opens from the ⋯ button on the row, and from Shift+F10 or the Menu key when the row is focused. Arrow keys navigate it; Esc closes it.

Importing a .env

Import .env in the manager toolbar takes pasted KEY=VALUE lines. Comments and export prefixes are tolerated; each line becomes an entry of type env. Existing names are skipped rather than overwritten, and the response reports created and skipped counts by name.

Search & qualifiers

The search field sits above both sub-tabs and covers every project at once. Press / or Ctrl/⌘+K to focus it from anywhere on the page.

Results are grouped by credential name, with every definition of that name listed underneath — the global vault first, then each project that defines it. "Where is STRIPE_KEY configured, and which one wins?" is one glance rather than expanding forty accordions.

STRIPE_KEY · 3 definitions
  Global vault      global   token · ••••64
  Payments API      project  overrides global
  Billing worker    project  overrides global

Qualifiers

Bare words are matched (AND) against name, description, env var, and owning project. key:value terms narrow further and can be combined freely.

Sorting & scope

Chips narrow results to All, Global, or Project. Sorts: name, most defined (widest sprawl first), last used, most used, and exposure — which floats agent_readable entries to the top, then inject. ↑↓ walks the results and ↵ opens the highlighted one.

The same qualifier syntax works in the per-manager Filter box, which narrows the list you are already looking at instead of searching across projects.

CLI commands

c3 creds get --show is the escape hatch for when you need to see a value — reading it into your own clipboard, not the agent's context. It is a local terminal command and has nothing to do with the agent_readable flag.

Tool actions

What the agent can call through c3_credentials. Read actions are safe in plan mode.

The full parameter reference lives on the tool card.

Audit trail

Every mutation and every reveal is logged by name — never by value.

To review what happened to one credential:

c3_edits(action='history', file='cred://NPM_TOKEN')

Troubleshooting