🔐 Credential Vault

---

name: credential-vault

description: "Encrypted credential storage for OpenClaw agents. Stop storing API keys in plaintext."

license: "MIT-0"

metadata:

openclaw:

emoji: "🔐"

requires:

bins: ["uv"]

primaryEnv: "VAULT_MASTER_PASSWORD"

---

# 🔐 Credential Vault

Encrypted credential storage for OpenClaw agents. Stop storing API keys in plaintext.

Overview

Credential Vault provides AES-256-GCM encrypted local storage for API keys, tokens, and other secrets. Instead of scattering credentials across `.env` files, centralize them in an encrypted vault with audit logging and expiry tracking.

Features

Installation

cd ~/ubik-collective/systems/ubik-pm/skills/credential-vault
uv sync

Quick Start

# Initialize vault (one-time setup)
uv run vault init

# Unlock vault
uv run vault unlock

# Add credentials
uv run vault add OPENAI_API_KEY "sk-..." --tag openai
uv run vault add TAVILY_API_KEY "tvly-..." --tag tavily --expires 2026-12-31

# List credentials
uv run vault list

# Get a credential
uv run vault get OPENAI_API_KEY

# Export for a skill
eval $(uv run vault env --tag tavily)

# Lock when done
uv run vault lock

Security Model

Encryption

Storage

Permissions

Threat Model

**Protects against:**

**Does NOT protect against:**

Usage Examples

See [EXAMPLE.md](./EXAMPLE.md) for detailed usage patterns.

Commands

`vault init`

Initialize a new vault with a master password.

`vault unlock`

Unlock the vault for the current session.

`vault lock`

Lock the vault and clear session key.

`vault status`

Show vault status (locked/unlocked, credential count).

`vault add KEY_NAME [VALUE] [--tag TAG] [--expires DATE]`

Add or update a credential. If VALUE is omitted, prompts securely.

`vault get KEY_NAME`

Retrieve and decrypt a credential.

`vault list [--tag TAG]`

List all credentials (values masked). Optionally filter by tag.

`vault remove KEY_NAME [-y]`

Remove a credential. Prompts for confirmation unless `-y` is passed.

`vault env [--tag TAG]`

Export credentials as `KEY=VALUE` for environment injection.

**Example:**

eval $(uv run vault env --tag openai)
echo $OPENAI_API_KEY  # Now available

`vault audit [--last N]`

View recent audit log entries.

`vault expiring [--days N]`

Check for credentials expiring within N days (default: 7).

`vault rotate KEY_NAME [NEW_VALUE]`

Replace a credential with a new value (preserves tags/metadata).

Integration with Skills

Pattern: Inject credentials before running a skill

# Tavily search skill
eval $(uv run vault env --tag tavily)
uv run scripts/search.py "OpenClaw release date"

Pattern: Skill checks vault directly

from lib.store import Store

store = Store()
# Assumes vault is unlocked by user beforehand
api_key = store.get("TAVILY_API_KEY")

Pattern: Auto-unlock in HEARTBEAT.md

# HEARTBEAT.md
Check if vault is locked. If so, prompt user to unlock before running daily checks.

Best Practices

1. **Use tags consistently** — Tag credentials by skill name for easy filtering

2. **Set expiry dates** — Track when API keys need rotation

3. **Lock when idle** — Run `vault lock` when not actively using credentials

4. **One vault per machine** — Don't sync the vault file across machines

5. **Rotate regularly** — Use `vault expiring` to track upcoming expirations

6. **Review audit logs** — Check `vault audit` periodically

Limitations

Troubleshooting

"Vault is locked"

Run `uv run vault unlock` and enter your master password.

"Incorrect master password"

Double-check your password. If forgotten, you'll need to reinitialize (losing all credentials).

"Vault not initialized"

Run `uv run vault init` to create a new vault.

Session key persists after reboot

Session file is cleared on `vault lock`, but not automatically on reboot. Run `vault lock` explicitly.

Development

Run tests

uv run pytest

Add a test

See `tests/test_roundtrip.py` for examples.

License

MIT-0 (public domain equivalent)