Vault

The Vault is AGH's encrypted store for daemon-managed secret material. Use it when AGH should own the value lifecycle instead of reading a value from the daemon process environment.

Ref Model

AGH accepts two secret ref families:

Ref family	Owner	Runtime behavior
`env:NAME`	Operator environment	AGH reads `NAME` from the daemon process environment when a runtime boundary needs it.
`vault:<namespace>/<path>`	AGH Vault	AGH stores the secret encrypted, resolves it only at internal launch/materialization boundaries, and redacts diagnostics.

Supported Vault namespaces are:

Namespace	Typical refs
`providers`	`vault:providers/openrouter/api-key`
`bridges`	`vault:bridges/brg_123/bot_token`
`automation`	`vault:automation/deploy-webhook/signing-secret`
`mcp`	`vault:mcp/github/env/GITHUB_TOKEN`, `vault:mcp/remote-docs/oauth/client-secret`
`hooks`	`vault:hooks/post-task/GITHUB_TOKEN`
`extensions`	`vault:extensions/slack/app-token`
`sandbox`	`vault:sandbox/daytona-dev/api-token`
`sessions`	`vault:sessions/sess_123/github-token`

Session Vault entries are normal Vault records under the sessions namespace. AGH filters them by the deterministic prefix vault:sessions/<session_id>/; there is no separate session-secret table.

Public Surfaces

Vault is agent-manageable through the same daemon surfaces as the rest of AGH:

Surface	Operations	Notes
CLI over UDS	`agh vault list`, `get`, `put`, `delete`	`put` accepts secret material only through `--value-stdin`.
HTTP API	`/api/vault/secrets` and `/api/vault/secrets/metadata`	Web UI and external local clients use these routes. HTTP Vault routes use the daemon's privileged loopback guard.
UDS API	Same route shapes as HTTP	CLI and local agents use the Unix domain socket surface.
Web UI	Settings > Vault	Lists metadata, filters by namespace or prefix, writes new values, and deletes refs.
Session inspector	Session Vault panel	Lists metadata for `vault:sessions/<session_id>/` refs.

The response shape is always redacted:

{
  "secret": {
    "ref": "vault:sessions/sess_123/github-token",
    "namespace": "sessions",
    "kind": "token",
    "present": true,
    "created_at": "2026-05-02T10:00:00Z",
    "updated_at": "2026-05-02T10:00:00Z"
  }
}

Fields such as secret_value, encrypted_value, tokens, and API keys are never returned by list, get, delete, settings read, CLI output, or web views.

CLI Usage

List all redacted metadata:

agh vault list

Filter by namespace:

agh vault list --namespace providers -o json

Filter one session:

agh vault list --prefix vault:sessions/sess_123/

Store a secret without putting it in shell history:

printf "%s" "$TOKEN" |
  agh vault put vault:sessions/sess_123/github-token --kind token --value-stdin

Read metadata for one ref:

agh vault get vault:sessions/sess_123/github-token

Delete one ref:

agh vault delete vault:sessions/sess_123/github-token

agh vault put intentionally does not have a --value flag. Passing secret values through argv can leak them through shell history or process inspection.

When --kind is omitted during rotation, AGH preserves the existing kind metadata for that ref.

API Usage

HTTP and UDS expose the same route model:

Method	Route	Purpose
`GET`	`/api/vault/secrets?prefix=&namespace=`	List redacted metadata.
`GET`	`/api/vault/secrets/metadata?ref=...`	Read redacted metadata for one ref.
`PUT`	`/api/vault/secrets`	Store or replace one write-only secret value.
`DELETE`	`/api/vault/secrets?ref=...`	Delete one ref.

Write request:

{
  "ref": "vault:sessions/sess_123/github-token",
  "kind": "token",
  "secret_value": "..."
}

The daemon validates the ref grammar, namespace, and non-empty secret_value. After a successful write it returns the persisted metadata row. The submitted value is registered with dynamic redaction before storage, then unregistered when the same ref is deleted or replaced.

HTTP Vault routes are intended for the local web UI and local integrations, so AGH applies the privileged loopback guard to metadata reads and mutations. Agents and local tools can use the UDS surface for the same route shapes without exposing the HTTP listener.

Web UI

Use Settings > Vault for global metadata inspection and write-only updates. The page supports:

namespace filtering
prefix filtering
create/update by ref
delete by ref
loading, empty, error, pending-write, and pending-delete states

Session pages include a Vault tab in the inspector. It shows only entries below vault:sessions/<session_id>/ and shortens the display label to the session-local suffix.

Operational Notes

AGH_VAULT_KEY can override the daemon-local Vault encryption key. When it is unset, AGH creates $AGH_HOME/vault.key with 0600 permissions the first time the Vault needs to encrypt or decrypt a secret.

Deleting a Vault ref removes the stored value. It does not rewrite existing configuration that still points at that ref, so dependent providers, bridges, MCP servers, hooks, automation triggers, sandbox profiles, or session-scoped consumers may report missing credentials until a new value is stored.

config.toml documents refs used by provider, MCP, automation, hook, extension, and sandbox configuration.
mcp.json documents MCP secret_env and OAuth client_secret_ref.
API Reference lists the Vault route family.
CLI Reference contains the generated agh vault command pages.