Skip to content

The-17/agentsecrets

BranchesTags

Repository files navigation

AgentSecrets

Zero-Knowledge Credential Infrastructure for AI Agents (and Humans and Teams): Secure key orchestration, sandboxed execution capabilities, and runtime delegation without ever exposing secret values to agent reasoning loops.

License: MIT Go Version Stars ClawHub

Website | Docs | Engineering Blog

AgentSecrets is the zero-knowledge credential infrastructure for the AI era. It decouples credentials from the application runtime entirely, ensuring that agents execute tasks using credentials by reference without ever holding the raw values in memory.

To achieve this, AgentSecrets acts as an extensible infrastructure host. Specific security guarantees are enforced by subsystems that plug into AgentSecrets:

Subsystem / Layer System What It Solves Claim
Credential Infrastructure AgentSecrets (Host) Agent credential theft & lifecycle management Extensible zero-knowledge infrastructure: credentials are resolved and injected at runtime without agents holding secret values
Capability Bounding Subsystem Keychain-Auth Static, long-lived, over-privileged local credentials OS-level keychain integration with process identity validation and dynamic session bounding

AgentSecrets compiles these subsystems into a cohesive, provably secure framework. At no step does the agent hold, see, or have access to the actual credential value. The zero-knowledge guarantee is architectural, not policy-based.

Contents

Package rename notice The agentsecrets PyPI package is now the AgentSecrets SDK: for developers building tools and agents on AgentSecrets infrastructure. The CLI wrapper is now agentsecrets-cli. The agentsecrets command itself is unchanged.

The Critical Difference

There are two fundamentally different approaches to secrets management for AI agents.

Runtime retrieval (the common pattern)

The agent fetches or leases a credential at runtime. The value enters agent memory.

export TOKEN=$(secrets lease github_token)
# The agent now holds sk_live_51H... in memory

Once the value enters agent context, it can be extracted via prompt injection, exposed in logs or traces, and accessed by tools, plugins, or any dependency running in the same process.

Zero-knowledge injection (AgentSecrets)

The agent references a key name. The value is resolved outside the agent and injected at the transport layer.

agentsecrets call --bearer GITHUB_TOKEN
# The agent referenced a name. It never received a value.

If a system gives an AI agent access to a credential value, it must accept that the value can be leaked. AgentSecrets removes that assumption entirely.

Why the Architecture Matters

Most approaches to AI agent credential security follow the same pattern: store secrets securely, then retrieve and inject them at runtime.

Secure store → agent retrieves sk_live_51H... → value enters agent memory
                                               → prompt injection can reach it
                                               → malicious plugin can read it
                                               → CVE exposes it
                                               → LLM trace captures it

Whether the store is a .env file, HashiCorp Vault, AWS Secrets Manager, or a leasing system, if the agent retrieves the value, the value is in agent context. That is the moment of exposure.

AgentSecrets eliminates that moment entirely.

OS keychain → proxy resolves in memory → value injected at transport layer
                                       → agent receives API response only
                                       → value never entered agent context
                                       → nothing to steal, log, or extract

The agent never retrieves the value. It cannot be prompted to reveal it. It cannot be logged. It cannot be stolen through a plugin or CVE. It was structurally absent from every place an attack would look.

Extensible Security Architecture

AgentSecrets hosts modular subsystems to provide layered defense-in-depth:

Zero-Knowledge Credential Core: Six auth injection styles, client-side encryption (X25519, AES-256-GCM, Argon2id), response body redaction, SSRF protection, and environment variable injection (agentsecrets env -- <cmd>). The server stores client-encrypted ciphertext it structurally cannot decrypt.

Capability Bounding (Keychain-Auth): Protects OS keychain access via process verification (Anti-Impersonation). It verifies the cryptographic hash of calling processes (like the CLI or proxy) and restricts credentials to authorized execution namespaces with session capability boundaries.

Environments & Teams: Switches contexts (development, staging, production) instantly. Syncs secrets client-side via NaCl SealedBox key exchange across team workspaces. No plaintext keys touch the wire or disk.

Identity & Audit Logs: Maps executions to cryptographically issued Agent Tokens (when configured). The log stores metadata, status, environment, and target scopes. No value field exists in the schema.

Developer SDK & MCP: Build MCP servers, plugins, and agents where credential values are resolved below the runtime loop. The SDK has no get() method to prevent accidental or malicious retrieval.

MCP integration: first-class MCP server for Claude Desktop and Cursor. No credential values in any config file.

Environment variable injection: agentsecrets env -- <command> wraps any process and injects secrets from the OS keychain at spawn time. Nothing written to disk.

Installation

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

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

# pip
pip install agentsecrets-cli

# Go (recommend using a pinned version for supply chain security)
go install github.com/The-17/agentsecrets/cmd/agentsecrets@v2.0.0

Quick Start

agentsecrets init

agentsecrets project create my-agent

# Set a single secret
agentsecrets secrets set STRIPE_KEY=sk_live_51H...

# Set multiple secrets at once
agentsecrets secrets set STRIPE_KEY=sk_live_51H... OPENAI_KEY=sk-proj-...

agentsecrets workspace allowlist add api.stripe.com api.openai.com

agentsecrets mcp install        # Claude Desktop + Cursor
agentsecrets proxy start        # any agent via HTTP proxy

The Agent Workflow

This is what AgentSecrets looks like when an AI agent operates the full credentials lifecycle autonomously.

agentsecrets status

AgentSecrets Status

  ──────────────────────────────
  Logged in as:        alice@theseventeen.co
  Session:             Active (expires 5 hours from now)
  Refresh Token:       Available
  Selected Workspace:  Acme Engineering (shared)
  Environment:         production (from project.json)
  Current Project:     payments-service (in Acme Engineering)
  Proxy:               Running (port 8765)
  Secrets:             12 synced (0 unsynced)
  Activity:            Last Push: 2 minutes ago | Last Pull: 5 minutes ago

agentsecrets secrets diff
# Comparing secrets & allowlist...
# 
# SECRETS:
# 
#   In Cloud but missing in Local:
#     STRIPE_KEY
# 
# Run agentsecrets secrets pull to sync from cloud.

agentsecrets secrets pull
# Pulling 1 secret and allowlist...
# Successfully synced cloud secrets and allowlist domains.

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

agentsecrets proxy logs --last 5
# 14:23:01  GET  api.stripe.com/v1/balance  STRIPE_KEY  200  245ms

The agent managed the complete workflow. No credential value appeared at any step. The audit log has no value field because there was no value to log.

Environments

Every project has three built-in environments. One command switches the active context. The proxy, push, pull, and diff commands all respect the active environment automatically.

agentsecrets environment switch production

agentsecrets environment list
#   development   12 secrets
#   staging        8 secrets
#   production    12 secrets   ← active

agentsecrets secrets diff --from development --to production
# In development but missing in production:
#   OPENAI_KEY
#   DATABASE_URL

agentsecrets environment merge staging production
# Prompts for production values for each staging key

Team Workspaces

agentsecrets workspace create "The Seventeen Engineering"
agentsecrets workspace invite alice@theseventeen.co bob@theseventeen.co

agentsecrets project create payments-service
agentsecrets project create auth-service

New developer onboards:

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

Agent Identity

# Declared identity
client = AgentSecrets(agent_id="billing-processor")

# Issued identity, cryptographically verified on every call
agentsecrets agent token issue "billing-processor"
# → agt_ws01hxyz_4kR9mNpQ...
client = AgentSecrets(agent_token="agt_ws01hxyz_...")

# Audit by agent
agentsecrets log list --agent billing-processor
agentsecrets log list --identity anonymous   # find coverage gaps

6 Auth Injection Styles

# Bearer token
agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY

# Custom header
agentsecrets call --url https://api.sendgrid.com/v3/mail/send \
  --header X-Api-Key=SENDGRID_KEY

# Query parameter
agentsecrets call \
  --url "https://maps.googleapis.com/maps/api/geocode/json?address=Lagos" \
  --query key=GOOGLE_MAPS_KEY

# Basic auth
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

Zero-Trust Proxy Security

Every proxied request passes through four security layers before injection:

Domain allowlist: deny-by-default. Every target domain must be explicitly authorized. Unauthorized domains are blocked before credential resolution, regardless of whether the request came from prompt injection, SSRF, or misconfiguration.

Response body redaction: if an external API echoes the injected credential in its response, the proxy replaces it with [REDACTED_BY_AGENTSECRETS] before the response reaches the agent.

SSRF protection: private IP ranges, localhost, and non-HTTPS targets are blocked at the proxy level.

Session token: generated at proxy startup, required on every request. Blocks rogue processes on the same machine from using the proxy.

agentsecrets workspace allowlist add api.stripe.com api.openai.com
agentsecrets workspace allowlist list
agentsecrets workspace allowlist log   # view blocked attempts

Encryption Model

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 ciphertext only, structurally cannot decrypt

AI Tool Integrations

Claude Desktop + Cursor

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

OpenClaw

openclaw skill install agentsecrets

Native exec provider for OpenClaw's SecretRef system. Credentials resolve at execution time through the AgentSecrets binary. Nothing in any OpenClaw config file.

Environment Variable Injection

agentsecrets env -- stripe mcp
agentsecrets env -- node server.js
agentsecrets env -- python manage.py runserver
agentsecrets env -- npm run dev

Values injected into child process memory at spawn time. Nothing written to disk. Gone when the process exits.

HTTP Proxy

agentsecrets proxy start

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

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

Build on AgentSecrets

pip install agentsecrets
from agentsecrets import AgentSecrets

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

The SDK has no get() method. There is no way to retrieve a credential value into calling code. The only operations available are the ones that keep the value out of agent context. The secure path is the only path.

Built on the SDK:

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                  # Workspace, project, environment, last sync

Workspaces

agentsecrets workspace create "Name"
agentsecrets workspace list
agentsecrets workspace switch "Name"
agentsecrets workspace invite user1@email.com user2@email.com
agentsecrets workspace promote user@email.com
agentsecrets workspace demote user@email.com
agentsecrets workspace allowlist add <domain>
agentsecrets workspace allowlist list
agentsecrets workspace allowlist log

Projects

agentsecrets project create NAME
agentsecrets project list
agentsecrets project use NAME
agentsecrets project update NAME
agentsecrets project delete NAME
agentsecrets project invite user@email.com

Environments

agentsecrets environment switch <n>
agentsecrets environment list
agentsecrets environment copy <from> <to>
agentsecrets environment merge <from> <to>
agentsecrets environment clean

Secrets

agentsecrets secrets set KEY=value
agentsecrets secrets get KEY
agentsecrets secrets list
agentsecrets secrets push
agentsecrets secrets pull
agentsecrets secrets delete KEY
agentsecrets secrets diff
agentsecrets secrets diff --from X --to Y

Proxy and Calls

agentsecrets call --url URL --bearer KEY
agentsecrets proxy start [--port 8765]
agentsecrets proxy status
agentsecrets proxy stop
agentsecrets proxy logs [--last N] [--watch] [--env ENV]
agentsecrets mcp serve
agentsecrets mcp install
agentsecrets exec
agentsecrets env -- <command>

Audit

agentsecrets log list [--tail] [--agent NAME] [--identity anonymous]
agentsecrets log summary [--since 7d]
agentsecrets log export --format csv
agentsecrets log detail <id>

Agent Identity

agentsecrets agent list
agentsecrets agent delete <n>
agentsecrets agent token issue <n>
agentsecrets agent token list <n>
agentsecrets agent token revoke <id> --agent="<n>"

Roadmap

  • Core CLI
  • Zero-knowledge cloud sync
  • Credential proxy with 6 auth styles
  • Workspaces, projects, team invites
  • MCP server (Claude Desktop, Cursor)
  • HTTP proxy server
  • OpenClaw skill + exec provider
  • Governance audit log
  • Agent identity + token management
  • Environment support (development / staging / production)
  • Domain allowlist + response body redaction
  • agentsecrets env for environment variable injection
  • Python SDK
  • Zero-Knowledge MCP Template
  • Multi-platform binaries (macOS, Linux, Windows)
  • npm, pip, Homebrew distribution
  • 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

Trust Model & OS Keychain

AgentSecrets delegates authentication and cryptography to the user's local OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service). Be mindful of which workspace and environment you configure for your agents, as they will have access to any credentials provisioned in that specific scope. However, unwanted actions and API calls are heavily mitigated by the domain allowlist, which bounds where agents can send those credentials.

Audit Logging Privacy

Every proxy call is recorded in a persistent audit log (locally at ~/.agentsecrets/proxy.log and globally in the cloud). The log records endpoints, timestamps, and key names (e.g., STRIPE_KEY), but never the actual values. Do not put sensitive data in the key names themselves.

Supply Chain Security

Your security depends on the integrity of the installed agentsecrets package. We strongly recommend installing from official sources (like Homebrew) which verify package hashes, or using pinned versions for go install (e.g., @v2.0.0 instead of @latest) to mitigate upstream supply chain poisoning.

Vulnerabilities: do NOT open public issues. Email: engineering@theseventeen.co, response within 24 hours.

Contributing

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

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

Links

License

MIT. See LICENSE

Built by The Seventeen

You cannot steal what was never there.

About

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

agentsecrets.theseventeen.co

Topics

security devops ai developer-tools ai-agents ai-security credential-management openclaw agent-secrets

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

119 stars

Watchers

3 watching

Forks

14 forks
Report repository

Releases 13

v2.1.0 Latest
May 27, 2026
+ 12 releases

Packages

 
 
 

Contributors

Languages