Secret Management and Trust Boundaries for Claude Code — A Production Guide for the Agent Era

Three Practical Injection Patterns and When to Use Them

Almost every realistic local-development setup falls into one of three patterns. The choice between them is not about absolute security — all three can be made acceptable with discipline — but about which trade-offs match your workflow.

Pattern A: Plain .env Files (Minimum Viable Defense)

The cheapest option, and the riskiest. It is acceptable for short experiments only when paired with .gitignore discipline and an automated commit-time scanner. I include it here not as a recommendation but because almost every project starts here, and you should know exactly what you are getting before you decide whether to graduate.

# .env (Git-ignored)
ANTHROPIC_API_KEY=sk-ant-XXXXXXXXXXXX
 
# package.json — load at startup
"scripts": {
  "start": "node --env-file=.env server.js"
}

Add both .env and .env.* to .gitignore and run a pre-commit secret scanner (covered later in this guide). The reason this pattern fails over time is not that the file gets exposed once — it is that it survives every system migration, every laptop replacement, every "let me copy my dotfiles to the new machine" moment. Every one of those is a chance for the file to land somewhere it does not belong. This pattern is fine for prototyping; it is not fine as a long-term posture for production code.

Pattern B: On-Demand Injection With 1Password CLI or Doppler (Recommended)

Store secrets in a vault and resolve them at process launch. This is my default for serious work, because the secret only lives in Layer 4 for the lifetime of the command. It also produces a workflow that is easier than Pattern A in practice, despite sounding more complex on paper.

# Sign in once per session
eval "$(op signin)"
 
# .env.template (committed to Git — contains references, not values)
ANTHROPIC_API_KEY=op://Personal/Anthropic/api-key
DATABASE_URL=op://Personal/Supabase/connection-string
 
# Run with secrets injected just for this process
op run --env-file=.env.template -- npm run start

The killer property is that .env.template is safe to commit. New machines, CI runners, and pair-programming sessions can reproduce the environment without any secret changing hands. The template doubles as documentation: any new contributor reading it sees exactly which secrets the application needs and where to provision them. Doppler offers an equivalent workflow with doppler run -- npm start, plus convenient access controls when you grow into a small team — you can grant a teammate access to the staging vault but not the production vault, with a single click.

There are a few sharp edges worth knowing about. First, op signin produces a session token that lives in your shell environment for a configurable duration. Treat that token as a secret in its own right. Second, op run will fail loudly if any reference cannot be resolved, which is the behavior you want — you would rather a deploy fail than silently launch with a missing key. Third, on shared workstations, lock your 1Password app when stepping away; an unlocked vault makes every script in this section moot.

Pattern C: OS Keychain at Launch (Solo Mac Workflow)

If you are a single developer on macOS, the lightest viable setup is to fetch from Keychain in a launcher script. This pattern shines when you do not want a third-party vault in your stack but still want better-than-.env security.

#!/usr/bin/env bash
# scripts/start-with-keychain.sh
 
set -euo pipefail
 
# Pre-populate with: security add-generic-password -a "$USER" -s "anthropic-api-key" -w "sk-ant-..."
ANTHROPIC_API_KEY=$(security find-generic-password \
  -a "$USER" \
  -s "anthropic-api-key" \
  -w 2>/dev/null) || {
    echo "❌ Anthropic API key not found in Keychain" >&2
    exit 1
  }
 
# Replace this shell with the server, exposing the key only to that process
ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" exec node server.js

Two details matter. exec replaces the shell instead of forking, so the key never touches your interactive environment. set -euo pipefail ensures the script aborts loudly if the lookup fails — without it you risk silently launching the server with an empty key, which is worse than failing to launch at all. The error-out-on-missing behavior is essential for the same reason op run fails closed: a process running with an empty credential will produce confusing downstream errors that take ten times longer to debug than an obvious "key not found" failure at launch.

You can take the pattern further by using security add-generic-password -T /usr/bin/security to restrict which binaries can read the entry without prompting, and by adding -A (always allow) only for the launchers you trust. For team workflows you would graduate to Pattern B; Pattern C earns its place by being completely vault-free.

Choose by the product of applications you run and people who touch them. Solo with one or two apps: pattern C. Solo with several: pattern B. Any size of team: pattern B by default, or HashiCorp Vault if you need centralized policy with audit trails that tie individual operators to individual key uses.

Handing Secrets to MCP Servers Without Spreading Them

Passing secrets to MCP servers is where most teams stumble. The official examples often write keys directly into claude_desktop_config.json's env field, and that path of least resistance becomes a long-term liability.

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "sbp_XXXXXXXXXXXXX"
      }
    }
  }
}

That file lives in your home directory and gets opened constantly — during screen shares, during onboarding walkthroughs, during quick "let me show you my setup" moments. It also gets backed up automatically by most macOS users, syncs to iCloud Drive if you keep your home folder there, and shows up in find ~ -name "*.json" searches. Every one of those touches is a chance for the secret to escape its intended scope.

I switched to a launcher-wrapper pattern instead, and the configuration shrunk from "spread the secret across multiple JSON fields" to "no secret in the config at all."

{
  "mcpServers": {
    "supabase": {
      "command": "/Users/me/.claude/mcp-launchers/supabase.sh",
      "args": []
    }
  }
}

#!/usr/bin/env bash
# ~/.claude/mcp-launchers/supabase.sh
set -euo pipefail
 
TOKEN=$(security find-generic-password -a "$USER" -s "supabase-access-token" -w 2>/dev/null) || {
  echo "FATAL: supabase token missing" >&2
  exit 1
}
 
export SUPABASE_ACCESS_TOKEN="$TOKEN"
exec npx -y @supabase/mcp-server-supabase "$@"

Three benefits emerge. The config file becomes safe to share — committing it to a dotfiles repo is suddenly a non-issue. The wrapper is a natural place to add logging, audit hooks, or step-up confirmation later; you can require a Touch ID prompt before the wrapper proceeds, for instance. And rotation becomes trivial — the wrapper is the only thing that needs to change when a key cycles, and the change is local to a single file you control.

A subtlety worth flagging: when MCP servers fork their own subprocesses, the environment you exported in the wrapper inherits down. If the MCP server itself calls another tool that prints process.env, your secret may surface in logs you did not anticipate. Audit the MCP servers you wrap with this pattern by reading their source or running them with strace/dtrace to confirm what they actually do with the credentials you hand them.

If your .env file refuses to load when wired into Claude Code, the diagnostic checklist in Claude Code env not loaded — troubleshooting guide is the fastest path to a fix; you can use that workflow alongside the wrapper pattern here.

Mechanical Defenses: Pre-Commit and PreToolUse Together

Human attention is not a defense. Anyone who has accidentally committed a .env file knows that the moment of distraction comes for everyone eventually. I install automatic checks at two boundaries: the commit boundary and the agent execution boundary. Together they catch the overwhelming majority of accidental disclosures before they reach the network.

Commit Boundary: pre-commit Hook With gitleaks

#!/usr/bin/env bash
# .git/hooks/pre-commit
set -euo pipefail
 
if ! command -v gitleaks >/dev/null 2>&1; then
  echo "⚠️  gitleaks not installed — skipping secret scan" >&2
  exit 0
fi
 
gitleaks protect --staged --redact --verbose || {
  echo "" >&2
  echo "🚨 Potential secret detected in staged changes" >&2
  echo "   Review the output above. To bypass intentionally:" >&2
  echo "   git commit --no-verify   (use with extreme caution)" >&2
  exit 1
}

The --redact flag is essential: when the hook fails inside CI, you do not want the failing log line to leak the actual secret to anyone who can read the build logs. Treat --no-verify as a documented exception, not a habit, and consider requiring a paired review whenever it is invoked. For teams, install the same hook globally via git config --global core.hooksPath ~/.config/git/hooks so that no individual repository can opt out by accident.

A complementary practice is to run gitleaks detect --no-git periodically against your home directory and ~/.config. Secrets often end up in places Git does not see — text editor session backups, browser-saved credentials, half-finished blog post drafts. A monthly sweep catches the long-tail cases that pre-commit cannot.

Agent Execution Boundary: PreToolUse Hook

Claude Code's PreToolUse hooks let you inspect a Bash command before it runs and decide to block it. The example below catches the most common patterns by which secrets accidentally escape through the agent.

#!/usr/bin/env bash
# .claude/hooks/pretooluse-bash-secret-guard.sh
 
set -euo pipefail
 
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
 
DANGER_PATTERNS=(
  'printenv($|[^A-Z_])'
  '\benv\b\s*$'
  'cat\s+.*\.env'
  'cat\s+.*credentials'
  'curl\s+.*-d\s+.*\$\{?[A-Z_]+API_KEY'
  'echo\s+.*\$\{?[A-Z_]+_(KEY|TOKEN|SECRET)'
)
 
for pattern in "${DANGER_PATTERNS[@]}"; do
  if echo "$COMMAND" | grep -qE "$pattern"; then
    cat <<JSON
{
  "decision": "block",
  "reason": "Command matches secret-exposure pattern: $pattern. If intentional, run manually outside Claude Code."
}
JSON
    exit 0
  fi
done
 
echo '{"decision": "approve"}'

Wire it up in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/pretooluse-bash-secret-guard.sh" }
        ]
      }
    ]
  }
}

Tuning matters. Start permissive, log every match for a week, and tighten the regex set against real traffic. A guard that triggers on every legitimate read of cat env-template.txt will be disabled within a day; one that quietly catches cat .env | curl -d @- is the one you want. The pragmatic rule of thumb I use is: each false positive costs me roughly fifteen seconds of friction; each true positive saves me hours of incident response. Optimize for the latter.

A useful extension is to add a second hook that records every allowed command into an append-only log. When you eventually need to do an incident review, having a complete record of what the agent ran during each session — independent of Claude Code's own conversation history — is invaluable. Compress and rotate the log monthly to keep disk usage bounded.

Rotation and Audit That Stay Lightweight

A "perfect" rotation policy is heavy and never gets followed by a solo developer. I keep three things and let everything else go.

First, calendar-driven rotation. A scheduled task posts a TODO every 90 days that says "rotate the production keys for site X." Memory does not work; calendars do. The interval depends on the credential's blast radius — payment processor keys I rotate every 60 days, while read-only analytics tokens stretch to 180. Tie the cadence to the realistic worst-case impact, not to a one-size-fits-all corporate policy that will get ignored.

Second, structured audit logs. The MCP wrapper appends a JSONL entry every time it pulls a key.

LOG_FILE="$HOME/.claude/logs/secret-access.jsonl"
mkdir -p "$(dirname "$LOG_FILE")"
 
jq -n \
  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg key "supabase-access-token" \
  --arg pid "$$" \
  --arg parent "${PPID:-unknown}" \
  '{ts: $ts, key: $key, pid: $pid, parent_pid: $parent}' \
  >> "$LOG_FILE"

JSONL is trivially queryable with jq, and after a few weeks of data you can spot anomalies like a 3 a.m. burst of access or unfamiliar parent process IDs. Pipe the log through a simple jq query each morning — jq 'select(.ts > "'"$(date -d 'yesterday' -u +%Y-%m-%dT%H:%M:%SZ)"'")' < secret-access.jsonl — and skim the result. The habit takes thirty seconds and surfaces problems weeks before they escalate.

Third, a written incident runbook. When something leaks, you do not want to be improvising. A runbooks/secret-leak.md file with five numbered steps — revoke in console, rotate in vault, restart consumers, scan logs, notify stakeholders — turns a panic moment into a checklist. Keep it short enough to fit on one screen, version it like code, and rehearse it once a quarter on a non-production credential. The first time you read your own runbook under pressure, you will discover gaps; better to find them on a drill day than during a real leak.

Five Pitfalls I Actually Hit

These are the mistakes I have made in production, in roughly the order I learned them. None of them are exotic — they are the failure modes that happen when ordinary care meets ordinary distractions.

What follows is not a comprehensive taxonomy of secret-management failures — entire books have been written on that subject — but a curated list of the failures that have actually happened to me while running automated content pipelines on Claude Code. If you are operating in a similar shape (one developer, multiple sites, agents driving routine commits), these are the ones most likely to bite you first. Treat the list as a pre-flight checklist: read it before your next big change to a credential-handling pathway, and you will dodge most of the surprises waiting in the next few months of operation.

1. Committing claude_desktop_config.json with real keys in env. The temptation to share a working setup is strong. Split into claude_desktop_config.shared.json and claude_desktop_config.local.json and merge them in a launch script. The .shared.json file documents structure and references; the .local.json overlay supplies real values and stays out of Git. New contributors get a reproducible setup; nobody ships a key.

2. Shell history capture. export API_KEY=xxx lives in ~/.bash_history forever. Set HISTCONTROL=ignorespace and prefix any command containing a secret with a single space to keep it out of history. While you are at it, add unset HISTFILE to scripts that handle credentials in transit, and audit your ~/.zsh_history for already-captured secrets — the past sometimes needs cleaning, not just the future.

3. Logging process.env in debug output. A single misplaced console.log(process.env) in a hot code path becomes a CI artifact you cannot redact after the fact. An eslint rule that forbids serializing process.env is worth its weight in incident-response time. The same applies to Python — write a small lint check that flags dict(os.environ) and repr(os.environ) patterns. Errors thrown by libraries that include the request headers in their messages are another sneaky path; sanitize error reporters before they reach Sentry or its equivalents.

4. Over-privileged MCP servers. Handing a Supabase MCP a service-role key bypasses RLS. The agent ends up with read access to every row in every table. Default to anon keys with proper RLS policies, and split high-privilege operations into a dedicated MCP server with its own rotating credential. The operational cost of running two MCP servers is small; the cost of an agent accidentally reading customer data because it asked the wrong question is enormous.

5. Predictable secret names. Patterns like OPENAI_API_KEY and STRIPE_SECRET_KEY are trivial for an attacker to grep. Renaming the in-process variable to something neutral like INTERNAL_AI_PROVIDER_TOKEN raises the cost of opportunistic exploitation. It is not a primary defense, but it shifts the easy attacks elsewhere. I treat this as the security equivalent of a screen door — it stops nothing determined, but it filters out the casual.

The CI-side scanning techniques in Claude Code security vulnerability scanning compose well with this checklist; the two together form a reasonably tight web. Layered defenses are not redundant — they are the only kind of defense that survives contact with reality.

A Real Multi-Site Implementation

For reference, here is the secret topology behind Dolice Labs (Claude Lab, Gemini Lab, Antigravity Lab, Rork Lab). It is the concrete instantiation of every principle above, so you can see how the abstract trade-offs settle into actual file paths and shell scripts.

Each site has an isolated GitHub Personal Access Token, stored in its own 1Password vault. A committed .env.template references vault entries by op:// URI, so any new development environment can come online with one command:

# .env.template (committed)
GITHUB_TOKEN=op://Dolice-Labs/Claude-Lab-PAT/token
ANTHROPIC_API_KEY=op://Dolice-Labs/Anthropic/api-key
STRIPE_SECRET_KEY=op://Dolice-Labs/Stripe-Claude-Lab/secret-key
KV_NAMESPACE_ID=op://Dolice-Labs/Cloudflare-Claude-Lab/kv-namespace
 
# Bootstrap a fresh checkout
op run --env-file=.env.template -- npm install

Scheduled tasks invoke a unified launcher that picks the right vault from the site name and wraps the actual command with op run. The task body never mentions a secret directly — it only knows which site it is operating on. That separation is what keeps each task small enough to read and audit. Reviewing a scheduled task should be a five-minute exercise; if you have to chase secrets across multiple files to understand what it can access, the design has failed.

The launcher also installs a trap for SIGINT and SIGTERM so that when an agent run is interrupted (Ctrl-C in interactive mode, a scheduled-task cancellation, an OS-level signal), any temporary file containing decrypted secrets is removed before the script exits. Doing this consistently has saved me from leaving fragments of secrets behind on shared workstations more than once. The trap also writes a closing entry to the audit log, so that "session ended cleanly" versus "session was killed mid-execution" is recoverable from the JSONL trail without guessing.

One pattern worth borrowing: each site's launcher refuses to run if gitleaks is not installed and the .git/hooks/pre-commit is missing. That is, the rotation runbook treats the local guard as a prerequisite for any agent activity. Tying the dependency in code rather than documentation means it actually gets enforced — nobody can accidentally start a content-update task on a freshly cloned repo without the guard in place.

Secret management is not a project you finish — it is a discipline you grow alongside the rest of your operations. Of the eight topics above, the single highest-leverage move you can make today is migrating one frequently used key into 1Password or your OS keychain and pulling it through op run or security find-generic-password. Doing that once, end to end, makes every subsequent design choice feel obvious. Pick the most-used key in your stack and start there.