Repository avatar
AI Tools
v1.1.1
active

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.

CI Scorecard MSRV License: MIT OR Apache-2.0 Status: v1.1.1 / unaudited / format v1 stable

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 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

BlindkeyCloud/proxy agent brokersTypical free password manager
Where secrets liveOne local encrypted fileCloud platform / intercepted at a proxyLocal or cloud, varies
Agent visibilityHandle only โ€” human-approved, model-blind deliveryProxy sees plaintext in transitN/A โ€” not agent-aware
Network dependencyNone โ€” fully offlineRequires the proxy/platformOften cloud-synced
Plaintext metadata (URLs, titles, timestamps)None โ€” all encryptedVariesOften leaks at least some
KDFArgon2id, floor enforced on openN/AArgon2d / PBKDF2; no floor check
In-memory secretszeroize + mlockN/AOften left in plaintext
How you verify the claims102 constraints with distributed tests (index)Trust usTrust 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).

  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

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

TopicDoc
Doc hub (start here)docs/README.md
Install & builddocs/INSTALL.md
CLI referencedocs/CLI.md
Agent brokerdocs/AGENT_BROKER.md
Threat modeldocs/THREAT_MODEL.md
Cryptographydocs/CRYPTO.md
File formatdocs/FILE_FORMAT.md
Architecturedocs/ARCHITECTURE.md
102 security constraintsblindkey_intent.yaml ยท test index
Use-case specs (30)docs/specs/
RoadmapROADMAP.md
Release verificationdocs/VERIFYING_RELEASES.md
Export & sanctions compliance (contains cryptography)docs/EXPORT_COMPLIANCE.md
EU Cyber Resilience Act statusdocs/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 .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 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

Maintained by Leo and Juan.

License

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