
blindkey
io.github.leocelis/blindkey
Local credential broker for AI agents: use secrets the agent never sees. No server, no proxy.
Documentation
๐ Blindkey
The local-first credential vault your AI agents can use โ but never see. No server. No account. One encrypted file. 102 testable security constraints. Rust.
Passwords. API keys. .env files. SSH and signing keys. Database URLs. The credentials your AI
coding agents touch every day.
Install ยท Documentation ยท Quickstart ยท Contributing ยท Support
[!WARNING] v1.1.1 โ not independently third-party audited โ keep your own backup of anything you store. Blindkey is functional: cryptographic core implemented and tested, working CLI and desktop app. On-disk format v1 is stable (ADR-0005) โ vault files from alpha releases open on 1.x without migration. See ROADMAP.md and SECURITY.md.
Why Blindkey exists
Developers now work alongside AI agents that read their files, run their shells, and โ if the
secret is sitting in a .env or an MCP config file โ read their credentials too.
GitGuardian found ~24,000 secrets exposed in public MCP configuration files on GitHub in
2026 (claude_desktop_config.json, .cursor/settings.json), over 2,100 of them still valid.
AI-assisted commits leak secrets at roughly 2x the platform-wide baseline. The industry's own
answer to this is converging on one principle: the agent should never hold or see the secret โ
something else should broker it in at the edge.
Blindkey is that something else, built local-first:
- No server, no account, no proxy in the traffic path. Other credential brokers for AI agents run as a cloud-platform service or a MITM HTTPS proxy that intercepts every request. Blindkey is one encrypted file plus a local broker โ nothing to stand up, nothing to trust with your connection.
- The agent gets a handle, not a secret.
blindkey agenthands out scoped handles; a human approves at the terminal; the secret is injected at the destination without the requesting process ever receiving the bytes (constraint C27; see docs/AGENT_BROKER.md). - Every claim is a falsifiable constraint with a test, not a trust-us page. If you can't tell how a tool protects you, you can't trust it โ Blindkey's entire design is written down as constraints you can read in an afternoon.
- Memory-hardened Rust core (
zeroize+mlock,panic = "abort", nounsafeoutside one designated FFI crate) โ the secret doesn't linger in process memory after use either.
What makes it different
| Blindkey | Cloud/proxy agent brokers | Typical free password manager | |
|---|---|---|---|
| Where secrets live | One local encrypted file | Cloud platform / intercepted at a proxy | Local or cloud, varies |
| Agent visibility | Handle only โ human-approved, model-blind delivery | Proxy sees plaintext in transit | N/A โ not agent-aware |
| Network dependency | None โ fully offline | Requires the proxy/platform | Often cloud-synced |
| Plaintext metadata (URLs, titles, timestamps) | None โ all encrypted | Varies | Often leaks at least some |
| KDF | Argon2id, floor enforced on open | N/A | Argon2d / PBKDF2; no floor check |
| In-memory secrets | zeroize + mlock | N/A | Often left in plaintext |
| How you verify the claims | 102 constraints with distributed tests (index) | Trust us | Trust us |
How an agent uses a secret without seeing it
The whole point in one picture: the agent asks for a handle, a human approves at the terminal, and Blindkey injects the secret into the destination โ the agent process never receives the bytes.
sequenceDiagram
participant Agent as AI agent
participant Broker as blindkey agent (local broker)
participant Human
participant Vault as Encrypted vault (.vlt)
participant Dest as Destination (child-process env var)
Agent->>Broker: request handle "github" (never the secret)
Broker->>Human: approve use of "github" for <cmd>? (TTY prompt)
Human-->>Broker: approve (one use)
Broker->>Vault: unlock + read secret (in-process, zeroized after)
Broker->>Dest: inject secret at the edge
Broker-->>Agent: status only (approved / denied) โ no secret
Note over Agent,Dest: The agent orchestrates the task โ the plaintext never crosses into it.
No proxy sits in your network path, no plaintext is intercepted in transit, and nothing is stored on a server โ the secret lives in one local file and is delivered model-blind (C13, C27).
Architecture
Small, auditable crates with a hard security boundary: all secret-touching code lives in
blindkey-core, and the only unsafe in the tree is the OS-hardening FFI in blindkey-sys.
flowchart TD
subgraph Frontends
CLI[blindkey-cli<br/>the `blindkey` binary]
TUI[blindkey-tui<br/>terminal UI]
GUI[blindkey-gui<br/>desktop app]
AGENT[blindkey-agent<br/>handle broker + MCP]
end
CORE[blindkey-core<br/>crypto ยท format ยท envelope ยท memory ยท rollback ยท sealed]
SYS[blindkey-sys<br/>mlock ยท setrlimit โ the only `unsafe`]
HW[blindkey-hardware<br/>YubiKey ยท FIDO2 ยท TPM]
CLIP[blindkey-clip<br/>clipboard concealment]
CLI --> CORE
TUI --> CORE
GUI --> CORE
AGENT --> CORE
CORE --> SYS
CLI --> HW
GUI --> HW
CLI --> CLIP
GUI --> CLIP
style CORE fill:#1f6feb,color:#fff
style SYS fill:#8957e5,color:#fff
Install
Developers (recommended)
You need a Rust toolchain (1.96+). No Apple Developer account required.
git clone https://github.com/leocelis/blindkey.git && cd blindkey
./scripts/setup-rust.sh
# CLI โ ~/.local/bin/blindkey (put ~/.local/bin on your PATH)
./scripts/install.sh
# Desktop app (opens a window โ leave the terminal running)
cargo run -p blindkey-gui
# Optional: local double-click .app on macOS (unsigned โ Gatekeeper may warn)
./scripts/bundle-macos.sh # โ target/Blindkey.app ; open target/Blindkey.app
Or install the CLI without cloning:
cargo install --git https://github.com/leocelis/blindkey.git --tag v1.1.1 --locked blindkey-cli
Prebuilt CLI (v1.1.1 GitHub Release): x86_64 and aarch64 for macOS and Linux. Windows is not supported: the agent broker is Unix-only. GUI: build from source (cargo run -p blindkey-gui). Prebuilt binaries have no live volume mount; build with --features volume-mount (Linux) or --features macos-fuse (macOS) for that.
Full options (Linux GUI deps, containers, fleet): docs/INSTALL.md
Not the npm blindkey or @blindkey/* packages, which are a different project.
Prebuilt CLI (no Rust)
Download from GitHub Releases, verify SHA256SUMS, chmod +x, move to PATH. See docs/VERIFYING_RELEASES.md.
# Example โ macOS Apple Silicon
curl -LO https://github.com/leocelis/blindkey/releases/download/v1.1.1/blindkey-aarch64-apple-darwin
curl -LO https://github.com/leocelis/blindkey/releases/download/v1.1.1/SHA256SUMS.txt
grep blindkey-aarch64-apple-darwin SHA256SUMS.txt | shasum -a 256 -c -
chmod +x blindkey-aarch64-apple-darwin && sudo mv blindkey-aarch64-apple-darwin /usr/local/bin/blindkey
There is no notarized Mac .app download yet. End-user double-click install needs Apple signing later; until then use the developer GUI path above.
Try Blindfolder (desktop)
Blindfolder keeps a .vltd in Dropbox/Drive/iCloud and never live-mounts that sync path (UC-30).
- Run the desktop app (
cargo run -p blindkey-gui). - Create volume โ Save asโฆ into your Dropbox (or other sync) folder โ passphrase โ Create. Wait until the file is fully downloaded.
- Open that
.vltdwith Open Blindfolder (not Mount on the sync path). - Unlock; edit files in the local folder Blindkey opens.
- Eject. Wait for the sync client to finish uploading the closed
.vltd.
Quickstart
Downloaded the binary and don't have the repo cloned? Create the sample file first:
cat > keys.txt <<'EOF'
github=synthetic-example-token-do-not-use
EOF
(Cloned the repo? Use the bundled samples/keys.txt instead โ same format.)
blindkey init
blindkey import --format raw --yes keys.txt # synthetic sample โ safe to try
blindkey ls
blindkey get github # copies to clipboard (model-blind)
blindkey gen --length 24
blindkey add myservice # interactive โ no secrets on argv
Scripts and agents without a terminal: pass --password-stdin, --password-fd N, or set
BLINDKEY_PASSWORD_FILE.
Real output from the flow above (secrets shown only because --stdout was passed explicitly;
the default is a model-blind clipboard copy):
$ blindkey init # prompts for a master password (not shown)
Deriving key (Argon2id)โฆ
Initial backup written to ~/.blindkey/vault.vlt.bak
note: Blindkey has not had an independent third-party security audit โ keep a separate backup; do not make this your only copy of irreplaceable secrets.
Created vault at ~/.blindkey/vault.vlt
$ blindkey import --format raw --yes keys.txt
note: Blindkey has not had an independent third-party security audit โ keep a separate backup; do not make this your only copy of irreplaceable secrets.
Parsed 1 entry (0 blocks skipped):
github syntโฆ-use (34)
Deriving key (Argon2id)โฆ
Backup written to ~/.blindkey/vault.vlt.bak
Imported 1 entries into ~/.blindkey/vault.vlt.
$ blindkey ls
Deriving key (Argon2id)โฆ
github
$ blindkey gen --length 24
S+6W;]|5c<}#^/*|+$.B1{_W
(157 bits of entropy)
$ blindkey get github --stdout # default is clipboard; --stdout shown here for illustration
Deriving key (Argon2id)โฆ
WARNING: plaintext written to stdout; ensure no AI agent or untrusted process captures this stream.
synthetic-example-token-do-not-use
Desktop app: see Install โ Developers. Drag samples/keys.txt onto the window to import credentials.
Documentation
| Topic | Doc |
|---|---|
| Doc hub (start here) | docs/README.md |
| Install & build | docs/INSTALL.md |
| CLI reference | docs/CLI.md |
| Agent broker | docs/AGENT_BROKER.md |
| Threat model | docs/THREAT_MODEL.md |
| Cryptography | docs/CRYPTO.md |
| File format | docs/FILE_FORMAT.md |
| Architecture | docs/ARCHITECTURE.md |
| 102 security constraints | blindkey_intent.yaml ยท test index |
| Use-case specs (30) | docs/specs/ |
| Roadmap | ROADMAP.md |
| Release verification | docs/VERIFYING_RELEASES.md |
| Export & sanctions compliance (contains cryptography) | docs/EXPORT_COMPLIANCE.md |
| EU Cyber Resilience Act status | docs/EU_CRA_STATUS.md |
Design at a glance: ChaCha20-Poly1305 STREAM (age construction) with a per-save key derived by HKDF ยท Argon2id ยท age-style multi-stanza envelope ยท encrypt-then-MAC ยท zero network, zero telemetry.
Project status
- โ
Research + 102-constraint intent + quality gate (
just check/just audit-ready; GHA CI) - โ
CLI, TUI, desktop GUI on shared
blindkey-core - โ v1.1.0 โ Blindfolder, local volumes, desktop craft; format v1 frozen (ADR-0005)
- โ
Blindfolder โ keep a
.vltdin Dropbox/Drive/iCloud/Syncthing; Blindkey copies it locally, opens a normal folder, and atomically checks it back in. It does not live-mount the sync-path file (UC-30). - โ
Volume live mount โ Linux FUSE via
blindkey-fuse(--features volume-mount). macOS live Finder mount is optional: install macFUSE yourself, then build with--features macos-fuse. Blindkey does not bundle or redistribute macFUSE/Fuse-T (ADR-0010). Without that feature, Blindfolder still opens a cleartext working folder. - โ
blindkey mcpโ MCP server with broker-backeduse_handledelivery when a companion agent is listening (UC-24) - โณ Hardware FFI polish, sync/merge, optional third-party audit โ ROADMAP.md
macOS live mount (optional)
# 1. Install macFUSE from https://macfuse.io (official package โ not redistributed by Blindkey)
# 2. Ensure pkg-config can see fuse.pc (macFUSE installer usually places it)
# 3. Build GUI or CLI with the feature:
cargo build -p blindkey-gui --features macos-fuse --release
cargo build -p blindkey-cli --features macos-fuse --release
Default desktop builds keep Blindfolder's cleartext working folder (no macFUSE required).
Repository layout
blindkey/
โโโ crates/
โ โโโ blindkey-core/ # crypto, format, envelope, memory, rollback
โ โโโ blindkey-cli/ # the `blindkey` binary
โ โโโ blindkey-gui/ # egui desktop app
โ โโโ blindkey-tui/ # ratatui terminal UI
โ โโโ blindkey-agent/ # handle broker + MCP server for AI agents
โ โโโ blindkey-clip/ # clipboard concealment
โ โโโ blindkey-fuse/ # FUSE mount adapter for encrypted volumes
โ โโโ blindkey-sys/ # mlock, setrlimit โ only `unsafe` boundary
โ โโโ blindkey-hardware/ # optional hardware unlock: YubiKey CR, FIDO2, TPM (need OS tools) โ see docs/guides/hardware-factor-status.md
โโโ docs/ # specs, threat model, CONSTRAINT_INDEX
โโโ samples/ # synthetic keys.txt for import demo
โโโ research/ # security research behind the design
โโโ blindkey_intent.yaml # constraint specification (source of truth)
Community
- Questions: GitHub Discussions
- Bugs: issue tracker ยท Security: SECURITY.md
- Contributing: CONTRIBUTING.md ยท GOVERNANCE.md
License
Dual-licensed under MIT or Apache-2.0. See COPYRIGHT.
https://github.com/leocelis/blindkey/releases/download/v1.1.1/blindkey-mcp-1.1.1.mcpb# mcpb: https://github.com/leocelis/blindkey/releases/download/v1.1.1/blindkey-mcp-1.1.1.mcpbRelated Servers
io.github.leocelis/eif
Runtime gate for AI agent claims. Catches sycophantic drift, circular self-validation, causal errors
io.github.leocelis/horizon-fidelity-monitor
Real-time conversation health for AI agents: drift, desync, causal collapse, plus mission clocks.
io.github.leocelis/ivd
33 tools that make AI write, implement, and verify intent against explicit, testable constraints.