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. A value spanning several lines inside one pair of quotes — a PEM key, a JSON service account — is imported whole and typed multiline; everything else becomes an entry of type env.

c3 creds import .env --dry-run
c3 creds import .env
c3 creds import .env --global
c3 creds import .env --only STRIPE_KEY,DB_URL

--dry-run prints a table of what would land — name, line, type, value length, fingerprint, and a reason for anything it will skip — and writes nothing. Skips are per-name and explained: already exists, not a usable credential name, no value, quote never closes, redefined later in the file.

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.

Structured kinds — cards, addresses, identity, logins (v2.87.0)

Four entry types hold named fields instead of one opaque value: card (cardholder, number, expiry, optional cvc/billing_zip — Luhn-checked), address (street1, city, state, zip, optional recipient/street2/country/phone), identity (full_name, optional dob/ssn/phone/email) and login (site_id, canonical_target, username, optional password/private_key/passphrase/totp_secret — v2.90.0, generalized v2.118.0). The payload is stored as one canonical JSON object through the same keyring / encrypted-sidecar path as any other value.

They are inject-only by construction, which is stricter than a normal secret:

• Reveal is permanently disabled — agent_readable and inject are refused at every surface, for every caller, forever. There is no flag to flip.
• Only single fields cross the boundary. The agent addresses a field — env_creds='CARD.number' (exported as $CARD_NUMBER) or {{cred:CARD.number}} inline — and a bare {{cred:CARD}} fails with the field list rather than expanding the whole payload.
• The registry shows a projection, not the data. Lists and the UI display visa ••••4242 for a card (brand + last4, deliberately not expiry), city/state for an address, the name for an identity, and github · https://github.com · 2FA or build01 · ssh://build01.lan:22 · key for a login — site, target and 2FA/key booleans, with the username withheld on purpose, because username + target is half the credential. Field names are public; field values never transit any HTTP response — a sweep test enforces this.
• Echoes redact per field to [cred:NAME.field]. Caveat: the redactor only tracks values of 4+ characters, so a 3-digit CVC or 2-letter state that a child process echoes cannot be scrubbed after the fact. The real guarantee remains decode-at-the-subprocess-boundary; redaction is the belt over it.
• The type boundary is immutable. A card cannot be rewritten into a plain token (or vice versa) by set, metadata update, or .env import — delete and re-create is the only path across, and a keyring attestation keeps an entry structured even if .c3/config.json is edited by hand.

Updating one field never requires retyping the rest: a partial payload merges ({"expiry": "01/30"} updates the expiry, JSON null deletes an optional field). Read-back for you is terminal-only: c3 creds get NAME --show (all fields) or --show --field number — the browser and the mobile gateway never carry the values, and mobile cannot create structured entries at all.

login is storage only, and that is a design constraint, not a gap. C3 has no browser surface and must not grow one: a login runner in which the agent picks the destination turns page-content prompt injection into credential exfiltration, and a check written into a script that already holds the plaintext in its own environment is not a boundary — the script can simply not call it. That is what canonical_target is for: stored normalized (scheme://host[:port], no path/query/fragment/userinfo, host lowercased), so a separate out-of-process runner that the agent does not author can pin a credential to exactly one destination and check where it is actually about to authenticate before typing. That runner is deliberately not shipped in this package. totp_secret must be base32 — a malformed seed produces wrong codes that look exactly like a wrong password.

Not just websites (v2.118.0). A login holds any target with one unambiguous destination: ssh://build01.lan:22, postgres://db.internal:5432, rdp://jump.corp, smb://files.lan. The scheme comes from an allowlist (https, ssh, sftp, ftps, rdp, smb, vnc, winrm, ldaps, imaps, smtps, amqps, postgres, mysql, mariadb, mssql, mongodb, redis); cleartext schemes are refused by name and told which TLS variant to use instead, for the same reason http:// always was. A server login may carry a private_key (PEM/OpenSSH, checked, with its own size allowance and an optional passphrase) instead of a password — one of the two is required, because a login with neither is not a credential.

The origin-pinning property is preserved, not weakened: canonical_origin is still a valid field name and still reads back — but only when the target is https. A browser broker that pins a credential by asking for canonical_origin gets nothing for an ssh:// entry and fails closed, rather than being handed a string it cannot compare to a top-level frame. Entries stored before v2.118.0 need no migration: the old field name is accepted on input and resolves on read.

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, so those two are one interface.

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.

Four of these have bulk equivalents — see Filters & bulk actions. The two that enable exposure deliberately do not.

Importing a .env

Import .env in the manager toolbar opens a chooser: pick a file, drop one on the panel, or paste KEY=VALUE lines. Comments and export prefixes are tolerated.

Nothing is written until you say so. Preview parses the file and shows a table of every row — name, line, type, value length, and a fingerprint — with anything it cannot import disabled and explained in place. Tick the rows you want and press Import. Replace entries that already exist is off by default, so a second import of the same file is a no-op rather than a silent overwrite.

Replacing an existing entry rotates its value and nothing else. The description you wrote, the custom env var, the type you chose, and the auto-inject and agent-read settings all survive. Before 2.93.0 an overwrite rebuilt the entry from scratch, which quietly turned auto-injection off.

If C3 read the file from a path on this machine, it remembers which file each entry came from — see Re-syncing a .env. A pasted body has no path to remember, so it records no source.

Re-syncing a .env

A .env drifts all week; the first import is never the last one. When C3 imported entries from a path on this machine it records that path, and the manager grows an Imported from strip listing each remembered file with an entry count, when it was last synced, and a Re-sync button.

Re-sync re-reads the file on the server and compares every value against the stored one by digest, so it can tell you what changed without either value reaching the browser. Each row comes back as one of four answers:

If the file changes between the preview and the import, the commit is refused rather than silently applying content you never saw: press Re-check to see the new answer.

Filters & bulk actions

Narrowing the list

Above every credential list is a row of chips — agent-readable, auto-inject, structured, shadowing, from .env, never used, stale >30d — each carrying a live count. Chips narrow: ticking two shows the rows matching both. They compose with the filter box and its key:value qualifiers, and / jumps to that box from anywhere on the page.

Sorting offers name, last used, most used, exposure and newest. Exposure floats the risky rows up: agent-readable counts double, auto-inject counts once.

Selecting rows

Select in the toolbar turns on checkboxes. Click a row to tick it, Shift-click to extend a range, or use the header checkbox to take everything currently shown — which is what makes the chips useful: filter to agent-readable, select all, revoke.

A partial run reports as partial: the toast reads 7 ok, 2 failed and names the first failure, rather than claiming nine successes. Every mutation is logged to the ledger by (scope, project, name) — a name alone is ambiguous when the same name legitimately lives in the global vault and in several projects at once.

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.

Usage history (v2.88.0)

Every time a value leaves the vault — an env_creds injection, a {{cred:NAME}} expansion, a gated reveal, a terminal c3 creds get --show — one event is appended to the owning scope's .c3/cred_usage.jsonl: timestamp, name (and field for structured entries), action, surface, project, exit code, and the command in its raw template form, capped at 120 characters. Never the expanded string, never a value. A global credential's usage from every project lands in ~/.c3, so its history is complete in one place.

Reading it back:

• UI — the Credentials tab's usage sub-view (totals, per-credential counts by surface, expandable recent events) and the hub drawer's “Usage & relationships” section.
• CLI — c3 creds usage [NAME] [--limit N] [--json].
• Agent — c3_credentials(action='usage'). Scoped on purpose: the agent sees full events (including command previews) only for the current project; other projects' use of a shared global credential is reduced to counts, so one project's agent cannot read another's command lines through the vault. Your surfaces (UI/CLI) show everything.
• REST — GET /api/credentials/usage and GET /api/credentials/<name>/usage (hub: /api/projects/credentials/usage).

The log rotates at 512KB (one .1 generation retained), both filenames are vault-write-protected and gitignored, and the lightweight last_used/use_count counters you already see on list rows keep working exactly as before — they are the summary; this is the history.

Audit trail

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

The Audit view

Those two logs answer different halves of the same question and, until v2.95.0, nothing joined them: changes live in the activity log, uses live in .c3/cred_usage.jsonl. Credentials → Audit in the hub merges them into one timeline, newest first, and every credential list has its own Audit button scoped to that vault.

A project's timeline includes the global vault, because a shared credential used from a project records into ~/.c3 rather than the project — reading only the project would lose exactly the entries a shared secret generates. The cross-project view reads that shared vault once, not once per project.

From the terminal:

c3 creds audit                        # everything, newest first
c3 creds audit NPM_TOKEN              # one credential's whole history
c3 creds audit --kind change          # who changed what
c3 creds audit --action reveal        # every plaintext read
c3 creds audit --since 2026-08-01 --json

Or, for the change half alone, through the edit ledger:

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

Change rows come from the live activity log. Entries older than its last rotation are in the archive and are not merged into this view.

Troubleshooting