🔑 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.0 — 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 agent hands 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", no unsafe outside 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	66 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 (env / subprocess / HTTP)

    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.0 --locked blindkey-cli

Prebuilt CLI (v1.1.0 GitHub Release): x86_64 and aarch64 for macOS and Linux. Windows: build from source (Unix-first broker). GUI: build from source (cargo run -p blindkey-gui).

Full options (Linux GUI deps, containers, fleet): docs/INSTALL.md

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.0/blindkey-aarch64-apple-darwin
curl -LO https://github.com/leocelis/blindkey/releases/download/v1.1.0/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).

1. Run the desktop app (cargo run -p blindkey-gui).
2. Create volume → Save as… into your Dropbox (or other sync) folder → passphrase → Create. Wait until the file is fully downloaded.
3. Open that .vltd with Open Blindfolder (not Mount on the sync path).
4. Unlock; edit files in the local folder Blindkey opens.
5. 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

Real output from the flow above (secrets shown only because --stdout was passed explicitly; the default is a model-blind clipboard copy):

$ blindkey init
  Created vault at ~/.blindkey/vault.vlt

$ blindkey import --format raw --yes keys.txt
  Parsed 2 entries (0 blocks skipped):
    github                       ghp_…real (30)
    openai                       sk-p…real (26)
  Imported 2 entries into ~/.blindkey/vault.vlt

$ blindkey ls
  github
  openai

$ blindkey gen --length 24
  %L1H*$b)!*:m#[D4ErQ&yqk6
  (157 bits of entropy)

$ blindkey get github --stdout    # default is clipboard; --stdout shown here for illustration
  WARNING: plaintext written to stdout; ensure no AI agent or untrusted process captures this stream.
  ghp_synthetic_example_not_real

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
66 security constraints	blindkey_intent.yaml · test index
Use-case specs (22)	docs/specs/
Roadmap	ROADMAP.md
Release verification

Design at a glance: XChaCha20-Poly1305 STREAM · 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 .vltd in 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-backed use_handle delivery 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-based broker for AI agents (scaffold)
│   ├── blindkey-clip/      # clipboard concealment
│   ├── blindkey-sys/       # mlock, setrlimit — only `unsafe` boundary
│   └── blindkey-hardware/  # YubiKey CR (CLI); FIDO2/TPM mocks — 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

Maintained by Leo and Juan.

License

Dual-licensed under MIT or Apache-2.0. See COPYRIGHT.