Quick Start

Choose the installation method that fits your environment.

# macOS / Linux — recommended
brew install The-17/tap/agentsecrets

Verify your installation with:

agentsecrets --version

Run agentsecrets init to create your account and set up your local environment.

agentsecrets init

The interactive setup will:

1. Ask whether to create a new account or log in to an existing one
2. Ask which storage mode to use:
   • Keychain (recommended) — secrets are stored in your OS keychain; no .env file is created
   • Standard — secrets are written to a .env file (traditional workflow)
3. Generate a cryptographic keypair on your machine. Your private key never leaves your device.
4. Write .agent/workflows/agentsecrets.md, a workflow file that teaches any AI assistant how to use AgentSecrets automatically.

To skip the interactive prompts:

agentsecrets init --storage-mode 1   # Keychain mode (recommended)
agentsecrets init --storage-mode 2   # Standard .env mode

If you are returning to an existing account on a new machine, agentsecrets init detects that and walks you through joining your existing workspace.

The workflow file at.agent/workflows/agentsecrets.md is read automatically by Claude, Cursor, and other AI tools. Do not edit it manually to change environments — use agentsecrets environment switch instead.

Projects map to your applications. Secrets are partitioned by project, and every secrets operation uses the active project context.

agentsecrets project create my-app

This writes .agentsecrets/project.json in the current directory, linking it to the remote project. The file contains no credentials and is safe to commit.

New projects use the development environment by default. Switch environments at any time:

# Switch to staging environment
agentsecrets environment switch staging

Set secrets one at a time or multiple at once. When you run secrets set, AgentSecrets writes the secret to your local OS Keychain and automatically encrypts client-side and syncs it to the cloud backend:

# Set a secret (auto-saved locally and synced to cloud)
agentsecrets secrets set STRIPE_KEY=sk_live_...

# Set multiple secrets
agentsecrets secrets set STRIPE_KEY=sk_live_... OPENAI_KEY=sk-proj-...

The value goes directly to the OS keychain for the active environment. It is never written to disk in plaintext and never sent to the AgentSecrets server in plaintext.

If you already have a .env file, import it directly in bulk:

agentsecrets secrets push
# Reads from .env or .env.development
# Encrypts locally, uploads ciphertext
# You can delete the .env file after this

Confirm what’s stored (key names only, values are never displayed):

agentsecrets secrets list

Before making any proxy calls, tell AgentSecrets which API domains your project is allowed to reach. The allowlist is deny-by-default: calls to unauthorized domains are blocked before the secret is even resolved from the keychain.

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

Verify:

agentsecrets workspace allowlist list

This step is required. The proxy will return a 403 for any domain not on the allowlist, regardless of whether a matching secret exists. This is intentional — the domain check happens before secret resolution.

Allowlist changes require admin role and password confirmation.

Connect AgentSecrets to your AI assistant, Python scripts, or custom backend services.

import openai
from agentsecrets import init, credential

# 1. Initialize interception once
init()

# 2. Use official SDK with zero-knowledge credential placeholder
client = openai.OpenAI(api_key=credential.OPENAI_API_KEY)
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

agentsecrets proxy start

Check status:

agentsecrets proxy status

Stop when done:

agentsecrets proxy stop

The proxy runs in the background at localhost:8765. It resolves credential values from the OS keychain and injects them at the transport layer. Your code sends key names. Values never cross into your process.

Use agentsecrets call to make a one-shot authenticated request. Your agent provides the key name; the proxy resolves the value from the keychain and injects it into the outbound request.

agentsecrets call \
  --url https://api.stripe.com/v1/balance \
  --bearer STRIPE_KEY

Output:

HTTP 200

{"object":"balance","available":[{"amount":10000,"currency":"usd",...}]}

What was sent to Stripe: Authorization: Bearer sk_live_51H... What you (or your agent) saw: the API response only.

Theagentsecrets call command supports multiple injection styles. See injection-styles for the full reference.

Every call is logged with the key name, endpoint, agent identity, status, and duration. No value field exists in the schema.

# Check what was logged — key names, endpoints, status codes. No value field.
agentsecrets proxy logs --last 5

Output:

TIME      RESULT  METHOD  URL                           KEY         AUTH    STATUS  REASON  DURATION
14:23:01  * OK    GET     api.stripe.com/v1/balance     STRIPE_KEY  bearer  200     -       245ms

You can also tail the log in real time or filter by agent:

agentsecrets proxy logs --watch
agentsecrets logs list --agent my-billing-agent