Metadata-Version: 2.4
Name: agentsecrets-cli
Version: 1.1.1
Summary: AI-native zero-knowledge secrets manager
Author-email: The Seventeen <hello@theseventeen.co>
License-Expression: MIT
Keywords: agents,ai,cli,credentials,secrets,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?logo=go)](https://go.dev/)
[![ClawHub](https://img.shields.io/badge/ClawHub-agentsecrets-blue)](https://clawhub.ai/SteppaCodes/agentsecrets)

**[Official Website](https://agentsecrets.theseventeen.co)** | **[Engineering Blog Series](https://engineering.theseventeen.co/series/building-agentsecrets)**

---

> **Package rename notice**
> The `agentsecrets` PyPI package is now the [AgentSecrets SDK](https://github.com/The-17/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:
> ```bash
> 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.

```bash
# An AI agent managing its own secrets workflow autonomously

agentsecrets status               # what workspace, project, 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

```bash
pip install agentsecrets-cli
```

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

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

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

# pip
pip install agentsecrets-cli
```

---

## Quick Start

```bash
# Create account + encryption keys
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
```bash
agentsecrets status
# Logged in as: steppa@theseventeen.co
# Workspace:    Acme Engineering
# Project:      payments-service
# Last pull:    2 minutes ago
```

### Notice drift and sync
```bash
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
```bash
agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY
# {"object":"balance","available":[{"amount":420000,"currency":"usd"}]}
```

### Audit what happened
```bash
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.

```bash
# 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.

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

### Role Management

```bash
agentsecrets workspace promote user@email.com   # Grant admin role
agentsecrets workspace demote user@email.com    # 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.

```bash
# Create workspace
agentsecrets workspace create "Acme Engineering"

# Invite teammates
agentsecrets workspace invite alice@acme.com
agentsecrets workspace invite bob@acme.com

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

**New developer onboards:**
```bash
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

```bash
# 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)

```bash
agentsecrets mcp install
```

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

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

### OpenClaw (Skill + Exec Provider)

```bash
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:

```bash
# 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):**

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

### HTTP Proxy (Any Agent or Framework)

```bash
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](https://github.com/The-17/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.

```python
pip install agentsecrets
```

```python
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:**
- [AgentSecrets MCP Server Template](https://github.com/The-17/agentsecrets-mcp-template) — scaffold for building MCP servers with zero credential storage
- [AgentSecrets for LangChain](https://github.com/The-17/agentsecrets-langchain) — zero-knowledge API calls in any LangChain agent

---

## Full Command Reference

### Account
```bash
agentsecrets init                    # Create account or login
agentsecrets login                   # Login to existing account
agentsecrets logout                  # Clear session
agentsecrets status                  # Current user, workspace, project, last sync
```

### Workspaces
```bash
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
```bash
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
```

### Secrets
```bash
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
```

### Proxy & Calls
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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 user@email.com              # Grant admin role
agentsecrets workspace demote user@email.com               # 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 | ❌ | ❌ | ❌ | ❌ |
| **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
```bash
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
```bash
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
```bash
# Agent handles this entire flow without human intervention
agentsecrets secrets diff          # checks for drift
agentsecrets secrets pull          # syncs if needed
agentsecrets workspace switch production
agentsecrets secrets pull
agentsecrets env -- python deploy.py
agentsecrets proxy logs            # audits what happened
```

### Incident Response at 2am
```bash
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](docs/ARCHITECTURE.md) and [PROXY.md](docs/PROXY.md) for deep dives.

---

## Roadmap

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

---

## Security

Reporting vulnerabilities: do NOT open public issues.
Email: hello@theseventeen.co — response within 24 hours.

---

## Contributing

Found a bug? [Open an issue](https://github.com/The-17/agentsecrets/issues)
Have an idea? [Start a discussion](https://github.com/The-17/agentsecrets/discussions)
Want to contribute? Check [CONTRIBUTING.md](docs/CONTRIBUTING.md)

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

---

## Links

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

---

## License

MIT — see [LICENSE](LICENSE)

Built by [The Seventeen](https://theseventeen.co)

---

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