Part of the security infrastructure for AI agents

Keep secrets out of AI context.

Keep AI coding tools away from credential files: a hook in Claude Code, instruction or ignore files in other tools. Store secrets in encrypted backends. Protect MCP server configs. One command to set up.

$npx secretless-ai init

View on GitHub Documentation

Open source. secretless-ai 0.23.0.

The problem.

AI coding tools read your filesystem. That includes .env files, SSH keys, cloud credentials, and MCP server configs. Without protection, your secrets enter the context window on every interaction.

Without secretless

xAI reads .env files with API keys.
xCredentials sent to remote AI APIs.
xSSH keys and cloud credentials exposed in context.
xAI suggests hardcoded secrets in code.

With secretless

Secret files are off limits: denied by a hook in Claude Code, by instruction elsewhere.
Stored values are referenced by name instead of pasted into the context window.
In Claude Code, a shell command whose text reads a secret file or prints a secret variable is denied before it runs.
AI uses environment variable references instead.

How it works.

Secretless auto detects your AI tools, installs a protection for each, stores credentials in encrypted backends, and injects them at runtime.

Detect

Scans your project for AI tool config files. Finds .claude/, .cursorrules, .aider.conf.yml, and more.

Configure

Installs tool specific protections. Hooks for Claude Code, instruction files for Cursor and Copilot, ignore patterns for Aider.

Store

Secrets go into encrypted backends: local AES-256-GCM, OS keychain, 1Password, Vault, or GCP Secret Manager, instead of .env files.

Inject

At runtime, secrets are injected into the process as environment variables. The AI tool refers to them by name and works from the command's output.

What secretless means here.

On this page, secretless means the AI tool works without seeing secret values. The secrets still exist: they are stored in an encrypted backend and injected into a command's environment when it runs.

Enforcement differs by tool. In Claude Code a hook and deny rules refuse a read of a credential file before it runs. For Cursor, GitHub Copilot, Windsurf and Cline, Secretless writes an instruction file that asks the model not to read credential files: nothing enforces it, and it has no effect unless the tool loads that file. For Aider it writes ignore patterns. A command whose own output is a credential still puts that value in the model's context.

Does secretless mean there are no secrets?

No. The secrets are stored in a backend: the OS keychain, 1Password, HashiCorp Vault, GCP Secret Manager or an AES-256-GCM encrypted file. A command receives them as environment variables when it runs.

How does an AI coding tool use a key it cannot read?

By name. The tool writes $STRIPE_SECRET_KEY in a command and the shell substitutes the value inside the subprocess. To inject one stored secret into one command:

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

Is this authentication or authorization?

Neither on its own. Secretless AI is not an identity provider and signs nobody in: it stores credentials and controls how they reach a process. Authorization comes with the optional broker, a local daemon whose policy rules allow or deny each request by agent ID, credential name, time window and rate limit.

Does it replace HashiCorp Vault?

No. Vault is one of the five storage backends. Secretless AI reads and writes Vault's KV v2 engine using VAULT_ADDR and VAULT_TOKEN. This command copies stored secrets into it:

$ npx secretless-ai migrate --from local --to vault

What does it not protect against?

What a command prints, and other processes. The hook and the deny rules check a command by its text before it runs and cannot see its output, so a command that returns a credential, such as a cloud CLI call that fetches a secret, places the value in the model's context. The gate sits on the assistant's tool path: it is not a boundary against other processes on the machine.

Five storage backends.

Choose where secrets are stored. All backends encrypt at rest. Secrets exist only in the backend and get injected into process memory at runtime.

Local

Default

AES-256-GCM encrypted file on disk. No external dependencies. Works everywhere Node.js runs.

Zero setup
Single machine
Filesystem auth

OS Keychain

macOS and Linux

macOS Keychain or Linux Secret Service. Hardware backed encryption on Apple Silicon. OS login auth.

OS level encryption
Device local sync
OS login auth

1Password

Recommended for teams

Dedicated vault via the op CLI. Biometric unlock (Touch ID). Service accounts for CI/CD. Cross device sync.

Biometric auth
Cross device sync
CI/CD via service accounts

HashiCorp Vault

Enterprise or self hosted

KV v2 secrets engine. Cross device and cross cluster sync. Vault token authentication. Namespace isolation.

Cross cluster sync
Vault token auth
Namespace isolation

GCP Secret Manager

Google Cloud

Google Cloud Secret Manager with IAM integration. Auto versioned. Native to Cloud Run, GKE, and Cloud Functions.

IAM integrated auth
Automatic versioning
Cloud native sync

terminal

$ npx secretless-ai backend set 1password
  Backend set to 1password.

$ npx secretless-ai migrate --from local --to 1password
  Migrating 4 secrets from local to 1password.
  Done. All secrets migrated.

Secret management.

Store, list, and inject secrets without exposing them to AI tools. Import from .env files or set them individually.

Store and list secrets

$ npx secretless-ai secret set STRIPE_KEY=sk_live_...
  Stored STRIPE_KEY.

$ npx secretless-ai secret list
  ANTHROPIC_API_KEY
  OPENAI_API_KEY
  STRIPE_KEY
  DATABASE_URL

Inject at runtime

# Inject all secrets into a command
$ npx secretless-ai run -- npm test

# Inject only specific keys
$ npx secretless-ai run --only STRIPE_KEY -- npm start

# Import from existing .env files
$ npx secretless-ai import --detect
  Found .env (4 secrets).
  Found .env.local (2 secrets).
  Imported 6 secrets.

MCP secret protection.

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

Encrypt MCP secrets

$ npx secretless-ai protect-mcp

  Secretless MCP protection.

  Scanned 1 client.

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

  3 secrets encrypted across 3 servers.

Before. Plaintext keys in JSON.

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "@stripe/mcp"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_live_51Hx..."
      }
    }
  }
}

After. Encrypted, injected at runtime.

{
  "mcpServers": {
    "stripe": {
      "command": "secretless-mcp",
      "args": ["npx", "-y", "@stripe/mcp"],
      "env": {}
    }
  }
}

Allowlist and custom rules.

A gitignore style .secretlessignore file suppresses known false positives. Custom deny rules add organization specific patterns. Both contain patterns, not secrets, so they are safe to commit.

secretless-rules.yml

# Block org specific environment variables
env:
  - ACME_*
  - INTERNAL_DB_*

# Block proprietary config files
files:
  - "*.corp-secret"
  - "internal-config.*"

# Block commands that access internal systems
bash:
  - "curl*internal.corp.com*"
  - "vault read*"

Initialize rules

$ npx secretless-ai rules init

Glob patterns for env vars, files, and bash commands.
Extends built in rules, does not replace them.
Safe to commit. Contains patterns, not secrets.

Test and manage rules

Preview what deny rules a pattern generates before applying. List active rules to audit coverage.

$ npx secretless-ai rules test "ACME_*"
$ npx secretless-ai rules list

AI safe guard.

When an AI tool tries to read a secret value, secretless detects the non interactive context and blocks output.

AI tool runs this command

$ npx secretless-ai secret get STRIPE_KEY

  secretless: Blocked.
  Secret values cannot be read in non interactive contexts.
  AI tools capture stdout, which would expose the secret in their context.

  To inject secrets into a command:
    npx secretless-ai run -- <command>

Direct terminal access (a human at a real TTY) works normally. The guard detects non interactive execution, which is how AI tools run commands, and refuses to output secret values.

Credential scope discovery.

Credential permissions change over time as platforms evolve. Scope discovery records what a stored credential can do as a baseline, and a later check reports the permissions added since.

Discover and check scope drift

# Discover current permissions, save baseline
$ npx secretless-ai scope discover MY_GCP_KEY

# Compare current permissions to saved baseline
$ npx secretless-ai scope check MY_GCP_KEY

# List all stored baselines
$ npx secretless-ai scope list

# Clear a baseline to re discover
$ npx secretless-ai scope reset MY_GCP_KEY

Supported providers

GCP. Service account key JSON via testIamPermissions.
HashiCorp Vault. Token prefix detection via capabilities-self.
AWS. Access key prefix detection via STS plus IAM introspection.

All providers use self inspection APIs. No additional permissions required.

Runs on demand

The scope commands run when they are called; nothing schedules them. The broker does not read scope baselines: since 0.22.1 a policy rule that names scopeCheck is refused when the policy loads.

Credential broker and data loss prevention.

Runtime credential access control and AI transcript scanning. Detect leaked credentials in shell history and conversation logs.

Credential broker

secretless-ai broker

Identity aware credential access control daemon. Enforces deny all policies so each credential is only accessible to authorized agents. Supports AIM identity verification, trust score constraints, and rate limiting.

$ npx secretless-ai broker start
$ npx secretless-ai broker status
$ npx secretless-ai broker stop

Deny all by default.
Per credential policy rules.
AIM identity plus trust score constraints.

Data loss prevention

secretless-ai scan / clean / watch

Scan AI tool transcripts, shell history, and conversation logs for leaked credentials. Redact findings in place or preview with dry run. Set up real time monitoring to catch leaks as they happen.

# Scan shell history for credentials
$ npx secretless-ai scan --history

# Redact credentials in shell history
$ npx secretless-ai clean-history

# Scan and redact AI transcripts
$ npx secretless-ai clean
$ npx secretless-ai clean --last

# Start real time transcript monitoring
$ npx secretless-ai watch start

Shell history scanning and redaction.
AI transcript credential detection.
Real time watch daemon with system daemon support.
Dry run mode for safe preview.

Supported AI tools.

Six AI coding tools. What Secretless installs differs by tool.

Tool	Protection method	How it is applied
Claude Code	`PreToolUse hook plus deny rules and instructions`	Denied before the tool call runs
Cursor	`.cursorrules instructions`	Instruction file, not enforced
GitHub Copilot	`.github/copilot-instructions.md`	Instruction file, not enforced
Windsurf	`.windsurfrules instructions`	Instruction file, not enforced
Cline	`.clinerules instructions`	Instruction file, not enforced
Aider	`.aiderignore patterns`	Ignore patterns the tool applies

In Claude Code, Secretless uses hooks: a script runs before the assistant's tool calls and denies one that would read a credential file. It is a gate on the assistant's tool path, not a boundary around the machine. For the other tools the protection is an instruction file or ignore patterns.

What is covered.

File patterns that should never enter AI context, plus runtime credential pattern detection from the open source @opena2a/credential-patterns catalog.

File patterns

Environment files
.env, .env.*, .env.local, .env.production
Private keys
*.key, *.pem, *.p12, *.pfx, *.crt
Cloud credentials
.aws/credentials, .ssh/*, .docker/config.json
Package auth
.npmrc, .pypirc, .git-credentials
Infrastructure
*.tfstate, *.tfvars
Secret directories
secrets/, credentials/

Credential pattern families

Anthropic API keys
OpenAI keys (project and legacy)
AWS access keys plus secret keys
GitHub PATs (classic and fine grained)
Slack tokens (bot, user, webhook)
Google API keys plus OAuth secrets
Stripe live and test keys
SendGrid keys
Supabase service and anon keys
Azure keys plus connection strings
GitLab tokens (personal, project, group)
Twilio account SID plus auth token
Mailgun API keys
MongoDB connection URIs
JWTs and bearer tokens

Plus more in the catalog. Versioned and shared with hackmyagent and opena2a-cli.

Git protection and continuous verification.

Pre commit and pre push hooks scan staged files for secrets before they enter git history. The verify command audits installed protections on demand.

git hook install

$ npx secretless-ai hook install
  Installed pre-commit hook.

$ npx secretless-ai hook status
  Pre-commit hook: installed.
  Patterns active across all credential families.

verify

$ npx secretless-ai verify

  Auditing installed protections.
  + Claude Code hook present.
  + .cursorrules instructions present.
  + .secretlessignore loaded.
  + Pre-commit hook installed.

  All protections verified.

Wires into agent identity.

When the credential broker runs, every credential access is attributable to a cryptographically signed agent identity. Trust score and policy gates apply per agent.

Agent attribution

Every broker decision is logged against an AIM identity, not a process or shell.

Trust score gates

Policy rules can require a minimum trust score. Suspended or revoked agents lose credential access immediately.

Shared CLI surface

opena2a-cli exposes secretless protect, broker, and scan commands through a unified surface.

Get started in 30 seconds.

No signup. No configuration. One command auto detects your AI tools, installs the right protections, and stores secrets in an encrypted backend.

$npx secretless-ai init

Star on GitHub Documentation