How AgentSecrets Works

AgentSecrets is a zero-knowledge developer credential orchestrator built for the AI era. Rather than acting as a simple HTTP request proxy, it manages the complete credentials lifecycle—secure storage, zero-knowledge sync, environment isolation, team sharing, transport-layer injection, and auditing—for AI agents and automated workflows.

By decoupling credentials from the application runtime, AgentSecrets ensures that sensitive keys never enter the memory, context, file logs, or console output of AI agents.

Core Capabilities Enabled

AgentSecrets enables developers to build and run AI agents and automated workflows with strict security boundaries:

Absolute Context Decoupling: AI agents only hold key references (e.g., STRIPE_KEY) rather than plaintext values. This protects credentials from prompt injection attacks, context window leakage, and compromised third-party dependencies.
Zero-Trust Team Synchronization: Team members can share environments and sync secrets securely without ever exposing decryption keys to the central coordination server.
Granular Access Control: Credentials are bound to specific workspaces, projects, environments, and authorized domain targets.
Auditable Agent Execution: Outbound calls are mapped to cryptographic agent identities, allowing you to trace which agent accessed which external API and when.

Zero-Knowledge Architecture

The zero-knowledge nature of AgentSecrets is holistic: the credential value itself is structurally absent across the entire architecture. For cloud synchronization, the sync server only stores ciphertext and never receives the Workspace Key. For runtime execution, the agent only sees key references while the trusted proxy/keychain boundary resolves the value transiently for transport-layer injection. The raw secret value is never returned to the agent, written to disk, recorded in logs, or exposed to the sync servers.

At-Rest Encryption & Process-Level Security

When secrets are defined locally, they are secured via your operating system keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). Because accessing the OS keychain safely requires process-level boundaries, AgentSecrets runs a secure background daemon called keychain-auth to manage all cryptographic operations.

When you sync these secrets to the cloud:

The keychain-auth daemon validates the cryptographic hash of the AgentSecrets CLI binary to prevent impersonation (Anti-Impersonation).
Once verified, the daemon retrieves the symmetric Workspace Key from your OS keychain.
The payload is encrypted locally using AES-256-GCM with a key derived from the Workspace Key via Argon2id.
The resulting ciphertext blob and initialization vectors (nonce and tag) are pushed to the backend database.
The server wraps this base64 blob in a second layer of Fernet encryption at rest. Because the server does not possess the Workspace Key, it is mathematically blind to your secrets.

To share credentials with teammates without a centralized key custodian, AgentSecrets uses a zero-trust asymmetric key exchange (NaCl SealedBox utilizing Curve25519):

Loading diagram...

Key Generation: When team members register, their local CLI generates an asymmetric Curve25519 keypair. The private key remains locally in their keychain; the public key is uploaded to the backend.
Envelope Creation: When you invite a user to a workspace, your local CLI fetches their public key, encrypts the Workspace Key using NaCl SealedBox, and uploads the encrypted envelope to the server.
Key Recovery: When the invitee accepts the invite, their local CLI downloads the envelope and decrypts it using their private key, restoring the Workspace Key locally. The backend never has access to the private key, maintaining zero-knowledge integrity.

The Proxy Call Lifecycle

The AgentSecrets proxy intercepts outgoing requests, validates them against target allowlists, and injects resolved credentials right before they hit the wire.

Loading diagram...

1Request Interception

The AI agent or application sends an outbound HTTP/HTTPS request, pointing authorization headers or request bodies to a key name (e.g. bearer="STRIPE_KEY"). The proxy daemon (running at localhost:8765) intercepts this request.

2Pre-Execution Allowlist Check

As an additional safety net, the target host is checked against the active workspace domain allowlist. If the domain is not authorized, the proxy aborts the execution with a 403 Forbidden, logs the blocked attempt, and stops. This prevents prompt injections from exfiltrating credentials to external hacker-controlled servers.

3Decryption and Anti-Impersonation

The proxy locates the workspace key, environment context, and key name. It queries the background keychain-auth daemon. The daemon verifies the cryptographic hash of the calling proxy process to ensure no unauthorized process is attempting to fetch secrets. Once approved, it decrypts the secret value inside the proxy daemon's private memory space. The decrypted value is never written to disk, output to standard streams, or returned to the calling agent process.

4Transport-Layer Injection

The decrypted credential is substituted into the request payload at the network layer. Depending on the configured injection style, it is placed in headers (e.g., Authorization: Bearer), URL query parameters, or JSON body fields. The request is then securely forwarded to the upstream API using TLS.

5Response Scanning and Redaction

Once the upstream API returns a response, the proxy scans the body. If the upstream service reflects the API key back in the payload (often found in error logs or debug fields), the proxy redacts it, replacing the token with [REDACTED_BY_AGENTSECRETS].

Finally, the proxy logs the metadata of the call (timestamp, requesting agent token, environment, endpoint, response status, and duration) to the audit log. No credential values are ever saved in the logs. The redacted response is then handed to the calling agent code.

Execution Modes

AgentSecrets provides four distinct execution paths, each suited to a different workflow:

1Credential Proxy (Persistent Daemon)

The primary mode for AI agents and long-running processes. Start the daemon, route HTTP traffic through localhost:8765, and the proxy intercepts, resolves, and injects credentials at the transport layer automatically.

agentsecrets proxy start

The proxy runs as a background daemon, handling every outbound request through the full enforcement pipeline — allowlist checks, anti-impersonation verification, secret policy evaluation, transport-layer injection, and response redaction.

2Environment Injection (CLI & Scripts)

For tools, test runners, and scripts that read from environment variables:

agentsecrets env -- npm test
agentsecrets env -- python train.py

AgentSecrets spawns the child process with secrets injected into its environment — no .env file needed, no plaintext on disk. The values exist only in the child process RAM for its lifetime.

3Direct CLI Calls (One-Shot Requests)

For quick API calls, curl replacements, and ad-hoc testing:

agentsecrets call --url https://api.stripe.com/v1/balance --bearer STRIPE_KEY
agentsecrets call --url https://api.openai.com/v1/models --header Authorization=OPENAI_KEY

Each call spawns a transient proxy, resolves the credential, injects it, makes the request, and tears down. No daemon required.

4MCP Server (AI Assistant Integration)

For AI coding assistants and desktop tools that support the Model Context Protocol:

agentsecrets mcp install

This registers an MCP server that exposes credential resolution as tools (api_call, list_keys, check_key) to clients like Cursor and Claude Desktop. The same zero-knowledge guarantees apply — the assistant sees key references, never values.

Secret Policy Enforcement Pipeline

Every request through the proxy passes through a multi-stage policy engine before a credential is resolved:

Agent Identity Check: If an agent token is present, the proxy validates it and loads the agent's capability allowlist/denylist.
Target Domain Verification: The outbound domain is checked against the workspace allowlist. Unauthorized domains receive a 403 Forbidden.
Secret Policy Evaluation: If the requested credential has a policy attached (restricted domains, HTTP methods, or required approval), the proxy enforces it. If the policy requires interactive approval, the proxy pauses and prompts via agentsecrets proxy approve.
Anti-Impersonation: Before querying the keychain, the keychain-auth daemon verifies the calling process hash and binary path.
Transport-Layer Injection: The credential is injected into the outbound request at the network boundary.
Response Redaction: The upstream response is scanned for reflected credential values and redacted before delivery.

This pipeline ensures that every authenticated call is governed, attributed, and audited — not just proxied.

Outbound Access Control and Identity Scoping

To ensure complete runtime security, AgentSecrets enforces boundaries at two levels:

Binary Anti-Impersonation (Keychain Auth)

Before any request is intercepted or keys are fetched, the local keychain-auth daemon verifies the cryptographic hash and execution path of the proxy making the request. This ensures that no unauthorized script or malware running locally can impersonate the legitimate proxy or CLI to extract credentials.

Cryptographic Agent Identity

By default, AgentSecrets supports anonymous execution for simple, single-agent setups or one-off tools. However, for multi-agent workflows, you can enforce cryptographic identity attribution:

Anonymous Execution (Default): Outbound calls are permitted and logged with no agent attribution (marked as anonymous).
Cryptographic Attribution: Every authorized agent instance is issued a cryptographic Agent Token. When an agent makes requests:
- The proxy cryptographically validates the token.
- The request is linked to the agent's identity in the audit log.
- You can instantly revoke an individual agent's token without rotating or changing underlying workspace credentials, isolating compromises immediately.

Environment Boundaries

Credentials are bound to environment namespaces (development, staging, production). The proxy enforces runtime boundaries, preventing development code from using production-level credentials, and vice versa, keeping data access segregated.