Swamp Vault Skill

Manage secure secret storage through swamp vaults. All commands support --json for machine-readable output.

Quick Reference

Repository Structure

Vaults use the dual-layer architecture:

• •Data directory (/.swamp/vault/) - Internal storage by vault type
• •Logical views (/vaults/) - Human-friendly symlinked directories

/vaults/{vault-name}/
  vault.yaml → ../.swamp/vault/{type}/{id}.yaml
  secrets/ → ../.swamp/secrets/{type}/{vault-name}/ (local_encryption only)

Vault Types

Two vault types are available:

local_encryption

Stores secrets encrypted locally using AES-GCM. Best for development and local workflows.

config:
  auto_generate: true # Generate encryption key automatically
  # OR
  ssh_key_path: "~/.ssh/id_rsa" # Use SSH key for encryption

aws

Integrates with AWS Secrets Manager. Best for production environments.

config:
  region: "us-east-1" # Required
  # profile: "default"  # Optional: AWS profile name

Create a Vault

swamp vault create local_encryption dev-secrets --json
swamp vault create aws prod-secrets --json

Output shape:

{
  "id": "abc-123",
  "name": "dev-secrets",
  "type": "local_encryption",
  "path": ".swamp/vault/local_encryption/abc-123.yaml"
}

After creation, edit the config if needed:

swamp vault edit dev-secrets

Store Secrets

swamp vault put dev-secrets API_KEY=sk-1234567890 --json
swamp vault put prod-secrets DB_PASSWORD=secret123 -f --json  # Skip confirmation

Output shape:

{
  "vault": "dev-secrets",
  "key": "API_KEY",
  "status": "stored"
}

Get a Secret

Retrieve a specific secret value from a vault.

swamp vault get dev-secrets API_KEY --json

Output shape:

{
  "vault": "dev-secrets",
  "key": "API_KEY",
  "value": "sk-1234567890"
}

Note: Use with caution. Secret values are sensitive and should not be logged or displayed unnecessarily.

List Secret Keys

Returns key names only (never values):

swamp vault list-keys dev-secrets --json

Output shape:

{
  "vault": "dev-secrets",
  "keys": ["API_KEY", "DB_PASSWORD"]
}

Vault Expressions

Access secrets in model inputs and workflows using CEL expressions:

attributes:
  apiKey: ${{ vault.get(dev-secrets, API_KEY) }}
  dbPassword: ${{ vault.get(prod-secrets, DB_PASSWORD) }}

Key rules:

• •Vault must exist before expression evaluation
• •Expressions are evaluated lazily at runtime
• •Failed lookups throw errors with helpful messages

Using Vaults in Workflows

For detailed workflow integration including the swamp/lets-get-sensitive model, see the swamp-workflow skill.

Quick syntax reference:

# In workflow step attributes
apiKey: ${{ vault.get(vault-name, secret-key) }}

# Environment-specific
prodToken: ${{ vault.get(prod-secrets, auth-token) }}
devToken: ${{ vault.get(dev-secrets, auth-token) }}

Security Best Practices

1. •Environment separation: Use different vaults for dev/staging/prod
2. •Never hardcode: Always use vault expressions for secrets
3. •Audit access: Monitor vault operations through logs
4. •Key rotation: Rotate secrets and encryption keys regularly

When to Use Other Skills

References

• •Examples: See references/examples.md for multi-vault setups, workflow usage, and migration patterns
• •Provider details: See references/providers.md for encryption and configuration details
• •Troubleshooting: See references/troubleshooting.md for common issues