DOCSEARCHbyAlgolia
Submit Docs

AgentSecrets

repository·main·Indexed 41 days ago

https://github.com/the-17/agentsecrets

A zero-knowledge credential infrastructure for AI agents that prevents secret leaks via prompt injection, logs, or process memory. It allows agents to use secret references while injecting actual values at the transport layer. Features include a CLI for managing secrets in the OS keychain, a deny-by-default workspace allowlist, an HTTP proxy with response body redaction, and integrations for OpenClaw (v2026.2.26), Claude Desktop, and Cursor via MCP.

Tokens
52K
Snippets
238
Records
282
Agent score
51%

What's inside AgentSecrets

  1. What is an AgentSecrets workspace?

    main

    A workspace is the top-level organizational boundary in AgentSecrets, acting as a team or organization. It serves as a container for:

    • Projects: Partitioned sets of secrets (e.g., backend, mobile, infra).
    • Members: Users with access to the workspace.
    • An allowlist: The specific domains the proxy is permitted to reach.

    When you create an account, a personal workspace is created automatically. You can create additional shared workspaces for team collaboration.

  2. How AgentSecrets Server Architecture Works

    main

    The agentsecrets-server is an asynchronous Django Ninja Extra backend running on ASGI (Uvicorn/Gunicorn) with PostgreSQL 16+.

    It utilizes two layers of security:

    1. Zero-Knowledge Core: Secrets are encrypted client-side using AES-256-GCM. The server only stores ciphertext blobs and never has access to plaintext values.
    2. Server Envelope Encryption: Stored blobs are further protected by an outer Fernet encryption key (ENCRYPTION_KEY) managed by the server.

  3. MCP Server Capabilities: list_secrets and api_call

    main

    The agentsecrets MCP server exposes two primary capabilities to AI agents:

    1. list_secrets: Allows the AI agent to discover the names of available secrets for the active project. Crucially, the actual secret values are never returned to the agent.
    2. api_call: Allows the AI agent to perform authenticated API requests by referencing secret names. The MCP proxy resolves the secret values in memory and injects them into the outbound HTTP requests, maintaining a zero-knowledge architecture.

  4. The 8 Local Trust Chain Checks

    main

    The agentsecrets doctor command verifies the following eight links in the local security trust chain:

    1. Daemon Installed & Versioned: Verifies keychain-auth is installed and meets the minimum version (>= v3.3.0).
    2. Daemon Running & Socket Dialable: Checks that the daemon background service is active and its IPC socket is dialable (e.g., /run/keychain-auth/agent.sock on Linux, ~/Library/Application Support/keychain-auth/agent.sock on macOS, or \. extbackslash pipe extbackslash keychain-auth on Windows).
    3. Daemon Up-to-Date: Ensures the running daemon process is not serving outdated or orphaned code.
    4. Binary Registered: Confirms the specific agentsecrets binary path and its SHA-256 hash are registered in the daemon's trust store.
    5. Live Policy Authorization: Probes the daemon's in-memory policy to verify the active session is granted access.
    6. Socket Integrity: Detects and cleans up orphaned or stale socket files.
    7. Trust Store Permissions: Audits /etc/keychain-auth/config.json to ensure it is not world-writable (hardened to 0640 root:keychain-auth).
    8. Credential Decryption: Verifies that stored credentials and workspace keys can be decrypted and read by the authorized binary.

  5. Manage AgentSecrets environments

    main

    AgentSecrets projects are partitioned into three default environments: development, staging, and production. Your active environment determines which secrets are synced to your local OS keychain and which external environment is targeted by secrets pull or secrets push commands.

    Use the agentsecrets environment command to manage these partitions.

    agentsecrets environment [command]

  6. How keychain-auth provides process-level verification

    main

    The keychain-auth daemon acts as a Zero-Trust Security Broker between agentsecrets and the OS keychain. It prevents unauthorized processes from accessing credentials by verifying the caller's identity via the OS kernel.

    Verification Workflow:

    1. agentsecrets connects to the keychain-auth Unix socket or Named Pipe.
    2. The daemon retrieves the caller's real PID using peer credentials (SO_PEERCRED or LOCAL_PEERPID).
    3. The daemon resolves the executable path and computes its SHA-256 hash.
    4. The daemon accepts the connection only if the hash matches a registered entry in config.json or if the binary has a valid Ed25519 developer code signature.

    Security Properties:

    • Connection-Bound: No session tokens are sent; closing the socket terminates the session.
    • Anti-Hijacking: Uses O_CLOEXEC to ensure the socket file descriptor is not inherited by child processes.

  7. Understand AgentSecrets telemetry collection

    main

    AgentSecrets collects anonymous, non-sensitive usage metrics to improve the CLI. No secret values, project names, or personal data are ever collected.

    Collected Data:

    • Command execution counts (e.g., secrets: 15, workspace: 3, call: 7)
    • OS and architecture
    • CLI version
    • Active environment name

    Mechanism:

    1. Counters are incremented in ~/.agentsecrets/telemetry.json during command execution.
    2. Counters are pushed to an internal API every 24 hours.
    3. Syncing occurs during CLI exit and does not block command execution.

  8. How AgentSecrets encryption and security guarantees work

    main

    AgentSecrets provides two structural security guarantees through its architecture:

    1. Server Isolation: The server only stores encrypted blobs. Decryption is impossible without your private key, which never leaves your device.
    2. Agent Isolation: AI agents never receive secret values. They only see key names, endpoints, and API responses. Values are injected at the proxy or process level, ensuring they never enter the agent's context.

    Encryption Hierarchy

    Secrets are protected by a multi-layered encryption model:

    • Password → Key: Uses Argon2id for memory-hard key derivation.
    • Private Key: Uses X25519 (asymmetric) to enable team sharing without server involvement.
    • Workspace Key: Uses AES-256-GCM (symmetric) to encrypt the actual secret values.

    Key Storage and Access

    KeyWhere StoredWho Can Access
    Private KeyKeychain via keychain-auth daemonYou only
    Workspace KeyCached securely in client memoryYou + authorized client binaries
    Password-Derived KeyNever stored (derived on demand)You only (requires password)

    Secure keychain operations are managed by the local keychain-auth daemon, which uses native services like Apple Keychain (macOS), Windows Credential Manager, or Secret Service (Linux).

  9. How AgentSecrets resolves the server URL

    main

    When executing any CLI command, the AgentSecrets CLI determines which server endpoint to use by following a specific resolution priority. If multiple configurations exist, the highest priority item in this list wins:

    1. CLI Flag: --server <URL>
    2. Environment Variable: AGENTSECRETS_SERVER_URL or AGENTSECRETS_API_URL
    3. Project Config: .agentsecrets/project.json (set via --project)
    4. Global Config: ~/.agentsecrets/config.json
    5. Default Server: https://api.agentsecrets.tech/api

  10. Use Ed25519 code signing for seamless updates

    main

    To prevent manual re-registration every time a binary is updated, keychain-auth supports Developer Code Signing.

    Client binaries can be signed using an Ed25519 private key. The resulting 64-byte signature and KCAS magic bytes are appended to the end of the binary. The daemon verifies these signatures against trusted public keys stored in /etc/keychain-auth/config.json. If the signature is valid, the daemon automatically registers the new binary hash without user intervention.

  11. How the agentsecrets allowlist security model works

    main
    The allowlist operates on a zero-trust principle. The credential proxy validates the outbound domain against the allowlist before attempting to resolve any secret from the OS keychain. If the requested domain is not present in the allowlist, the request is immediately rejected with an HTTP 403 error. This prevents unauthorized agents from accessing secrets to communicate with unapproved external services.

  12. Key guarantees of AgentSecrets migration

    main

    AgentSecrets migration ensures data integrity and security through two primary mechanisms:

    • Zero-Knowledge Preserved: Secret payloads remain encrypted under client-side workspace keys throughout the entire export, transport, and import lifecycle.
    • Direct Stream: In the recommended mode, the destination server pulls data directly from the source server over TLS, avoiding the need for a disk-based file intermediary.