aivault

name	aivault
description	Complete guide for using aivault as a zero-trust local vault and proxy for API secrets. Use this skill when initializing or configuring aivault, managing secrets and credentials, invoking capability-backed API calls, setting workspace/group isolation, installing provider plugins such as Postgres, adding custom providers, or troubleshooting daemon and policy issues.

aivault Runtime And Integration

This skill covers secure setup and day-to-day use of aivault for agent workflows. The detailed reference files are generated from this repository's docs/ sources; update docs first, then run pnpm skills:sync.

Quick Reference

Resource	Path
CLI binary	aivault
Daemon binary	aivaultd
Vault root (default)	~/.aivault/data/vault/
Daemon socket (default)	~/.aivault/run/aivaultd.sock
Repo docs source	docs/
Generated skill refs	skills/aivault/references/

Default Workflow

1. Check status and provider setup:
   • aivault status
   • aivault provider list -v
2. Store secrets in the vault, not in agent-readable env files:
   • aivault secrets create --name OPENAI_API_KEY --value "sk-..." --scope global
3. Inspect available capabilities:
   • aivault capability list
   • aivault capability describe openai/chat-completions
4. Invoke through the policy boundary:
   • aivault invoke openai/chat-completions --body '{"model":"gpt-5.2","messages":[{"role":"user","content":"hello"}]}'
5. Verify audit trail:
   • aivault audit

Detailed References

Load only what is needed:

• references/getting-started.md - installation, first-run setup, and secure invocation flow.
• references/cli-reference.md - command groups and practical command patterns.
• references/provider-plugins.md - optional provider binaries, including Postgres setup and invocation.
• references/registry-custom-providers.md - built-in registry model, schema, and custom provider flow.
• references/security-and-isolation.md - zero-trust properties, scope resolution, encryption, audit, and threat boundaries.
• references/operations.md - daemon behavior, environment flags, storage layout, and testing commands.

Essential Patterns

Registry-backed secret provisioning

Use canonical secret names such as OPENAI_API_KEY so aivault can pin to a provider and auto-enable capabilities.

Capability-first invocation

Call aivault invoke <capability-id>, aivault json <capability-id>, or aivault markdown <capability-id> instead of direct upstream calls with raw keys.

Scoped tenancy controls

Use --scope workspace and --scope group for tenant isolation, then pass --workspace-id and --group-id on invoke.

Provider plugin activation

If a capability starts with a plugin namespace such as postgres/, check aivault provider list -v, then install and enable the official provider before configuring credentials:

aivault provider install postgres --enable

Custom provider fallback

Only create manual credentials and capabilities when a provider is not in the built-in registry or available as an official provider plugin.

Common Mistakes To Avoid

1. Storing API keys in .env for untrusted agent code.
2. Invoking raw URLs instead of declared capabilities.
3. Forgetting scope context when debugging credential resolution.
4. Assuming caller-provided auth headers are allowed; the broker owns auth headers.
5. Treating custom providers as equally tamper-resistant as compiled registry providers.
6. Importing database client libraries or reading DATABASE_URL in agent-owned code when postgres/* capabilities are available.

Maintenance

Run pnpm skills:sync after docs changes. Run pnpm skills:check in CI or before releases to ensure skills/aivault still matches docs/.