secretless-ai

OpenA2A: CLI · HackMyAgent · Secretless · AIM · Browser Guard · DVAA

Keep API keys and other secrets invisible to AI coding tools. Works with Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, and Aider. Apache 2.0.

Website · Demos · Discord

Quick start

npx secretless-ai init

  Secretless v0.18.3
  Keeping secrets out of AI

  Configured: Claude Code (1 of 1 detected)

  Created:
    + .claude/hooks/secretless-guard.sh
    + CLAUDE.md

  Modified:
    ~ .claude/settings.json (added 86 deny patterns)

  Next steps:
    Verify: secretless-ai verify
    Scan:   secretless-ai scan
    Status: secretless-ai status

Install

npm

npx secretless-ai init          # run once, no install
npm install -g secretless-ai    # install globally

Requires Node.js 20.19 or later.

Homebrew

brew install opena2a-org/tap/secretless-ai

From source

git clone https://github.com/opena2a-org/secretless-ai.git
cd secretless-ai
npm install
npm run build && npm test
node dist/cli.js verify

Verifying what was installed

Every release publishes via npm Trusted Publishing with SLSA v1 provenance. No long-lived NPM_TOKEN. GitHub Actions exchanges its OIDC token with npm at publish time.

npm view secretless-ai dist.attestations --json
# Expects non-empty result with predicateType "https://slsa.dev/provenance/v1"

Secretless never reads or transmits credential values it manages. Backends (OS keychain, 1Password, HashiCorp Vault, GCP Secret Manager, AES-256-GCM encrypted file) decrypt on demand at subprocess spawn time. secretless-ai verify runs an integrity check of your local install.

How it works

1. Scans your project for hardcoded credentials in config files and source code. 57 credential patterns from @opena2a/[email protected], lockstep-asserted, across .js, .ts, .py, .go, .java, .rb, and more. Suppresses fixture-path false positives via .secretlessignore defaults (test/, __tests__/, examples/, e2e/, docs/vhs/, node_modules/, etc.).
2. Migrates them to secure storage: OS keychain, 1Password, HashiCorp Vault, GCP Secret Manager, or AES-256-GCM encrypted file.
3. Blocks AI tools from reading credential files. 21 file patterns enforced at the AI-tool hook layer.
4. Brokers access through environment variables. Secrets never enter AI context.

Store secrets and use them in AI sessions

Move keys out of files and into a storage backend, then use them by name. Values never enter AI context, transcripts, or shell history.

npx secretless-ai secret set STRIPE_SECRET_KEY   # value read from stdin, never echoed
npx secretless-ai import .env                    # or migrate an existing .env in one step
npx secretless-ai secret list                    # names only, values are never printed

secret set also installs a shell hook (eval "$(secretless-ai env)" in ~/.zshenv or ~/.bashrc), so new terminals export stored secrets as environment variables automatically. To inject into a single command instead of the whole shell:

npx secretless-ai run --only STRIPE_SECRET_KEY -- node charge.js

Reading a value back is TTY-gated: secret get NAME prints it in an interactive terminal, but is blocked in piped or AI-driven contexts unless --force is passed — and init installs deny rules so AI tools cannot run the --force form or dump an injected environment (run -- env).

Ask your AI assistant to use a secret

After init, the assistant's instruction file (CLAUDE.md, .cursorrules, ...) lists which keys are available as environment variables and tells the tool to reference them as $VAR_NAME without reading values. So this works in Claude Code:

Call the Stripe API and list the last 5 charges.

Claude writes the command with a variable reference. The shell substitutes the value inside the subprocess; nothing enters the model's context:

curl -s "https://api.stripe.com/v1/charges?limit=5" -H "Authorization: Bearer $STRIPE_SECRET_KEY"

For a key stored after init, or one init doesn't recognize, name the variable in your prompt ("use $GAMMA_API_KEY for auth") or add a row to the key table in CLAUDE.md. To keep the assistant away from raw values entirely, ask it to run commands under the injector:

Run the deploy script with secretless-ai run --only DEPLOY_TOKEN -- ./deploy.sh.

MCP server protection

Every MCP server config has plaintext API keys in JSON files on your machine. The LLM sees them. Secretless encrypts them.

npx secretless-ai protect-mcp

  Scanned 1 client(s)

  + claude-desktop/browserbase
      BROWSERBASE_API_KEY (encrypted)
  + claude-desktop/github
      GITHUB_PERSONAL_ACCESS_TOKEN (encrypted)
  + claude-desktop/stripe
      STRIPE_SECRET_KEY (encrypted)

  3 secret(s) encrypted across 3 server(s).
  MCP servers start normally. No workflow changes needed.

Scans configs across Claude Desktop, Cursor, Claude Code, VS Code, and Windsurf. Secrets move to your configured backend. Non-secret env vars (URLs, regions) stay untouched.

npx secretless-ai protect-mcp --backend 1password   # store MCP secrets in 1Password
npx secretless-ai mcp-status                        # show which servers are protected
npx secretless-ai mcp-unprotect                     # restore original configs from backup

Triage helpers

npx secretless-ai scan --min-confidence 0.85   # high-confidence findings only
npx secretless-ai ignore docs/migration.md     # append a path to .secretlessignore
npx secretless-ai ignore --pattern '*.golden.txt'
npx secretless-ai diff main                    # audit secretless-managed file changes vs a git ref
npx secretless-ai scan --json                  # machine-readable findings for CI
npx secretless-ai status --json                # protection state for CI (gate on summary.verdict)

scan renders a Confidence: high (0.92) line under every finding. The score combines pattern specificity, value entropy, value length, and path tier. With --no-ignore, findings whose path matches the default-ignore list are tagged (looks like a test fixture) so they stay visible without being re-suppressed.

Architecture

Three layers. Use one, two, or all three. Each works against any supported backend.

Tier 1: In-process SDK. Credentials resolved in the call stack and zeroized after use. Available in the Python and TypeScript AIM SDKs. Sub-millisecond overhead.

Tier 2: Vault Exec. A subprocess primitive that injects a credential into a child process's environment without exposing it to the parent. The agent running under an AI assistant never sees the secret.

npx secretless-ai vault exec github -- curl https://api.github.com/user

The child process receives $GITHUB. The parent shell, the AI tool's context, and any process listing see nothing. Language-agnostic. Wraps any command.

Tier 3: Broker with identity policy. A local daemon that mediates credential access across multiple agents. Policy rules allow or deny access by agent ID, credential name, time window, and rate limit. Optional AIM integration adds trust-score and capability constraints.

npx secretless-ai broker start

See Run the Broker for when to use the daemon and how to configure it.

AIM is optional. Tier 1 and Tier 2 work against any of the five storage backends with no AIM involvement. Tier 3 adds identity-bound policy when an AIM server is reachable. Default-deny still enforces locally without one.

Supported tools

Claude Code gets the strongest protection because it supports hooks. A shell script runs before every file read and blocks access at the tool level.

Storage backends

npx secretless-ai backend set 1password               # switch backend
npx secretless-ai migrate --from local --to 1password # migrate existing secrets

NanoMind integration

Optional integration with NanoMind for enhanced security analysis:

npm install @nanomind/guard @nanomind/engine  # optional

• MCP injection screening. protect-mcp screens env-var values for prompt-injection patterns and warns when suspicious content is detected.
• Rich scan explanations. scan --explain generates context-aware security explanations for each finding using NanoMind's local inference engine.

Both features gracefully degrade when NanoMind packages are not installed.

Using with opena2a-cli

opena2a-cli is the unified CLI for the OpenA2A security toolchain. Secretless powers opena2a secrets.

npm install -g opena2a-cli
opena2a review          # full security dashboard
opena2a secrets init    # initialize secretless protection

Telemetry

Secretless sends anonymous tier-1 usage data to the OpenA2A Registry: tool name (secretless-ai), version, command name (scan, protect, etc.), success, duration, platform, Node major version, and a stable per-machine install_id. No content is collected. No scanned secrets, no file paths, no env-var values, no rule contents, no IPs.

• Policy: opena2a.org/telemetry.
• Status: secretless-ai telemetry status.
• Disable per-invocation: OPENA2A_TELEMETRY=off secretless-ai <anything>.
• Disable persistently: secretless-ai telemetry off.
• Audit every payload: OPENA2A_TELEMETRY_DEBUG=print secretless-ai <anything> echoes each event to stderr as JSON.

Fire-and-forget with a 2-second timeout. Telemetry never blocks Secretless.

Use cases

Full index: docs/USE-CASES.md.

Contributing

Apache 2.0. PRs from outside the org welcome.

git clone https://github.com/opena2a-org/secretless-ai.git
cd secretless-ai && npm install && npm run build && npm test

Security issues: [email protected] (coordinated disclosure, response within 24 hours).

Links

• Website
• Documentation
• Demos
• OpenA2A CLI
• Credential patterns library
• aicomply — inline PII and credential classification for agent I/O at runtime, the complement to protecting credentials at rest

Part of the OpenA2A security platform.

License

Apache-2.0. See LICENSE.