Bagman

Secure key management patterns for AI agents handling wallets, private keys, and secrets.

Bagman solves the three critical problems of agentic key management:

1. Key Loss — Agents forget credentials between sessions
2. Accidental Exposure — Keys leaked to GitHub, logs, or outputs
3. Prompt Injection — Malicious prompts extracting secrets

Quick Start

Choose Your Backend

Bagman supports multiple secret storage backends. No 1Password required.

Bagman auto-detects the best available backend.

Install

# Clone
git clone https://github.com/zscole/bagman-skill.git
cd bagman-skill

# Optional: Install backend dependencies
brew install age          # For encrypted file backend
brew install 1password-cli  # For 1Password backend

Usage

from examples.secret_manager import get_secret, get_session_key

# Auto-detects backend
api_key = get_secret("openai-key")

# With session metadata
creds = get_session_key("trading-bot")
if creds.is_expired():
    raise ValueError("Session expired")
    
print(f"Backend: {creds.backend}")
print(f"Expires: {creds.time_remaining()}")

Force Specific Backend

from examples.backends import get_backend

# Force macOS Keychain
backend = get_backend("keychain")

# Force 1Password
backend = get_backend("1password", vault="My-Vault")

# Force encrypted file
backend = get_backend("encrypted_file", path="~/.secrets.age")

# Force environment variables
backend = get_backend("env")

Or via environment variable:

export BAGMAN_BACKEND=keychain

---

Backends

macOS Keychain (Default on macOS)

Zero setup required. Uses native security CLI.

# Store secret
security add-generic-password -s bagman-agent -a my-key -w "secret-value"

# Or via Python
from examples.backends import get_backend
backend = get_backend("keychain")
backend.set("my-key", "secret-value")

1Password CLI

Rich metadata support (expiration, spending caps, allowed contracts).

# Setup
brew install 1password-cli
eval $(op signin)
op vault create "Agent-Credentials"

# Store with metadata
op item create \
  --vault "Agent-Credentials" \
  --category "API Credential" \
  --title "trading-bot-session" \
  --field "password=0xsession..." \
  --field "expires=2026-02-15T00:00:00Z" \
  --field "spending-cap=1000 USDC" \
  --field "allowed-contracts=0xDEX1,0xDEX2"

Encrypted File (age)

Portable encrypted JSON file. Works anywhere.

# Setup
brew install age

# Set passphrase
export BAGMAN_PASSPHRASE="your-passphrase"

# Or use identity file
age-keygen -o ~/.bagman/identity.txt

Secrets stored in ~/.bagman/secrets.age.

Environment Variables

Fallback that always works. Secrets prefixed with BAGMAN_.

export BAGMAN_TRADING_BOT_KEY="0x1234..."
export BAGMAN_OPENAI_KEY="sk-..."

key = get_secret("trading-bot-key")  # Reads BAGMAN_TRADING_BOT_KEY

---

Core Rules

---

Architecture

┌─────────────────────────────────────────────────────┐
│                   AI Agent                          │
├─────────────────────────────────────────────────────┤
│  Session Key (bounded)                              │
│  ├─ Expires after N hours                           │
│  ├─ Max spend per tx/day                            │
│  └─ Whitelist of allowed contracts/methods          │
├─────────────────────────────────────────────────────┤
│  Secret Manager (Auto-detect Backend)               │
│  ├─ macOS Keychain (native)                         │
│  ├─ 1Password CLI (rich metadata)                   │
│  ├─ Encrypted file (portable)                       │
│  └─ Environment vars (fallback)                     │
├─────────────────────────────────────────────────────┤
│  Smart Account (ERC-4337)                           │
│  ├─ Programmable permissions                        │
│  └─ Recovery without key exposure                   │
└─────────────────────────────────────────────────────┘

---

Files

---

For OpenClaw

# Install from ClawHub
clawhub install bagman

# Or copy to skills
cp -r openclaw/ ~/.openclaw/skills/bagman/

The skill auto-detects available backends. No 1Password required.

---

License

MIT