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.23.0
  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 96 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. 18 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 scan --max-files 20000       # raise the per-walk file cap (default 5000)
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.

Incomplete scans do not report clean

A scan that could not read everything is not a passing scan. If the walk stops at the file cap, or a path cannot be opened, scan prints what it missed, exits 1, and says No credentials found in the files scanned rather than No hardcoded credentials found. In --json, summary.truncated and summary.unreadable carry the same signal, so CI can tell "clean" from "unfinished".

Two kinds of gap, and only one of them gates. A gap against a claim the scanner made -- it said it would read something and did not -- sets exit 1: truncated, unreadable, oversize. A boundary the scanner declared and never claimed to cross does not: outOfRoot, skippedUnsupported (files enumerated but not opened, such as a .png or a .md), and notEntered (directories not descended into, such as node_modules/ or any dot-directory). The second group is reported, sampled and given the command that scans it, but it does not fail your build -- every repository contains at least one of them, so gating on it would fail every build. If you want a declared boundary to gate, test it yourself: jq -e '.summary.notEntered == 0'.

Dot-directories are among the notEntered group, and that includes .claude/. Config files and key files inside them are still scanned; source files inside them are not. See issue #144.

Symlinks are followed inside the scan root. A link whose target resolves outside it is not followed -- otherwise a repo containing link -> $HOME would pull the whole home directory into the scan -- and each one is listed with the command to scan its target directly, so the boundary is never silent. These do not affect the exit code.

A flag never widens scope

A command line the tool cannot bind is refused with exit 2 before anything runs, rather than partly ignored. That covers an unrecognised flag, a flag given a value it cannot use, and a value-taking flag given no value at all. --only=NAME, --path=DIR and every other --flag=value spelling binds the same way as the spaced form.

scan, scan-staged and scan-history refuse an unrecognised flag rather than warning and continuing, because their output is the answer: a typo in a coverage flag used to produce No hardcoded credentials found. at exit 0 over a narrower scan than the one you asked for. feedback and diff still warn, since they report no verdict.

--json is implemented by scan and status. Passing it to any other command exits 2 and names those two, rather than printing human text and exiting 0 -- the caller of --json is a machine, and a machine reading exit 0 beside prose cannot tell it was ignored.

Exit codes: 0 clean, 1 credentials found (or an incomplete scan), 2 the command line was refused and nothing ran. Gate CI on 2 separately -- it means the tool did not answer the question, not that the answer was clean.

npx secretless-ai clean --dryrun --path ./transcripts
#   Unknown option: --dryrun (did you mean --dry-run?)
#   `clean` was not run. Nothing was changed.
#   Supported: --dry-run, --help, --last, --path <value>
#   Run `secretless-ai clean --help` for usage.

npx secretless-ai scan --json | jq '.summary'
# { "total": 0, "critical": 0, "high": 0, "placeholdersSuppressed": 0,
#   "truncated": false, "maxFiles": 5000, "unreadable": 0, "outOfRoot": 0,
#   "oversize": 0, "skippedUnsupported": 0, "notEntered": 0 }

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

| Tool | Protection method | |---|---| | Claude Code | PreToolUse hook (blocks reads before they happen) + deny rules + CLAUDE.md | | Cursor | .cursorrules instructions | | GitHub Copilot | .github/copilot-instructions.md instructions | | Windsurf | .windsurfrules instructions | | Cline | .clinerules instructions | | Aider | .aiderignore file patterns |

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

| Backend | Storage | Best for | |---|---|---| | local | AES-256-GCM encrypted file | Quick start, single machine | | keychain | macOS Keychain or Linux Secret Service | Native OS integration | | 1password | 1Password vault | Teams, CI/CD, multi-device | | vault | HashiCorp Vault KV v2 | Enterprise, self-hosted | | gcp-sm | GCP Secret Manager | GCP-native workloads |

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.
• Generated scan context. scan --explain can add a model-written note beside each finding, off by default and enabled with SECRETLESS_NANOMIND_EXPLAIN=1. It is off because the local engine does not yet produce explanations worth showing: over 30 measured runs, none were usable and several asserted things about the credential that were not true. Verified remediation always comes from the finding itself, never from the model.

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

| Guide | Time | |---|---| | Protect My Credentials | 2 min | | Secure MCP Configs | 3 min | | Bring Your Own Vault | 3 min | | Run the Broker | 3 min | | Team Setup | 5 min | | Migrate from .env | 3 min |

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.