{"slug": "i-built-a-way-for-coding-agents-to-use-secrets-with-o-seeing-them", "title": "I built a way for coding agents to use secrets with O seeing them", "summary": "Developer pdumicz released Secret Shuttle, a local bridge that lets AI coding agents use secrets like API keys without ever seeing the plaintext values. The tool stores secrets in a local daemon vault and exposes only references and metadata to agents, closing a security gap in existing secret management tools. Currently in beta, it supports Claude Code, Codex, Cursor, and Copilot.", "body_md": "Reading this as an AI coding agent?Your starting point is[skills/secret-shuttle/SKILL.md](raw URL:`https://raw.githubusercontent.com/pdumicz/secret-shuttle/main/skills/secret-shuttle/SKILL.md`\n\n). The SKILL is your operational manual; this README is for humans.\n\nLet AI agents use secrets without seeing them.\n\n[ ▶ Walk through the interactive demo →](https://pdumicz.github.io/secret-shuttle/demo/?scene=0) · opens on the one-approval\n\n`provision`\n\nflow, then a 9-scene click-through of the low-level mechanics — a dev shipping a Stripe webhook secret to Vercel prod without ever seeing the value.\n\nStatus: 0.5.0 — beta.The architecture has been through multiple bursts of adversarial security review with fixes shipped at each gate. Not yet independently audited; recommend test accounts and rotating tokens until that audit lands. Suitable for development workflows and prototype deployments.\n\nSecret Shuttle is a local bridge that lets coding agents — Claude Code, Codex, Cursor, browser-using agents — capture, generate, store, compare, and inject secrets through browser and CLI workflows. The agent sees only refs like `ss://stripe/prod/STRIPE_WEBHOOK_SECRET`\n\n, fingerprints, field metadata, and status — never the raw value.\n\nThose tools sync secrets across environments — they assume a human or a CI runner is the consumer. Secret Shuttle assumes an AI coding agent is the consumer, and treats every plaintext touch as a leak vector.\n\n| Tool | Where secrets live | Who sees plaintext | Agent-aware? |\n|---|---|---|---|\n| Doppler / Infisical | Cloud vault | Anyone with read access (incl. agents querying it) | No — sync model |\n| 1Password CLI | OS keychain | Caller process; `op read` writes to stdout |\nNo |\n| Vercel envs (et al.) | Vendor backend | Engineers via dashboard; build runners via env | No |\nSecret Shuttle |\nLocal daemon vault | Only the daemon's child processes (templates) | Yes — agent sees only refs |\n\nIf your secrets already live in a sync tool and an agent never touches them, you don't need Secret Shuttle. If you have an agent writing code that needs to ship secrets to Vercel/GitHub/etc, and you want the agent to do that without the bytes entering its context — that's the gap this closes.\n\n```\nnpx secret-shuttle init\n```\n\nThis starts the local daemon and walks you through creating a vault passphrase in a local web window that only the daemon owns — the CLI never reads it. (Touch ID isn't a first-run prompt: it's how *later* unlocks work once the vault key is enrolled in the OS keychain. `init`\n\nenrols the keychain by default when it creates the vault — pass `--no-keychain`\n\nto opt out, or run `secret-shuttle keychain enable`\n\nlater.) After `init`\n\ncompletes the daemon is running and you are ready to use the CLI or hand it to an agent.\n\nIf you're configuring an agent to use Secret Shuttle, paste this raw skill URL into the agent (it's the canonical operating manual):\n\n```\nhttps://raw.githubusercontent.com/pdumicz/secret-shuttle/main/skills/secret-shuttle/SKILL.md\n```\n\nIf you have the CLI installed locally, run one of these from your project root and the platform-specific instructions file is written for you:\n\n```\nsecret-shuttle agent install claude # → .claude/skills/secret-shuttle/SKILL.md\nsecret-shuttle agent install codex # → AGENTS.md snippet (marker-managed)\nsecret-shuttle agent install cursor # → .cursor/rules/secret-shuttle.mdc\nsecret-shuttle agent install copilot # → .github/copilot-instructions.md snippet (marker-managed)\nsecret-shuttle agent print-skill-url # → the raw URL (one line, paste it)\n```\n\nSnippet targets (AGENTS.md, .github/copilot-instructions.md) wrap the Secret Shuttle block in ``\n\n/ ``\n\nmarkers — re-running `agent install`\n\nonly replaces the marked block, never the surrounding content.\n\n```\nAgent CLI (untrusted client)\n |\n | localhost HTTP, bearer token from ~/.secret-shuttle/daemon-socket.json\n v\nSecret Shuttle daemon\n - vault key (in memory only, after passphrase unlock through web UI)\n - approval grants (single-use, 2-min TTL, bound to action/ref/domain/target/field/template)\n - browser owner — talks raw CDP over a pipe\n - filtered CDP WebSocket proxy exposed to the agent\n - safe command-template runner (no shell, no arbitrary commands)\n```\n\nThe daemon owns every secret moment. The agent sees refs and status, never raw values, never the raw Chrome CDP URL, never the vault key.\n\n**CLI templates (most reliable).** Push a secret to Vercel / GitHub Actions / Cloudflare / Supabase — the value goes to the vendor's own CLI, never through the agent. This is the path the hero demo above shows.**Universal browser handoff (experimental).** Your agent drives*any*vendor portal with its normal browser tool, and hands off only the secret moment — it marks the field, the daemon types/reads it under blind mode with the agent's view severed. No per-vendor recipe; it works on a portal nobody integrated.\n\nThe browser path is early (v0.5, best-effort, pending real-page verification): the guarantee is \"the agent never sees the plaintext,\" **not** \"a hostile destination page can't exfiltrate a secret you enter.\" See [SECURITY.md](/pdumicz/secret-shuttle/blob/main/SECURITY.md); for untrusted destinations, prefer the CLI path.\n\n```\nsecret-shuttle provision --secret INTERNAL_CRON_SECRET \\\n --from random_32_bytes \\\n --environment production \\\n --to vercel:production\n# (production secret — approve in the window the daemon opens)\n\nsecret-shuttle secrets list --env production\nsecret-shuttle secrets get-ref ss://local/prod/INTERNAL_CRON_SECRET\nsecret-shuttle audit --since=1d\n```\n\nFor the full browser walkthrough see [examples/stripe-to-vercel/walkthrough.md](/pdumicz/secret-shuttle/blob/main/examples/stripe-to-vercel/walkthrough.md).\n\n```\nsecret-shuttle template list\nsecret-shuttle template run vercel-env-add \\\n --ref ss://stripe/prod/STRIPE_SECRET_KEY \\\n --param name=STRIPE_SECRET_KEY \\\n --param environment=production\n```\n\nTemplates run vetted binaries with `shell: false`\n\n, absolute paths only, and never echo stdout/stderr back to the agent.\n\n- TypeScript CLI distributed as\n`secret-shuttle`\n\n- Local daemon with bearer-authenticated HTTP API on 127.0.0.1\n- Passphrase-derived envelope around the vault master key (scrypt + AES-256-GCM)\n`ss://source/env/name`\n\nrefs- Generate, capture (focused field / selection), inject, compare — all routed through the daemon\n- Inject runs inside a daemon-managed blind window (no manual\n`blind start`\n\n) - Agentic blind transactions:\n`inject-submit`\n\nwrites a stored secret into a marked field, clicks the marked submit control, waits for the approved success marker, and proves the raw secret is absent from every daemon-observable surface before auto-resuming.`reveal-capture`\n\nclicks a marked reveal control, captures the now-visible bytes from a marked field or ancestor container, hides them, and writes them to the vault only after the absence proof passes `secret-shuttle browser mark focused|pick --as