# 🛡️ agent-secrets
**Aegis for AI Agents** — Portable credential management with age encryption, session-scoped leases, and a killswitch.
[](https://golang.org)
[](LICENSE)
## Why?
AI agents need secrets: API keys, tokens, credentials. But giving an agent raw access to your password manager (and therefore all your passwords) is a terrible idea:
- **Exfiltration risk** — compromised agent leaks all credentials
- **No audit trail** — who accessed what, when?
- **No revocation** — can't cut off access without rotating everything
- **No rotation** — credentials sit forever, waiting to be compromised
**agent-secrets** fixes this with:
- 🔐 **Age encryption** — secrets never plaintext on disk
- ⏱️ **Session-scoped leases** — TTL-based access, auto-expires
- 🔄 **Auto-rotation hooks** — `gh auth refresh`, custom commands
- 🚨 **Multi-factor killswitch** — revoke all + rotate all + wipe
- 📋 **Append-only audit log** — every access recorded
## Installation
**One-liner (macOS, Linux, WSL):**
```bash
curl -fsSL https://raw.githubusercontent.com/joelhooks/agent-secrets/main/install.sh | bash
```
**Or clone and install manually:**
```bash
git clone https://github.com/joelhooks/agent-secrets
cd agent-secrets
make build
sudo mv secrets /usr/local/bin/
```
**Or with Go:**
```bash
go install github.com/joelhooks/agent-secrets/cmd/secrets@latest
```
**Add the OpenClaw skill (teaches your agent how to use it):**
```bash
npx openclaw skills add https://github.com/joelhooks/agent-secrets
```
**Verify (self-documenting root command):**
```bash
secrets
```
## Quick Start
```bash
# 1) Initialize store and start daemon (one-time setup)
secrets init
secrets serve &
# 2) Add secrets
secrets add github_token --rotate-via "gh auth refresh"
secrets add anthropic_key
echo "sk-ant-..." | secrets add openai_key
# 3) Discover commands and available secrets
secrets
secrets list
# 4) Lease a secret (default output is raw value, ideal for exports)
export GITHUB_TOKEN=$(secrets lease github_token)
# 5) Request JSON envelope when you need metadata + next actions
secrets lease github_token --json
# 6) Inspect state and logs
secrets status
secrets audit --tail 20
# 7) Emergency killswitch
secrets revoke --all
```
> **Note:** The daemon must be running for most commands to work. The install script auto-starts it, but if you see "daemon not running" errors, run `secrets serve &`.
## Migration Guide: v0.4.x -> v0.5.x
`v0.5.x` keeps compatibility with older scripts while moving to JSON-first behavior.
- `secrets lease <name>` now defaults to raw value output. `--raw` still works as a hidden deprecated no-op and prints a warning to `stderr`. Remove it from scripts before `v0.6.0`.
- `--human` and `--output` are restored as hidden deprecated global flags. They are no-ops and print warnings to `stderr`. Remove them before `v0.6.0`.
- JSON envelopes now include both `ok` and `success` for one version cycle. They carry the same boolean value.
## JSON Envelope Pattern
All commands return a JSON response envelope with `ok`, `success`, `command`, `result`, and `next_actions`, except `secrets lease <name>` which returns only the raw secret value by default.
```bash
# Root command returns command tree
secrets
```
```json
{
"ok": true,
"command": "secrets",
"result": {
"description": "Portable credential management for AI agents",
"version": "dev",
"commands": [
{"name": "init", "description": "Initialize the secrets store", "usage": "secrets init"},
{"name": "list", "description": "List stored secret names", "usage": "secrets list"},
{"name": "lease", "description": "Get a secret value (raw by default)", "usage": "secrets lease <name> [--ttl 1h] [--client-id agent-x] [--json]"}
]
},
"next_actions": [
{"command": "secrets status", "description": "Check daemon status"}
]
}
```
```bash
# Lease envelope (opt in)
secrets lease github_token --json
```
```json
{
"ok": true,
"command": "secrets lease",
"result": {
"lease_id": "lease-123",
"secret_name": "github_token",
"value": "ghp_xxx",
"expires_at": "2026-02-19T12:00:00Z",
"ttl": "1h",
"client_id": "my-agent"
},
"next_actions": [
{"command": "export GITHUB_TOKEN=$(secrets lease github_token)", "description": "Export to environment"},
{"command": "secrets revoke lease-123", "description": "Revoke this lease"}
]
}
```
```json
{
"ok": false,
"command": "secrets lease",
"error": {
"message": "failed to acquire lease: ... secret not found",
"code": "generic_error"
},
"fix": "Check available secrets: secrets status"
}
```
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ CLI (cobra) │
│ init | add | lease | revoke | audit | status | daemon │
└─────────────────────────┬───────────────────────────────────┘
│ Unix Socket (JSON-RPC)
┌─────────────────────────▼───────────────────────────────────┐
│ Daemon Process │
│ ~/.agent-secrets/agent-secrets.sock │
└─────┬─────────┬─────────┬─────────┬─────────┬───────────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐
│ Store │ │ Lease │ │ Audit │ │Rotation │ │ Killswitch │
│ (age) │ │ Manager │ │ Log │ │ Hooks │ │ +Heartbeat │
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────────┘
```
## Commands
### `secrets`
Show a self-documenting command tree for agent discovery.
```bash
secrets
```
### `secrets init`
Initialize the encrypted store. Creates:
- `~/.agent-secrets/identity.age` — X25519 private key
- `~/.agent-secrets/secrets.age` — encrypted secrets
- `~/.agent-secrets/config.json` — configuration
### `secrets add <name>`
Add a secret to the store.
```bash
# Interactive (prompts for value)
secrets add my_secret
# With rotation hook
secrets add github_token --rotate-via "gh auth refresh"
# Pipe value from stdin
echo "secret-value" | secrets add api_key
cat credentials.txt | secrets add service_account
```
### `secrets list`
List stored secret names and lease-related metadata for discovery.
```bash
secrets list
```
### `secrets lease <name>`
Acquire a time-bounded lease on a secret.
- Default output: **raw secret value only** (best for shell exports)
- `--json`: full envelope with lease metadata and `next_actions`
```bash
# Primary pattern: raw value for shell export
export TOKEN=$(secrets lease github_token)
# Custom TTL
export TOKEN=$(secrets lease github_token --ttl 30m)
# Custom client ID (for audit)
export TOKEN=$(secrets lease github_token --client-id "my-agent")
# JSON envelope for agents
secrets lease github_token --json
```
### `secrets revoke [lease-id]`
Revoke access.
```bash
# Revoke specific lease
secrets revoke abc123
# KILLSWITCH: Revoke ALL active leases
secrets revoke --all
```
### `secrets audit`
View the append-only audit log.
```bash
# Last 50 entries (default)
secrets audit
# Last 100 entries
secrets audit --tail 100
```
### `secrets status`
Show daemon status.
```bash
secrets status
```
```json
{
"ok": true,
"command": "secrets status",
"result": {
"running": true,
"secrets_count": 5,
"active_leases": 2,
"started_at": "2026-02-19T10:30:00Z",
"uptime": "1h 15m"
},
"next_actions": [
{"command": "secrets lease <name>", "description": "Get a secret value"}
]
}
```
### `secrets daemon restart`
Gracefully restart a daemon managed by launchd, systemd, or another `KeepAlive` supervisor.
```bash
secrets daemon restart
```
The command requests shutdown over the authenticated Unix socket, then waits for a fresh daemon instance. If the daemon cannot answer RPC, use the host's restricted break-glass service restart.
For macOS scheduling, stall diagnosis, and safe launchd configuration reloads, see [Daemon operations](docs/daemon-operations.md). Credential RPCs serving interactive clients should use `ProcessType=Interactive`, not `Background`. A plist reload must wait for the old job's removal before bootstrap.
### `secrets env`
Generate `.env` file from `.secrets.json` config. Perfect for agentic workflows where secrets need to be loaded into a project environment.
```bash
# Generate .env from .secrets.json in current directory
secrets env
# Force overwrite existing .env
secrets env --force
```
**How it works:**
1. Reads `.secrets.json` from current directory
2. Acquires leases for each secret listed
3. Writes `KEY=value` pairs to `.env` file
4. Sets restrictive permissions (0600)
**Example `.secrets.json`:**
```json
{
"secrets": [
{
"name": "github_token",
"env_var": "GITHUB_TOKEN"
},
{
"name": "anthropic_key",
"env_var": "ANTHROPIC_API_KEY"
},
{
"name": "openai_key",
"env_var": "OPENAI_API_KEY",
"ttl": "30m"
}
],
"client_id": "my-project"
}
```
**Schema:**
- `secrets` (required): Array of secret mappings
- `name` (required): Secret name in agent-secrets store
- `env_var` (required): Environment variable name for .env file
- `ttl` (optional): Custom TTL for this secret (default: 1h)
- `client_id` (optional): Custom client ID for audit trail (default: auto-generated)
### `secrets exec`
Run a command with secrets loaded as environment variables. Combines `secrets env` + command execution + automatic cleanup.
```bash
# Run command with secrets loaded
secrets exec -- npm run dev
# Run tests with credentials
secrets exec -- pytest tests/
# Execute shell script
secrets exec -- ./deploy.sh
# Chain multiple commands
secrets exec -- sh -c "npm install && npm test"
```
**What it does:**
1. Generates temporary `.env` file from `.secrets.json`
2. Executes command with environment loaded
3. Cleans up `.env` file when command exits (even on error)
### `secrets cleanup`
Remove expired lease environment files. Run this to clean up stale `.env` files when leases have expired.
```bash
# Remove all expired .env files
secrets cleanup
# Check what would be cleaned (dry-run)
secrets cleanup --dry-run
```
## Security Model
### Encryption
- All secrets encrypted at rest using [age](https://age-encryption.org/)
- X25519 key pair generated on init
- Identity file permissions: `0600`
### Leases
- Secrets **cannot** be accessed directly — must acquire a lease
- Leases have mandatory TTL (max 24h by default)
- Expired leases automatically cleaned up
- Background goroutine prunes expired leases
### Audit
- Every operation logged with timestamp
- Append-only format (JSONL)
- Logs: secret access, lease grants, revocations, rotations, killswitch events
### Killswitch
- `revoke --all` immediately invalidates all active leases
- Optional: rotate all secrets with hooks
- Optional: wipe entire store
- Optional: heartbeat monitor — auto-killswitch if remote endpoint goes down
## Configuration
Config stored at `~/.agent-secrets/config.json`:
```json
{
"directory": "/home/user/.agent-secrets",
"socket_path": "/home/user/.agent-secrets/agent-secrets.sock",
"socket_mode": "0600",
"socket_group": "",
"default_lease_ttl": "1h",
"max_lease_ttl": "24h",
"rotation_timeout": "30s",
"heartbeat": {
"enabled": false,
"url": "https://your-endpoint.com/heartbeat",
"interval": "1m",
"timeout": "10s",
"fail_action": {
"revoke_all": true,
"rotate_all": false,
"wipe_store": false
}
}
}
```
`secrets serve --config <path>` loads an explicit daemon config. A partial client config can point Joel's CLI at a service-owned socket without exposing the store:
```json
{
"socket_path": "/Users/Shared/joelclaw/run/agent-secrets.sock"
}
```
For service-account deployments, keep the store and age identity `0700`/`0600` under the service account. Grant clients access only through a dedicated group-owned socket such as mode `0660`. Do not use a broad group such as `staff`.
## Agent Integration
Once the CLI is installed globally (`secrets` in PATH), any AI agent with shell access can use it directly. For richer integration, install the skill documentation or platform plugins.
### Any Agent (Direct CLI)
Works out of the box with any agent that can run shell commands.
**Option 1: Direct lease (single secret)**
```bash
# Lease credentials for a task
export GITHUB_TOKEN=$(secrets lease github_token --ttl 1h --client-id "claude-refactor-123")
export ANTHROPIC_API_KEY=$(secrets lease anthropic_key --ttl 1h --client-id "claude-refactor-123")
# Check status
secrets status
# Revoke when done
secrets revoke --all
```
**Option 2: Project-based workflow (.secrets.json)**
```bash
# 1. Create .secrets.json in project root
cat > .secrets.json <<'EOF'
{
"secrets": [
{"name": "github_token", "env_var": "GITHUB_TOKEN"},
{"name": "anthropic_key", "env_var": "ANTHROPIC_API_KEY"},
{"name": "vercel_token", "env_var": "VERCEL_TOKEN", "ttl": "30m"}
],
"client_id": "project-deploy-task"
}
EOF
# 2. Generate .env with all secrets
secrets env
# 3. Work with credentials loaded
source .env
npm run deploy
# 4. Cleanup when done
secrets cleanup
```
**Option 3: One-shot execution**
```bash
# Run command with secrets, auto-cleanup
secrets exec -- npm run deploy
secrets exec -- pytest tests/integration
secrets exec -- ./scripts/sync-prod.sh
```
**Best practices:**
- Use descriptive `--client-id` values (task name, agent ID)
- Match TTL to expected task duration
- Revoke leases when task completes or errors
- Use `secrets exec` for one-shot commands (auto-cleanup)
- Use `.secrets.json` for multi-secret workflows
---
### Claude Code / OpenCode (Agent Skills)
Install the skill documentation so agents understand capabilities and usage patterns.
**Option 1: Global skills (recommended)**
```bash
# Install skill globally - available to all projects
mkdir -p ~/.claude/skills
cp -r agent-secrets/skills/secret-management ~/.claude/skills/
# For OpenCode
mkdir -p ~/.opencode/skills
cp -r agent-secrets/skills/secret-management ~/.opencode/skills/
```
**Option 2: Per-project skills**
```bash
# Add to a specific project
mkdir -p your-project/.claude/skills
cp -r agent-secrets/skills/secret-management your-project/.claude/skills/
```
Once installed, agents will discover the skill and know how to use the CLI:
```bash
secrets status
secrets lease github_token --ttl 1h --client-id "claude-session-123"
```
---
### OpenClaw Plugin
The repo includes a full OpenClaw plugin with registered tools.
**Installation**
Add to your OpenClaw config (`~/.openclaw/config.json`):
```json
{
"plugins": {
"load": {
"paths": ["~/path/to/agent-secrets"]
},
"entries": {
"agent-secrets": {
"enabled": true,
"config": {
"default_ttl": "1h",
"client_id_prefix": "openclaw"
}
}
}
}
}
```
The plugin assumes `secrets` is in your PATH. Override with `"cli_path": "/custom/path/secrets"` if needed.
**Registered Tools**
| Tool | Description | Optional |
|------|-------------|----------|
| `secrets_lease` | Acquire time-bounded credential | No |
| `secrets_status` | Check daemon and lease status | No |
| `secrets_revoke` | Revoke specific lease | No |
| `secrets_audit` | View audit log | No |
| `secrets_add` | Add new secret | Yes (allowlist) |
| `secrets_killswitch` | Emergency revoke all | Yes (allowlist) |
**Enabling optional tools** (dangerous operations require explicit allowlist):
```json
{
"agents": {
"list": [{
"id": "main",
"tools": {
"allow": ["secrets_add", "secrets_killswitch"]
}
}]
}
}
```
**Usage in OpenClaw:**
```
Agent: I need to access the GitHub token for this task.
[Tool: secrets_lease]
{
"name": "github_token",
"ttl": "30m",
"client_id": "openclaw-task-123"
}
→ Returns: ghp_xxxxxxxxxxxx
```
---
### Direct CLI Usage (Any Agent)
Any agent with shell access can use the CLI directly:
```bash
# In your agent's environment setup or task preamble
export GITHUB_TOKEN=$(secrets lease github_token --ttl 1h --client-id "my-agent")
export ANTHROPIC_API_KEY=$(secrets lease anthropic_key --ttl 1h --client-id "my-agent")
# Check what's available
secrets status
# When done or on error, revoke the lease
secrets revoke $LEASE_ID
```
**Best practices for agents:**
1. Use descriptive `--client-id` values (e.g., `"claude-refactor-auth-module"`)
2. Match TTL to expected task duration
3. Revoke leases when task completes
4. Use `secrets audit` to review access patterns
---
## Development
```bash
# Run tests
make test
# Run with coverage
make test-cover
# Build
make build
# Install to $GOPATH/bin
make install
# Lint
make lint
```
## Dependencies
- [filippo.io/age](https://github.com/FiloSottile/age) — Modern encryption
- [github.com/spf13/cobra](https://github.com/spf13/cobra) — CLI framework
- [github.com/google/uuid](https://github.com/google/uuid) — Lease IDs
## Inspiration
This project was inspired by [Alex Hillman's approach](https://x.com/alexhillman/status/2005334574973296911) to agent credential management — the insight that agents shouldn't be anywhere near ALL your passwords. Scoped, time-bounded, audited access with a killswitch.
## License
MIT — Use it, fork it, ship it.
---
*Built for agents that need secrets but shouldn't keep them.*