cd /news/ai-agents/securely-share-passwords-with-your-a… · home › topics › ai-agents › article
[ARTICLE · art-173931] src=github.com ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

Securely share passwords with your Agents

A tool called secret-scratch, published as the TypeScript library @inixiative/secret-scratch, intercepts secrets typed into coding-agent chats before inference, replacing them with opaque references such as †m1.1 and storing the real values in a 0600 scratch-pad file under ~/.secret-scratch/. The tool ships as a drop-in Agent Client Protocol middleware proxy that wraps Claude ACP, Codex ACP and Gemini CLI ACP agents, as a stdio MCP server exposing the secret_scratch and secret_pipe tools, and as a library for custom harnesses, with zero runtime dependencies on Node.js 20+ and Bun 1.4+. It matters because pasting an API key or private key into an agent chat otherwise sends the secret to the model provider and leaves it in session transcripts, tool logs and crash dumps.

key takeaway

Prefix secrets with $$ (or rely on recognized shapes like sk-, ghp_, AKIA, AIza and PEM keys) so the ACP proxy lifts them into a 0600 scratch pad and the agent only ever sees a † reference, then use secret_pipe to pass the value to a command's stdin.

read5 min views5 publishedNov 21, 2026
Securely share passwords with your Agents
Image: Michielbdejong (auto-discovered)

Securely send secrets to your AI agent with $$value without the LLM, transcript, or logs ever seeing them.

You type:       Put $$sk_live_9876543210 into .env.local as STRIPE_KEY, then push it to GitHub Actions.
Agent sees:     Put †m1.1 into .env.local as STRIPE_KEY, then push it to GitHub Actions.
Agent calls:    secret_scratch(action: "env", ref: "†m1.1", path: ".env.local", key: "STRIPE_KEY")
                secret_pipe(envFile: ".env.local", key: "STRIPE_KEY", command: "gh secret set STRIPE_KEY")
Agent gets:     { ok: true, exitCode: 0 }
Agent tries:    cat .env.local  ->  BLOCKED (.env.local is held by secret-scratch)

Zero runtime dependencies. Works with Node.js 20+ and Bun 1.4+. Ships three ways to integrate:

  1. Drop-in Agent Client Protocol (ACP) middleware proxy (secret-scratch -- <acp-agent-command> ) wrapping Claude ACP, Codex ACP, Gemini CLI ACP, or any ACP agent inside hosts such as Zed and JetBrains.
  2. Stdio MCP server (secret-scratch mcp ) exposingsecret_scratch andsecret_pipe .
  3. TypeScript library (@inixiative/secret-scratch ) for custom harnesses and agent runtimes.

Pasting an API key or private key into a coding agent chat sends the secret to the model provider, writes it into session transcripts, and leaves it in tool logs and crash dumps.

secret-scratch intercepts secrets before they reach the model:

  1. Lift before inference. Any word prefixed with$$ (plus common shaped tokens such assk-... ,ghp_... ,AKIA... ,AIza... , and PEM private keys if you forget the prefix) is moved into a0600 per-thread scratch pad file in~/.secret-scratch/ (0700 ) and replaced with an opaque reference like†m1.1 .
  2. Use by reference. The agent receives two MCP tools:secret_scratch (list ,env ,write ,consume ) andsecret_pipe (pipes a secret to a shell command'sstdin , discardsstdout andstderr , returns onlyexitCode ).
  3. Block access to held files. Every file written bysecret_scratch is recorded inheld-files.json . ACP permission requests, filesystem calls, and terminal calls targeting a held file, a.private path, or the scratch pad directory are denied at the proxy boundary.
  4. Scrub outgoing updates. Held values (6+ characters) are scrubbed from outgoingsession/update frames back into their† reference as defense in depth.

Wrap any ACP agent command with npx @inixiative/secret-scratch --:

npx -y @inixiative/secret-scratch -- <your-acp-agent-command> [args...]

Or install globally:

npm install -g @inixiative/secret-scratch
secret-scratch -- <your-acp-agent-command> [args...]
{
  "agent_servers": {
    "Claude Code (secret-scratch)": {
      "command": "npx",
      "args": ["-y", "@inixiative/secret-scratch", "--", "claude-agent-acp"]
    },
    "Codex (secret-scratch)": {
      "command": "npx",
      "args": ["-y", "@inixiative/secret-scratch", "--", "codex-acp"]
    },
    "Gemini CLI (secret-scratch)": {
      "command": "npx",
      "args": ["-y", "@inixiative/secret-scratch", "--", "gemini", "--experimental-acp"]
    }
  }
}

When a session starts, the proxy:

  • Injects the secret-scratch stdio MCP server intosession/new ,session/load ,session/resume , andsession/fork (preserving all other MCP servers).
  • Lifts $$value markers and recognised secret shapes onsession/prompt before forwarding to the agent, attaching usage guidance on the first turn that carries a secret.
  • Rejects session/request_permission ,fs/read_text_file ,fs/write_text_file , andterminal/create calls targeting held files,.private paths, or~/.secret-scratch .
  • Scrubs held values out of session/update notifications.
secret-scratch [options] -- <acp-agent-command> [args...]
secret-scratch mcp --dir <path> --thread <id> [--cwd <path>]
secret-scratch list [--dir <path>] [--thread <id>]
secret-scratch clear <thread> [--dir <path>]

Options:
  --dir <path>          Scratch pad directory (default: ~/.secret-scratch)
  --private <glob>      Extra private path glob to block (repeatable)
  --no-lift-shaped      Only lift explicit $$value markers
  --no-scrub            Disable scrubbing held values from session/update
js
import {
  SecretScratchPad,
  SHAPED_SECRET_PATTERNS,
  privatePathGate,
  scratchTarget,
} from '@inixiative/secret-scratch';

const pad = new SecretScratchPad('~/.secret-scratch');

// 1. Lift before sending to the LLM
const { text, refs } = pad.lift(
  'Set STRIPE_KEY to $$sk_live_example1234567890 in .env.local',
  { thread: 'thread_1', message: 'm1' },
  { patterns: SHAPED_SECRET_PATTERNS },
);
// text === 'Set STRIPE_KEY to †m1.1 in .env.local'

// 2. Write safely inside cwd (rejects .., symlink escapes, .git, .claude, .ssh)
const target = scratchTarget(process.cwd(), '.env.local');
pad.env({ ref: refs[0]! }, 'thread_1', target, 'STRIPE_KEY', { consume: true });

// 3. Pipe straight to a CLI without returning stdout/stderr
const { exitCode } = await pad.pipe(
  { envFile: target, key: 'STRIPE_KEY' },
  'thread_1',
  'gh secret set STRIPE_KEY',
);

// 4. Gate agent file/shell tools
const gate = privatePathGate({
  scratchDir: pad.dir,
  heldFiles: pad.heldFiles(),
});
gate({ toolName: 'Bash', toolInput: { command: 'cat .env.local' } });
// { behavior: 'deny', message: '.env.local is private: ...' }

See docs/VERBS.md for the complete public API table.

  • Prevents accidental exposure to the LLM, agent transcripts, and tool output. Secrets lifted at the prompt boundary never enter model context, prompt caches, or downstream agent session transcripts.secret_pipe discardsstdout andstderr and kills the whole process group on timeout.
  • On-disk storage is 0600 plaintext in a 0700 directory. Scratch pads live at~/.secret-scratch/<thread>.pad until consumed or cleared (secret-scratch clear <thread> ). They protect against LLM and transcript leakage, not against another process running as your OS user.
  • Shell gating and secret_pipe defend against accidental leaks, not a hostile sandbox. If a downstream agent runs shell commands directly inside its own process without asking the ACP host viasession/request_permission orterminal/create , the ACP proxy cannot intercept those local subprocess calls. Likewise, an adversarial model that can pass arbitrary shell commands tosecret_pipe could write stdin to an untracked file or encode bytes in the exit code. For enforcement against an untrusted model, pairsecret-scratch with an OS sandbox or a harness that routes all tool calls throughprivatePathGate and restricts allowed pipe commands.
  • Single-word marker.$$value lifts up to the next whitespace. Multi-line secrets (such as PEM private keys) are lifted by shape automatically; arbitrary multi-line secrets should be passed by file or env key rather than$$ .

Extracted from Foundry, a source-available (BSL 1.1) local agent harness built by inixiative.

MIT

── more in #ai-agents 4 stories · sorted by recency
── more on @secret-scratch 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/securely-share-passw…] indexed:0 read:5min 2026-11-21 · —