agentsecrets-cli 1.1.2

AI-native zero-knowledge secrets manager

AgentSecrets

Zero-knowledge secrets infrastructure built for AI agents to operate, not just consume.

Every other secrets tool was built for humans to provision credentials to agents. AgentSecrets was built for agents to manage credentials themselves — without ever seeing a single value.

Official Website | Engineering Blog Series

---

Package rename notice The agentsecrets PyPI package is now the AgentSecrets SDK — for developers building tools and agents on AgentSecrets infrastructure. This CLI wrapper is now agentsecrets-cli. If you previously installed pip install agentsecrets for CLI access, run:

pip install agentsecrets-cli

The agentsecrets CLI command itself is unchanged. Only the PyPI package name changed.

---

What This Is

Most secrets tools treat AI agents as consumers — something that receives a credential and uses it. AgentSecrets treats the agent as an operator.

Your agent checks its own status. Notices a secret is out of sync. Pulls the latest from the cloud. Makes the authenticated API call. Audits what it did. All of this without ever knowing a single credential value.

# An AI agent managing its own secrets workflow autonomously

agentsecrets status               # what workspace, project, environment, last sync?
agentsecrets secrets diff         # anything out of sync?
agentsecrets secrets pull         # sync from cloud to keychain
agentsecrets secrets list         # what keys are available?
agentsecrets call \
  --url https://api.stripe.com/v1/balance \
  --bearer STRIPE_KEY             # make the authenticated call
agentsecrets proxy logs           # audit what just happened

The agent ran the entire credentials workflow. It never saw sk_live_51H.... Not at any step.

This is what it means to be built for the agentic era — not bolted onto it.

---

The Problem With Every Other Approach

Traditional vaults protect credentials at rest. Once an agent retrieves a key to use it, that key is in agent memory. That's where it gets vulnerable.

Vault → agent retrieves sk_live_51H... → key is in agent memory
                                        → prompt injection can reach it
                                        → malicious plugin can reach it  
                                        → CVE can expose it

AgentSecrets never puts the value in agent memory. The proxy resolves from the OS keychain and injects at the transport layer. The agent makes the call. It sees only the response.

AgentSecrets → agent says "use STRIPE_KEY" → proxy resolves from OS keychain
                                           → injects into HTTP request
                                           → returns API response only
                                           → value never entered agent context

You cannot steal what was never there.

---

Installation

pip install agentsecrets-cli

Or install the full binary directly — recommended for production use:

# Homebrew (macOS / Linux)
brew install the-17/tap/agentsecrets

# npm
npm install -g @the-17/agentsecrets

# pip
pip install agentsecrets-cli

---

Quick Start

# Set up your account (first time) or initialise a new project (returning user)
agentsecrets init

# Create a project
agentsecrets project create my-app

# Store credentials — values go to OS keychain, never to disk
agentsecrets secrets set STRIPE_KEY=sk_live_51H...
agentsecrets secrets set OPENAI_KEY=sk-proj-...
agentsecrets secrets set DATABASE_URL=postgresql://...

# Or push your existing .env all at once
agentsecrets secrets push

# Authorize the domains your agents can reach
agentsecrets workspace allowlist add api.stripe.com api.openai.com

# Connect your AI tool
agentsecrets mcp install               # Claude Desktop + Cursor
agentsecrets proxy start               # Any agent via HTTP
openclaw skill install agentsecrets    # OpenClaw

# Or inject secrets as env vars into any Python process
agentsecrets env -- python manage.py runserver
agentsecrets env -- celery -A myapp worker
agentsecrets env -- pytest

Your agent now has full API access. It will never see a credential value.

---

The Agent Workflow

This is what AgentSecrets looks like when an AI agent is operating it end to end.

Check status

agentsecrets status
# Logged in as: [e-mail]
# Workspace:    Acme Engineering
# Project:      payments-service
# Environment:  development
# Last pull:    2 minutes ago

Notice drift and sync

agentsecrets secrets diff
# LOCAL ONLY:  PAYSTACK_KEY
# REMOTE ONLY: SENDGRID_KEY
# OUT OF SYNC: STRIPE_KEY (remote is newer)

agentsecrets secrets pull
# Synced 3 secrets from cloud to OS keychain

Make authenticated calls

agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY
# {"object":"balance","available":[{"amount":420000,"currency":"usd"}]}

Audit what happened

agentsecrets proxy logs --last 10
# 14:23:01  GET  api.stripe.com/v1/balance   STRIPE_KEY  200  245ms
# 14:31:15  POST api.stripe.com/v1/charges   STRIPE_KEY  200  412ms
# 14:31:16  POST api.openai.com/v1/chat/...  OPENAI_KEY  200  1203ms

The agent managed the complete credentials lifecycle. No human touched the workflow. No credential value was exposed at any step.

---

Zero-Knowledge Architecture

AgentSecrets is zero-knowledge at every layer — not just at the point of API injection.

Step	What the agent sees
secrets list	Key names only
secrets diff	Key names and sync status
secrets pull	Confirmation message — values go to OS keychain
agentsecrets call	API response only
agentsecrets env	Injects values into child process — agent never sees them
proxy logs	Key names, endpoints, status codes

The log struct has no value field. It is structurally impossible to accidentally log a credential value anywhere in the system.

Zero-Trust Proxy Enforcement

AgentSecrets enforces a deny-by-default security posture on every proxied request.

Domain Allowlist: Every outbound request must target a domain explicitly authorized in your workspace allowlist. If an agent attempts to hit an unauthorized domain, whether through prompt injection, SSRF, or misconfiguration, the proxy blocks the request with 403 Forbidden and logs the attempt.

# Authorize domains (supports multiple at once)
agentsecrets workspace allowlist add api.stripe.com api.openai.com

# Review allowed domains
agentsecrets workspace allowlist list

# View blocked attempts
agentsecrets workspace allowlist log

Allowlist modifications require admin role and password verification. Non-admins cannot change what domains agents can reach.

Response Body Redaction: If an external API echoes back the injected credential in its response body, the proxy automatically replaces the value with [REDACTED_BY_AGENTSECRETS] before the response reaches the agent. This prevents credential echo exfiltration — a class of attack where a malicious API is designed to reflect secrets back into agent context.

agentsecrets proxy logs --last 5
# 14:23:01  * OK (REDACTED)  GET  httpbin.org/headers  STRIPE_KEY  bearer  200  credential_echo  245ms

Role Management

agentsecrets workspace promote [e-mail]   # Grant admin role
agentsecrets workspace demote [e-mail]    # Revoke admin role

Encryption

Layer	Implementation
Key exchange	X25519 (NaCl SealedBox)
Secret encryption	AES-256-GCM
Key derivation	Argon2id
Key storage	OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
Transport	HTTPS / TLS
Server	Stores encrypted blobs only — cannot decrypt
Proxy	Session token, SSRF protection, redirect stripping

---

Team Workspaces

AgentSecrets is built for teams. A workspace is a shared environment — teammates join and get access to projects within it. Secrets are encrypted client-side before upload. The server cannot decrypt them.

# Create workspace
agentsecrets workspace create "Acme Engineering"

# Invite teammates
agentsecrets workspace invite [e-mail]
agentsecrets workspace invite [e-mail]

# Partition by service
agentsecrets project create payments-service
agentsecrets project create auth-service
agentsecrets project create data-pipeline

New developer onboards:

agentsecrets login
agentsecrets workspace switch "Acme Engineering"
agentsecrets project use payments-service
agentsecrets secrets pull
# Ready. No credential sharing. No .env files sent over Slack.

Every AI agent every teammate runs has access to the credentials it needs. None of them ever see the values.

---

The Credential Proxy

AgentSecrets runs a local HTTP proxy on localhost:8765. Agents send requests with injection headers. The proxy resolves from the OS keychain, injects into the outbound request, returns only the response.

6 Auth Styles

# Bearer token (Stripe, OpenAI, GitHub, most modern APIs)
agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY

# Custom header (SendGrid, Twilio, API Gateway)
agentsecrets call --url https://api.sendgrid.com/v3/mail/send \
  --header X-Api-Key=SENDGRID_KEY

# Query parameter (Google Maps, weather APIs)
agentsecrets call --url "https://maps.googleapis.com/maps/api/geocode/json" \
  --query key=GMAP_KEY

# Basic auth (Jira, legacy REST APIs)
agentsecrets call --url https://jira.example.com/rest/api/2/issue \
  --basic JIRA_CREDS

# JSON body injection
agentsecrets call --url https://api.example.com/auth \
  --body-field client_secret=SECRET

# Form field injection
agentsecrets call --url https://oauth.example.com/token \
  --form-field api_key=KEY

---

AI Tool Integrations

Claude Desktop + Cursor (MCP)

agentsecrets mcp install

Auto-configures your MCP setup. No credential values in any config file.

{
  "mcpServers": {
    "agentsecrets": {
      "command": "/usr/local/bin/agentsecrets",
      "args": ["mcp", "serve"]
    }
  }
}

OpenClaw (Skill + Exec Provider)

openclaw skill install agentsecrets

AgentSecrets ships as both a ClawHub skill and a native exec provider for OpenClaw's SecretRef system (shipped in v2026.2.26). The agent manages the full secrets workflow autonomously within OpenClaw.

Any AI Assistant (Workflow File)

agentsecrets init creates .agent/workflows/agentsecrets.md — a workflow file that teaches any AI assistant how to use AgentSecrets automatically. Claude, Gemini, Copilot, or any tool that reads workflow files picks it up without configuration.

Environment Variable Injection

For tools that manage their own credential storage (Stripe CLI) or SDKs that read from environment variables:

# Wrap any command — secrets injected as env vars
agentsecrets env -- python manage.py runserver
agentsecrets env -- celery -A myapp worker
agentsecrets env -- pytest

Values exist only in the child process memory. Nothing is written to disk. When the process exits, the secrets are gone.

Claude Desktop config (wrapping native Stripe MCP):

{
  "mcpServers": {
    "stripe": {
      "command": "agentsecrets",
      "args": ["env", "--", "stripe", "mcp"]
    }
  }
}

HTTP Proxy (Any Agent or Framework)

agentsecrets proxy start

curl http://localhost:8765/proxy \
  -H "X-AS-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-AS-Inject-Bearer: STRIPE_KEY"

Works with LangChain, CrewAI, AutoGen, and any agent that makes HTTP requests.

---

Build on AgentSecrets

The AgentSecrets SDK lets you build tools, MCP servers, and AI agents where credential values never enter your code — or the code of anyone using what you build.

pip install agentsecrets

from agentsecrets import AgentSecrets

as_client = AgentSecrets()

response = as_client.call(
    url="https://api.stripe.com/v1/balance",
    bearer="STRIPE_KEY"
)

You pass a key name. The SDK resolves from the OS keychain, injects at the transport layer, returns only the API response. Every user of every tool built on the SDK gets zero-knowledge credential management automatically.

Built on the SDK:

• Zero-Knowledge MCP Server Template — scaffold for building MCP servers with zero credential storage
• AgentSecrets for LangChain — zero-knowledge API calls in any LangChain agent (coming soon)
• AgentSecrets JS SDK — JavaScript/Node.js SDK (coming soon)

---

Full Command Reference

Account

agentsecrets init                    # Set up account or initialise a new project
agentsecrets login                   # Login to existing account
agentsecrets logout                  # Clear session
agentsecrets status                  # Current user, workspace, project, environment, last sync

Workspaces

agentsecrets workspace create "Name"       # Create workspace
agentsecrets workspace list                # List workspaces
agentsecrets workspace switch "Name"       # Switch active workspace
agentsecrets workspace invite user@email   # Invite teammate

Projects

agentsecrets project create my-app        # Create project
agentsecrets project list                 # List projects in current workspace
agentsecrets project use my-app           # Set active project
agentsecrets project update my-app        # Update project
agentsecrets project delete my-app        # Delete project

Environments

agentsecrets environment switch <name>        # Switch active environment (development, staging, production)
agentsecrets environment list                 # List all environments and secret counts
agentsecrets environment copy <from> <to>     # Copy all secrets from one env to another
agentsecrets environment merge <from> <to>    # Merge secrets and prompt for new values
agentsecrets environment clean                # Delete all secrets in current environment

Secrets

agentsecrets secrets set KEY=value        # Store a secret
agentsecrets secrets get KEY              # Retrieve a value (you see it, agent doesn't)
agentsecrets secrets list                 # List key names — never values
agentsecrets secrets push                 # Upload .env to cloud (encrypted)
agentsecrets secrets pull                 # Download cloud secrets to keychain
agentsecrets secrets delete KEY           # Remove a secret
agentsecrets secrets diff                 # Compare local vs cloud active environment
agentsecrets secrets diff --from X --to Y # Compare two environments directly

Proxy & Calls

agentsecrets call --url <URL> --bearer KEY    # One-shot authenticated call
agentsecrets proxy start [--port 8765]        # Start HTTP proxy
agentsecrets proxy status                     # Check proxy status & revocation list
agentsecrets proxy sync                       # Force background revocation sync
agentsecrets proxy logs [--last N] [--watch]  # View or stream local audit trail
agentsecrets exec                             # OpenClaw exec provider (reads stdin)
agentsecrets mcp serve                        # Start MCP server
agentsecrets mcp install                      # Auto-configure AI tools

Logging & Audit

agentsecrets log list [--tail]               # View or stream global backend logs
agentsecrets log export --format csv         # Export global logs to CSV/JSON
agentsecrets log summary                     # View global statistics and usage metrics
agentsecrets log detail <id>                 # Inspect a specific request deeply

Agent Identity

agentsecrets agent list                      # List AI agents attached to workspace
agentsecrets agent delete <name>             # Delete agent & safely cascade-revoke tokens
agentsecrets agent token issue <name>        # Generate a new session key for an AI
agentsecrets agent token list <name>         # See all active tokens for an agent
agentsecrets agent token revoke <id> --agent="<name>" # Revoke a specific identity token

Environment Injection

agentsecrets env -- <command> [args...]       # Inject secrets as env vars into child process
agentsecrets env -- python manage.py migrate  # Wrap Django
agentsecrets env -- celery -A app worker      # Wrap Celery
agentsecrets env -- pytest                    # Wrap Pytest

Workspace Security

agentsecrets workspace allowlist add <domain> [domain...]  # Authorize domains
agentsecrets workspace allowlist list                      # List allowed domains
agentsecrets workspace allowlist log                       # View allowlist audit log
agentsecrets workspace promote [e-mail]              # Grant admin role
agentsecrets workspace demote [e-mail]               # Revoke admin role

---

vs. Traditional Secrets Management

	AgentSecrets	HashiCorp Vault	AWS Secrets Manager	Doppler	1Password
Agent as operator	✅ Full lifecycle	❌ Consumer only	❌ Consumer only	❌ Consumer only	❌ Consumer only
Zero-knowledge end to end	✅ Every step	❌ Agent retrieves value	❌ Agent retrieves value	❌ Agent retrieves value	⚠️ Partial
Domain allowlist enforcement	✅ Deny-by-default	❌	❌	❌	❌
Response body redaction	✅ Echo exfiltration defense	❌	❌	❌	❌
Prompt injection protection	✅ Structural	❌	❌	❌	❌
Environment support (dev/staging/prod)	✅ Built-in	⚠️ Manual	⚠️ Manual	✅	⚠️ Manual
Env var injection (run --)	✅ agentsecrets env	❌	❌	✅ doppler run	✅ op run
AI-native workflow	✅ Built for it	❌	❌	❌	❌
SDK for building on top	✅	❌	❌	❌	❌
Team workspaces	✅ Built-in	⚠️ Complex	⚠️ IAM roles	✅	✅ Vaults
OS keychain storage	✅	❌	❌	❌	✅
Setup time	⚡ 1 minute	⏱️ Hours	⏱️ 30+ min	⏱️ 10 min	⏱️ 5 min
Free	✅	✅ OSS	⚠️ AWS costs	⚠️ Limited	❌

---

Use Cases

Solo Developer

agentsecrets init
agentsecrets secrets set STRIPE_KEY=sk_live_...
agentsecrets mcp install
# Ask Claude to check your Stripe balance. It manages the call. Never sees the key.

Team Onboarding

agentsecrets login
agentsecrets workspace switch "Acme Engineering"
agentsecrets project use payments-service
agentsecrets secrets pull
# Ready. No credential sharing. No .env files sent over Slack.

Autonomous Agent Deployment

# Agent handles this entire flow without human intervention
agentsecrets secrets diff                    # checks for drift
agentsecrets secrets pull                    # syncs if needed
agentsecrets environment switch production   # switch to production environment
agentsecrets secrets pull                    # pull production secrets
agentsecrets env -- python deploy.py
agentsecrets proxy logs                      # audits what happened

Incident Response at 2am

agentsecrets proxy start
# Claude queries logs, checks database state, calls APIs
# Full access. Zero credential exposure. Full audit trail.
# You debug. The agent never held your credentials.

---

Architecture

Built with Go for universal compatibility:

• Crypto: X25519 key exchange + AES-256-GCM encryption + Argon2id key derivation
• Keyring: OS keychain integration (macOS Keychain, Linux Secret Service, Windows Credential Manager)
• Proxy: Local HTTP server with session token, SSRF protection, redirect stripping
• Cloud: Zero-knowledge backend — stores ciphertext only, structurally cannot decrypt
• Distribution: Single binary, ~5-10MB, no runtime dependencies

See ARCHITECTURE.md and PROXY.md for deep dives.

---

Roadmap

• Core CLI
• Workspaces + Projects + Team invites
• Zero-knowledge cloud sync
• Credential proxy — 6 auth styles
• MCP server (Claude Desktop, Cursor)
• HTTP proxy server
• OpenClaw skill + exec provider
• Audit logging
• Multi-platform binaries (macOS, Linux, Windows)
• npm, pip, Homebrew distribution
• secrets diff
• Automatic JWT refresh
• Zero-trust domain allowlist enforcement
• Response body redaction (echo exfiltration defense)
• Workspace role management (promote/demote)
• agentsecrets env — environment variable injection
• Python SDK (pip install agentsecrets)
• Zero-Knowledge MCP Server Template
• Agent identity + token management
• Governance audit log
• Environment support (development / staging / production)
• AgentSecrets for LangChain
• AgentSecrets for CrewAI
• JavaScript / Node.js SDK
• Secret rotation
• Web dashboard
• Cloud resolver (serverless + production deployments)
• AgentSecrets Connect (multi-tenant credential delegation)

---

Security

Reporting vulnerabilities: do NOT open public issues. Email: [e-mail] — response within 24 hours.

---

Contributing

Found a bug? Open an issue Have an idea? Start a discussion Want to contribute? Check CONTRIBUTING.md

git clone https://github.com/The-17/agentsecrets
cd agentsecrets
go mod download
make build
make test

---

Links

• Website: agentsecrets.theseventeen.co
• Deep Dive: Building AgentSecrets (Engineering Blog)
• GitHub: github.com/The-17/agentsecrets
• SDK: github.com/The-17/agentsecrets-sdk
• ClawHub: clawhub.ai/SteppaCodes/agentsecrets
• Related: SecretsCLI — original Python implementation

---

License

MIT — see LICENSE

Built by The Seventeen

---

The agent operates it. The agent never sees it. ⭐