# End-to-end walkthrough
A complete run-through of Svault's AI-aware flow: create a vault, classify secrets
with descriptions, define callers, turn on the AI judge, and watch a real model
grant or deny agent requests. The judge outputs below are **actual responses** from
`google/gemini-2.5-flash` via OpenRouter.
> **Vaults are addressed by name.** You can keep several (local today, remote on the
> [roadmap](roadmap.md)). The `secret`, `get`, and `settings` commands take
> `-v <vault>`; `unlock` and `lock` take the name as a positional argument. Omit the
> name only when there's a single vault.
## 1. Build
```bash
git clone https://github.com/nim444/Svault.git
cd Svault && cargo build --release
alias svault="$PWD/target/release/svault"
```
## 2. Create a vault (with a description)
```bash
svault create
# Name: billing-api
# Description: production billing service ← the judge sees this
# Allow agents: list → claude-code, billing-worker
# Rate limit: 20/hour
# Default tier: medium
# Use AI judge: yes
# Master passphrase: ******** ← first run only; one secret unlocks every vault
# → prints a one-time RECOVERY CODE; save it.
```
The vault description is the overall context the judge sees. Storage is `local`
today. There is no per-vault passphrase — the first `create` sets a **master
passphrase** that unlocks every vault; later vaults reuse it.
## 3. Add secrets — classify them and say what they're for
`--description` records the secret's purpose. The judge weighs each request's
*reason* against it, so an off-purpose request is denied even when the caller and
scope check out.
```bash
svault secret add DATABASE_URL -v billing-api --scope database --tier medium \
--description "production Postgres connection string"
svault secret add STRIPE_KEY -v billing-api --scope payments --tier high --require-reason \
--description "production Stripe charge key — only for billing/charge flows"
```
Classification lives **AES-256-GCM encrypted inside `vault.enc`**. Without the vault
key, a same-UID process can neither read a tier, scope, or purpose at rest to plan a
passing request nor downgrade one. In the TUI, `a` in the secret browser opens the
same form (name / value / scope / description / tier / require-reason).
## 4. Define who may ask (callers)
Caller rules live encrypted in the vault as well, so there is no committable
`svault.policy.yaml`. Seed the defaults, then edit them in `svault settings`:
```bash
svault policy init # seed default callers into the vault's encrypted policy
svault policy check claude-code # what it can reach + recent activity (unlocks the vault)
```
Conceptually a vault's caller rules look like:
```yaml
callers:
claude-code:
scopes: [database, api]
rate_limit: 20/hour
billing-worker:
scopes: [payments]
rate_limit: 60/hour
default:
scopes: []
rate_limit: 5/hour
```
## 5. Turn on the AI judge
There is no plaintext config and no key file. Every judge — its model, thresholds,
free-text **criteria**, and its own API key — lives AES-256-GCM **encrypted** in the
keyring at `.svault/keyring.enc`, opened by your **master passphrase** (no separate
keyring passphrase). Create the keyring, add a named judge (with criteria and key),
enable the judge globally, then unlock once:
```bash
svault keyring init # create the keyring under your master (one-time)
svault judge add strict # prompts: model, thresholds, criteria, then the API key (hidden)
# Model: google/gemini-2.5-flash
# Allow threshold: 60
# High threshold: 80
# Criteria: Only allow billing-related reasons that name an invoice or charge.
# OpenRouter API key: sk-or-… (blank = fall back to $SVAULT_OPENROUTER_KEY)
svault judge enable # flip the global on/off switch (on)
svault keyring unlock # caches a 0600 session key so the judge is live this session
svault judge status
# keyring: unlocked
# judge (global): on default: strict
# strict google/gemini-2.5-flash allow 60 high 80 KEY set
```
The first judge you add becomes the keyring's **default**, which vaults with no
explicit assignment use. A vault opts in to the judge via its per-vault toggle (set
at `svault create` or in settings); the keyring's global switch and each judge's
criteria are managed here. Until the keyring is unlocked the judge stays off and the
static tier rules apply (high = human-only).
## 6. Dry-run the model — `svault judge test`
This builds a sample request and asks the live model; nothing is read or written.
Pass a realistic `--vault` (the model sees it) and the descriptions. The outputs
below are real model responses:
```bash
# Plausible reason that matches the vault → ALLOW
svault judge test --vault billing-api --vault-description "production billing service" \
--tier medium --scope database --secret DATABASE_URL \
--reason "run the nightly billing migration against the production database" --caller claude-code
# ALLOW score 95 — Nightly billing migration is a plausible and specific reason for
# accessing the production database URL, matching the vault's purpose.
# Vague reason → DENY
svault judge test --vault billing-api --tier medium --scope database --secret DATABASE_URL \
--reason "asdf" --caller claude-code
# DENY score 10 — Stated reason 'asdf' is vague and unspecific.
# Reason matches the secret's description → ALLOW
svault judge test --vault billing-api --tier high --scope payments --secret STRIPE_KEY \
--description "production Stripe charge key — only for billing/charge flows" \
--reason "charge a customer invoice for the monthly subscription" --caller billing-worker
# ALLOW score 95 — Caller is a billing worker, requesting a Stripe key for a billing-api
# vault to charge a customer invoice, which aligns perfectly with the
# secret's purpose.
# Reason contradicts the secret's description → DENY
svault judge test --vault billing-api --tier high --scope payments --secret STRIPE_KEY \
--description "production Stripe charge key — only for billing/charge flows" \
--reason "export the full customer email list for a marketing campaign" --caller billing-worker
# DENY score 90 — Stated reason does not match secret's purpose. STRIPE_KEY is for
# billing/charge flows, not exporting customer email lists.
```
The last two are the headline behavior: same secret, same caller, same tier — the
**reason versus the documented purpose** is what flips the decision.
## 7. The agent request — the gate from a shell
The canonical agent door is the **MCP server** (section 10). `svault get` runs the
identical gate from a shell and is shown here because it's the quickest way to see
the gate end-to-end — but it's **deprecated** (it prints a deprecation note to
stderr and will be removed), so new integrations should wire up MCP instead.
Unlock once (or run the [daemon](daemon.md) so the key stays in memory), then the
agent path runs the full gate — policy, then tier, then judge, then audit —
**enforced inside the daemon**.
```bash
svault daemon start
svault unlock billing-api
# Granted — reason fits the secret's purpose
svault get STRIPE_KEY -v billing-api --scope payments \
--reason "charge a customer invoice for the monthly subscription" --caller billing-worker
# → sk_live_... (value to stdout; a one-line granted: status to stderr)
# Denied — reason doesn't fit
svault get STRIPE_KEY -v billing-api --scope payments \
--reason "export the customer email list for marketing" --caller billing-worker
# → denied: request not authorized for this secret
# (exits non-zero; no value printed)
```
On allow, only the value goes to stdout, so an agent capturing stdout never sees the
rationale. On deny the caller gets a single **generic** message; the real reason
(judge score plus rationale, scope or caller mismatch, rate limit) is recorded only
in the audit log, so the agent can't hill-climb a denied request into a passing one.
## 8. Tiers and fail modes
| `low` | skipped (unless `require_reason`) | allow |
| `medium` | allow if score ≥ `allow_threshold` (60) | **fail-open**, audit-flagged `judge-unavailable` |
| `high` | allow if score ≥ `high_threshold` (80) | **fail-closed** (deny) |
With the judge **off** (keyring locked, global switch off, no resolved key, or the
vault opted out), the gate falls back to the static rule (high = human-only), so
nothing regresses. To verify fail-closed, edit a judge (`svault judge edit strict`)
to point its base URL at an unreachable host, then request a high-tier secret — it
denies.
## 9. Review the audit trail
Every decision is appended to `.svault/billing-api/audit.log` (gitignored, `0600`),
stamped with the **peer UID** of the connecting process (unforgeable, unlike the
self-asserted `--caller`) and the judge's score and rationale — never the secret
value.
```bash
svault policy check billing-worker # scopes, reachable secrets, recent allows/denials
```
## 10. Hand it to an agent over MCP
MCP is the canonical agent door. The same gate that the deprecated `svault get`
runs from a shell is exposed over the [Model Context Protocol](mcp.md), so an
MCP-aware agent (Claude Code, Cursor) requests secrets directly instead of reading
`.env` files.
The human unlocks once, then wires the server (or press `m`, then `w` in the TUI):
```bash
svault daemon start # keys live in memory (optional but recommended)
svault unlock billing-api # one master passphrase opens every vault
# .mcp.json (Claude Code / Cursor) — points the agent at the gated server
# {
# "mcpServers": {
# "svault": { "command": "svault", "args": ["mcp"],
# "env": { "SVAULT_CALLER": "claude-code" } }
# }
# }
```
Now the agent calls the `svault_get_secret` tool with `name` / `scope` / `reason`
— the request runs through the *same* policy + judge gate as section 7, audited
with `source = mcp`. A weak reason is denied with the generic message; a locked
vault tells the agent a human must run `svault unlock`; high-tier stays human-only.
The agent never sees the master passphrase. See [mcp.md](mcp.md) for the tools, the
security model, and a raw transcript.
## Notes
- **Key safety.** Each judge's OpenRouter key is stored AES-256-GCM encrypted in
`.svault/keyring.enc`, never in a plaintext file. A judge with no stored key falls
back to the opt-in `$SVAULT_OPENROUTER_KEY` environment variable. Rotate a key with
`svault judge set-key <name>` if it is ever exposed (for example, pasted into a chat
or a log).
- **What the judge sees.** Secret name, scope, tier, caller, reason, recent activity,
and any vault or secret descriptions — **never the secret value**. Keep descriptions
free of sensitive data, since they are sent to the model. See
[security.md](security.md#ai-judge).
- **Honest boundary.** Svault enforces the gate for cooperative or semi-trusted agents
and keeps a tamper-resistant audit trail. It is *not* a sandbox against a hostile
same-UID process, which can read the unlocked daemon's memory directly.
