Vault

vault

Keep your secrets encrypted. API keys, passwords, tokens -- locked in a vault that only you can open. Your AI agent gets secrets when it needs them, then forgets them.

Script: ./scripts/vault.sh Setup: ./scripts/setup.sh (run once, takes 30 seconds)

---

Setup

cd /path/to/skills/vault
./scripts/setup.sh

• Claude Code: copy this skill folder into .claude/skills/vault/
• Codex CLI: append this SKILL.md content to your project's root AGENTS.md

For the full installation walkthrough (prerequisites, verification, troubleshooting), see [references/installation-guide.md](references/installation-guide.md).

Staying Updated

This skill ships with an UPDATES.md changelog and UPDATE-GUIDE.md for your AI agent.

After installing, tell your agent: "Check UPDATES.md in the vault skill for any new features or changes."

When updating, tell your agent: "Read UPDATE-GUIDE.md and apply the latest changes from UPDATES.md."

Follow UPDATE-GUIDE.md so customized local files are diffed before any overwrite.

---

Why this matters

Right now, your secrets probably live in a .env file. Plain text. Anyone who can see your files -- a colleague, a stolen laptop, a backup that leaks, an AI agent that goes rogue -- reads every secret you have.

This vault encrypts them. Even if someone copies your entire hard drive, they can't read your secrets without your encryption key. And your AI agent only sees secrets for the instant it needs them -- they never sit in memory or get written to a file.

Before (plaintext .env):

OPENAI_API_KEY=sk-abc123-real-key-here      encrypt -> vault -> agent needs it -> decrypt to memory -> use -> forget`

---

## Quick Start

Three steps. That's it.

### 1. Run setup

```bash
cd path/to/this/skill
./scripts/setup.sh

This installs the encryption tools (if needed), creates your vault, and generates your encryption key. One command, done.

2. Add a secret

./scripts/vault.sh set MY_API_KEY "sk-your-actual-key"

3. Get it back

./scripts/vault.sh get MY_API_KEY

Your vault is working. Secrets are encrypted on disk, decrypted only when you ask for them.

---

Commands

VAULT="./scripts/vault.sh"

# Store a secret
$VAULT set API_KEY "sk-abc123"

# Retrieve a secret (outputs to stdout, no trailing newline)
$VAULT get API_KEY

# List all secret names (not their values)
$VAULT list

# Export all secrets to your current shell
eval "$($VAULT source)"

# Run a command with secrets injected as env vars
$VAULT exec node server.js

# Check that vault works
$VAULT verify

# Full health check (tools, permissions, encryption test)
$VAULT doctor

# First-time setup
$VAULT setup

# Help for any command
$VAULT get --help
$VAULT set --help
$VAULT exec --help
$VAULT doctor --help

Every command has --help. When something goes wrong, error messages tell you what happened and what to do.

---

For AI agents

This is the pattern for injecting secrets into AI agent workflows.

Pattern 1: Variable assignment

# Agent needs one secret for a specific command
export TOKEN=$(./scripts/vault.sh get MY_API_KEY)
curl -H "Authorization: Bearer $TOKEN" https://api.example.com
unset TOKEN

Pattern 2: Source all secrets

# Load everything into the current shell
eval "$(./scripts/vault.sh source)"
# Now all secrets are available as env vars
echo $MY_API_KEY  # available
echo $DATABASE_URL  # available

Pattern 3: Scoped execution

# Run a command with secrets -- they don't leak to the parent shell
./scripts/vault.sh exec python my_script.py
# Secrets are gone after the command finishes

Pattern 3 is the safest. Secrets exist only for the duration of the command. They don't linger in your shell's environment. Prefer this when possible.

Agent safety rules

• Never write secrets to files that get committed to git
• Never include secrets in prompts or logs
• Prefer vault.sh exec over eval "$(vault.sh source)" when possible
• After using eval source, clean up with unset for sensitive vars

---

Configuration

All paths are configurable via environment variables:

| Variable | Default | What it controls | |----------|---------|-----------------| | VAULT_DIR | ~/.shit | Where the vault lives | | VAULT_FILE | $VAULT_DIR/vault.enc.yaml | The encrypted secrets file | | SOPS_AGE_KEY_FILE | $VAULT_DIR/.age-identity | Your encryption key |

Customize the vault path. The default (~/.shit) is intentionally misleading -- it's an extra layer of obscurity on top of the real encryption. Pick something that makes sense for your setup. Some options:

# In your shell profile (~/.zshrc or ~/.bashrc):
export VAULT_DIR="$HOME/.config/vault"     # conventional
export VAULT_DIR="$HOME/.cache/.internal"   # hidden in cache
export VAULT_DIR="$HOME/.local/secrets"     # descriptive

Then re-run setup: VAULT_DIR="$HOME/.config/vault" ./scripts/setup.sh

---

How it works (under the hood)

Two tools do the heavy lifting:

• age -- Modern encryption. Creates a key pair (public + private). Your secrets are encrypted with the public key and can only be decrypted with the private key. No passwords to remember.
• sops -- Wraps age to encrypt individual fields in a YAML file. Each secret value is encrypted separately, but key names stay visible (so you can see what's in the vault without decrypting).

The vault directory looks like this:

~/.shit/                    chmod 700 (only you can access)
  .age-identity             Your encryption key (chmod 600)
  vault.enc.yaml            Your encrypted secrets
  .sops.yaml                Config telling sops which key to use

Key security facts:

• Secrets are encrypted with X25519 (the elliptic-curve key-exchange algorithm Signal uses)
• Decrypted values only exist in memory -- stdout, pipes, env vars
• Nothing writes plaintext to disk, ever
• The vault.sh script validates all input to prevent injection attacks
• File permissions are checked and auto-fixed on every operation

---

What this protects against (and what it doesn't)

Protected:

• Casual file browsing (encrypted, not readable)
• Accidental git commits (encrypted file is safe to commit, though not recommended)
• Laptop theft (encrypted without the key is useless)
• AI agent data exfiltration (secrets aren't in plaintext files)
• Plaintext exposure in logs or backups

NOT protected:

• Someone with access to your logged-in user account (they can run vault.sh)
• Physical access to your unlocked computer
• Malware running as your user (it can read the key file)
• Key compromise (if someone gets .age-identity, they get everything)

Bottom line: This is dramatically better than .env files. It's not a replacement for a dedicated secrets manager in production infrastructure (use HashiCorp Vault, AWS Secrets Manager, etc. for that). It's for your development machine, your personal API keys, your local credentials.

---

Error Handling

| Problem | Solution | |---------|----------| | sops not found | brew install sops (Mac) or see sops install guide | | age not found | brew install age (Mac) or see age install guide | | jq not found | brew install jq (Mac) or sudo apt install jq (Linux) | | Age identity not found | Run ./scripts/setup.sh to create it | | Vault decrypted but no secrets found | Normal for a fresh vault -- add a secret with vault.sh set | | Failed to set key | Check that key name uses only letters, digits, and underscores | | Key not found | Run vault.sh list to see available keys | | Permission denied | Run vault.sh doctor to check and fix permissions | | Everything broken | Run vault.sh doctor -- it checks everything and tells you what's wrong |

---

Anti-Patterns

| Do NOT | Do instead | |--------|------------| | Store secrets in .env plaintext files | Store secrets with ./scripts/vault.sh set ... | | Leave secrets exported in shell for long sessions | Prefer ./scripts/vault.sh exec for scoped access | | Print secrets to logs or command history | Use env vars and avoid echoing secret values | | Commit decrypted outputs or temp files | Keep secrets encrypted at rest and out of git | | Skip vault.sh doctor when setup fails | Run vault.sh doctor first, then fix reported issues |

---

Bundled Resources Index

| Path | What | When to load | |------|------|-------------| | ./references/installation-guide.md | Detailed install walkthrough for Claude Code and Codex CLI | First-time setup or environment repair | | ./scripts/vault.sh | Vault CLI -- the main interface | Always | | ./scripts/setup.sh | First-time setup script | Initial setup only |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: buildoak
• Source: buildoak/fieldwork-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.