Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/leocelis--blindkey/badge.svg)](/listings/leocelis--blindkey)

HTML

<a href="/listings/leocelis--blindkey"><img src="/api/listings/leocelis--blindkey/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](docs/INSTALL.md)

Not the npm `blindkey` or `@blindkey/*` packages, which are a different project.

Prebuilt CLI (no Rust)

Download from [GitHub Releases](https://github.com/leocelis/blindkey/releases), verify SHA256SUMS, `chmod +x`, move to PATH. See [docs/VERIFYING_RELEASES.md](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](docs/specs/UC-30-volume-working-copy.md)).

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 311 lines
  1. <div align="center">
  2. # 🔑 Blindkey
  3. **The local-first credential vault your AI agents can use — but never see.**
  4. **No server. No account. One encrypted file. 102 testable security constraints. Rust.**
  5. Passwords. API keys. `.env` files. SSH and signing keys. Database URLs. The credentials your AI
  6. coding agents touch every day.
  7. [![CI](https://github.com/leocelis/blindkey/actions/workflows/ci.yml/badge.svg)](https://github.com/leocelis/blindkey/actions/workflows/ci.yml)
  8. [![Scorecard](https://github.com/leocelis/blindkey/actions/workflows/scorecard.yml/badge.svg)](https://github.com/leocelis/blindkey/actions/workflows/scorecard.yml)
  9. [![MSRV](https://img.shields.io/badge/MSRV-1.96-blue.svg)](rust-toolchain.toml)
  10. [![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)
  11. [![Status: v1.1.1 / unaudited / format v1 stable](https://img.shields.io/badge/status-v1.1.1%20%2F%20unaudited%20%2F%20format%20v1%20stable-yellow.svg)](#project-status)
  12. [Install](#install) · [Documentation](#documentation) · [Quickstart](#quickstart) · [Contributing](CONTRIBUTING.md) · [Support](SUPPORT.md)
  13. </div>
  14. > [!WARNING]
  15. > **v1.1.1 — not independently third-party audited — keep your own backup of anything you store.**
  16. > Blindkey is **functional**: cryptographic core implemented and tested, working CLI *and* desktop app.
  17. > **On-disk format v1 is stable** ([ADR-0005](docs/adr/0005-format-v1-freeze.md)) — vault files from
  18. > alpha releases open on 1.x without migration. See [ROADMAP.md](ROADMAP.md) and [SECURITY.md](SECURITY.md).
  19. ---
  20. ## Why Blindkey exists
  21. Developers now work alongside AI agents that read their files, run their shells, and — if the
  22. secret is sitting in a `.env` or an MCP config file — read their credentials too.
  23. GitGuardian found **~24,000 secrets exposed in public MCP configuration files** on GitHub in
  24. 2026 (`claude_desktop_config.json`, `.cursor/settings.json`), over 2,100 of them still valid.
  25. AI-assisted commits leak secrets at roughly **2x** the platform-wide baseline. The industry's own
  26. answer to this is converging on one principle: **the agent should never hold or see the secret** —
  27. something else should broker it in at the edge.
  28. Blindkey is that something else, built local-first:
  29. - **No server, no account, no proxy in the traffic path.** Other credential brokers for AI agents
  30. run as a cloud-platform service or a MITM HTTPS proxy that intercepts every request. Blindkey is
  31. one encrypted file plus a local broker — nothing to stand up, nothing to trust with your
  32. connection.
  33. - **The agent gets a handle, not a secret.** `blindkey agent` hands out scoped handles; a human
  34. approves at the terminal; the secret is injected at the destination without the requesting
  35. process ever receiving the bytes (constraint C27; see [docs/AGENT_BROKER.md](docs/AGENT_BROKER.md)).
  36. - **Every claim is a falsifiable constraint with a test**, not a trust-us page. If you can't tell
  37. *how* a tool protects you, you can't trust it — Blindkey's entire design is written down as
  38. constraints you can read in an afternoon.
  39. - **Memory-hardened Rust core** (`zeroize` + `mlock`, `panic = "abort"`, no `unsafe` outside one
  40. designated FFI crate) — the secret doesn't linger in process memory after use either.
  41. ## What makes it different
  42. | | Blindkey | Cloud/proxy agent brokers | Typical free password manager |
  43. |---|---|---|---|
  44. | Where secrets live | **One local encrypted file** | Cloud platform / intercepted at a proxy | Local or cloud, varies |
  45. | Agent visibility | **Handle only — human-approved, model-blind delivery** | Proxy sees plaintext in transit | N/A — not agent-aware |
  46. | Network dependency | **None — fully offline** | Requires the proxy/platform | Often cloud-synced |
  47. | Plaintext metadata (URLs, titles, timestamps) | **None — all encrypted** | Varies | Often leaks at least some |
  48. | KDF | **Argon2id, floor enforced on open** | N/A | Argon2d / PBKDF2; no floor check |
  49. | In-memory secrets | **`zeroize` + `mlock`** | N/A | Often left in plaintext |
  50. | How you verify the claims | **102 constraints** with distributed tests ([index](docs/CONSTRAINT_INDEX.md)) | Trust us | Trust us |
  51. ## How an agent uses a secret without seeing it
  52. The whole point in one picture: the agent asks for a *handle*, a human approves at the terminal,
  53. and Blindkey injects the secret into the destination — the agent process never receives the bytes.
  54. ```mermaid
  55. sequenceDiagram
  56. participant Agent as AI agent
  57. participant Broker as blindkey agent (local broker)
  58. participant Human
  59. participant Vault as Encrypted vault (.vlt)
  60. participant Dest as Destination (child-process env var)
  61. Agent->>Broker: request handle "github" (never the secret)
  62. Broker->>Human: approve use of "github" for <cmd>? (TTY prompt)
  63. Human-->>Broker: approve (one use)
  64. Broker->>Vault: unlock + read secret (in-process, zeroized after)
  65. Broker->>Dest: inject secret at the edge
  66. Broker-->>Agent: status only (approved / denied) — no secret
  67. Note over Agent,Dest: The agent orchestrates the task — the plaintext never crosses into it.
  68. ```
  69. No proxy sits in your network path, no plaintext is intercepted in transit, and nothing is
  70. stored on a server — the secret lives in one local file and is delivered model-blind (C13, C27).
  71. ## Architecture
  72. Small, auditable crates with a hard security boundary: all secret-touching code lives in
  73. `blindkey-core`, and the only `unsafe` in the tree is the OS-hardening FFI in `blindkey-sys`.
  74. ```mermaid
  75. flowchart TD
  76. subgraph Frontends
  77. CLI[blindkey-cli<br/>the `blindkey` binary]
  78. TUI[blindkey-tui<br/>terminal UI]
  79. GUI[blindkey-gui<br/>desktop app]
  80. AGENT[blindkey-agent<br/>handle broker + MCP]
  81. end
  82. CORE[blindkey-core<br/>crypto · format · envelope · memory · rollback · sealed]
  83. SYS[blindkey-sys<br/>mlock · setrlimit — the only `unsafe`]
  84. HW[blindkey-hardware<br/>YubiKey · FIDO2 · TPM]
  85. CLIP[blindkey-clip<br/>clipboard concealment]
  86. CLI --> CORE
  87. TUI --> CORE
  88. GUI --> CORE
  89. AGENT --> CORE
  90. CORE --> SYS
  91. CLI --> HW
  92. GUI --> HW
  93. CLI --> CLIP
  94. GUI --> CLIP
  95. style CORE fill:#1f6feb,color:#fff
  96. style SYS fill:#8957e5,color:#fff
  97. ```
  98. ## Install
  99. ### Developers (recommended)
  100. You need a Rust toolchain (1.96+). No Apple Developer account required.
  101. ```sh
  102. git clone https://github.com/leocelis/blindkey.git && cd blindkey
  103. ./scripts/setup-rust.sh
  104. # CLI → ~/.local/bin/blindkey (put ~/.local/bin on your PATH)
  105. ./scripts/install.sh
  106. # Desktop app (opens a window — leave the terminal running)
  107. cargo run -p blindkey-gui
  108. # Optional: local double-click .app on macOS (unsigned — Gatekeeper may warn)
  109. ./scripts/bundle-macos.sh # → target/Blindkey.app ; open target/Blindkey.app
  110. ```
  111. Or install the CLI without cloning:
  112. ```sh
  113. cargo install --git https://github.com/leocelis/blindkey.git --tag v1.1.1 --locked blindkey-cli
  114. ```
  115. **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.
  116. Full options (Linux GUI deps, containers, fleet): [docs/INSTALL.md](docs/INSTALL.md)
  117. Not the npm `blindkey` or `@blindkey/*` packages, which are a different project.
  118. ### Prebuilt CLI (no Rust)
  119. Download from [GitHub Releases](https://github.com/leocelis/blindkey/releases), verify SHA256SUMS, `chmod +x`, move to PATH. See [docs/VERIFYING_RELEASES.md](docs/VERIFYING_RELEASES.md).
  120. ```sh
  121. # Example — macOS Apple Silicon
  122. curl -LO https://github.com/leocelis/blindkey/releases/download/v1.1.1/blindkey-aarch64-apple-darwin
  123. curl -LO https://github.com/leocelis/blindkey/releases/download/v1.1.1/SHA256SUMS.txt
  124. grep blindkey-aarch64-apple-darwin SHA256SUMS.txt | shasum -a 256 -c -
  125. chmod +x blindkey-aarch64-apple-darwin && sudo mv blindkey-aarch64-apple-darwin /usr/local/bin/blindkey
  126. ```
  127. 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.
  128. ### Try Blindfolder (desktop)
  129. Blindfolder keeps a `.vltd` in Dropbox/Drive/iCloud and never live-mounts that sync path ([UC-30](docs/specs/UC-30-volume-working-copy.md)).
  130. 1. Run the desktop app (`cargo run -p blindkey-gui`).
  131. 2. **Create volume** → **Save as…** into your Dropbox (or other sync) folder → passphrase → **Create**. Wait until the file is fully downloaded.
  132. 3. Open that `.vltd` with **Open Blindfolder** (not Mount on the sync path).
  133. 4. Unlock; edit files in the local folder Blindkey opens.
  134. 5. **Eject**. Wait for the sync client to finish uploading the closed `.vltd`.
  135. ## Quickstart
  136. Downloaded the binary and don't have the repo cloned? Create the sample file first:
  137. ```sh
  138. cat > keys.txt <<'EOF'
  139. github=synthetic-example-token-do-not-use
  140. EOF
  141. ```
  142. (Cloned the repo? Use the bundled `samples/keys.txt` instead — same format.)
  143. ```sh
  144. blindkey init
  145. blindkey import --format raw --yes keys.txt # synthetic sample — safe to try
  146. blindkey ls
  147. blindkey get github # copies to clipboard (model-blind)
  148. blindkey gen --length 24
  149. blindkey add myservice # interactive — no secrets on argv
  150. ```
  151. Scripts and agents without a terminal: pass `--password-stdin`, `--password-fd N`, or set
  152. `BLINDKEY_PASSWORD_FILE`.
  153. Real output from the flow above (secrets shown only because `--stdout` was passed explicitly;
  154. the default is a model-blind clipboard copy):
  155. ```console
  156. $ blindkey init # prompts for a master password (not shown)
  157. Deriving key (Argon2id)…
  158. Initial backup written to ~/.blindkey/vault.vlt.bak
  159. 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.
  160. Created vault at ~/.blindkey/vault.vlt
  161. $ blindkey import --format raw --yes keys.txt
  162. 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.
  163. Parsed 1 entry (0 blocks skipped):
  164. github synt…-use (34)
  165. Deriving key (Argon2id)…
  166. Backup written to ~/.blindkey/vault.vlt.bak
  167. Imported 1 entries into ~/.blindkey/vault.vlt.
  168. $ blindkey ls
  169. Deriving key (Argon2id)…
  170. github
  171. $ blindkey gen --length 24
  172. S+6W;]|5c<}#^/*|+$.B1{_W
  173. (157 bits of entropy)
  174. $ blindkey get github --stdout # default is clipboard; --stdout shown here for illustration
  175. Deriving key (Argon2id)…
  176. WARNING: plaintext written to stdout; ensure no AI agent or untrusted process captures this stream.
  177. synthetic-example-token-do-not-use
  178. ```
  179. Desktop app: see [Install → Developers](#developers-recommended). Drag `samples/keys.txt` onto the window to import credentials.
  180. ## Documentation
  181. | Topic | Doc |
  182. |-------|-----|
  183. | Doc hub (start here) | [docs/README.md](docs/README.md) |
  184. | Install & build | [docs/INSTALL.md](docs/INSTALL.md) |
  185. | CLI reference | [docs/CLI.md](docs/CLI.md) |
  186. | Agent broker | [docs/AGENT_BROKER.md](docs/AGENT_BROKER.md) |
  187. | Threat model | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) |
  188. | Cryptography | [docs/CRYPTO.md](docs/CRYPTO.md) |
  189. | File format | [docs/FILE_FORMAT.md](docs/FILE_FORMAT.md) |
  190. | Architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
  191. | 102 security constraints | [blindkey_intent.yaml](blindkey_intent.yaml) · [test index](docs/CONSTRAINT_INDEX.md) |
  192. | Use-case specs (30) | [docs/specs/](docs/specs/README.md) |
  193. | Roadmap | [ROADMAP.md](ROADMAP.md) |
  194. | Release verification | [docs/VERIFYING_RELEASES.md](docs/VERIFYING_RELEASES.md) |
  195. | Export & sanctions compliance (contains cryptography) | [docs/EXPORT_COMPLIANCE.md](docs/EXPORT_COMPLIANCE.md) |
  196. | EU Cyber Resilience Act status | [docs/EU_CRA_STATUS.md](docs/EU_CRA_STATUS.md) |
  197. Design at a glance: ChaCha20-Poly1305 STREAM (age construction) with a per-save key derived by HKDF · Argon2id · age-style multi-stanza envelope ·
  198. encrypt-then-MAC · **zero network, zero telemetry**.
  199. ## Project status
  200. - ✅ Research + 102-constraint intent + quality gate (`just check` / `just audit-ready`; [GHA CI](.github/workflows/ci.yml))
  201. - ✅ CLI, TUI, desktop GUI on shared `blindkey-core`
  202. - ✅ **v1.1.0** — Blindfolder, local volumes, desktop craft; format v1 frozen ([ADR-0005](docs/adr/0005-format-v1-freeze.md))
  203. - ✅ **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](docs/specs/UC-30-volume-working-copy.md)).
  204. - ✅ **Volume live mount** — Linux FUSE via `blindkey-fuse` (`--features volume-mount`). macOS live Finder mount is **optional**: install [macFUSE](https://macfuse.io) yourself, then build with `--features macos-fuse`. Blindkey does **not** bundle or redistribute macFUSE/Fuse-T ([ADR-0010](docs/adr/0010-volume-macos-mount-matrix.md)). Without that feature, Blindfolder still opens a cleartext working folder.
  205. - ✅ `blindkey mcp` — MCP server with broker-backed `use_handle` delivery when a companion agent is listening ([UC-24](docs/specs/UC-24-mcp-broker.md))
  206. - ⏳ Hardware FFI polish, sync/merge, optional third-party audit — [ROADMAP.md](ROADMAP.md)
  207. ### macOS live mount (optional)
  208. ```bash
  209. # 1. Install macFUSE from https://macfuse.io (official package — not redistributed by Blindkey)
  210. # 2. Ensure pkg-config can see fuse.pc (macFUSE installer usually places it)
  211. # 3. Build GUI or CLI with the feature:
  212. cargo build -p blindkey-gui --features macos-fuse --release
  213. cargo build -p blindkey-cli --features macos-fuse --release
  214. ```
  215. Default desktop builds keep Blindfolder's cleartext working folder (no macFUSE required).
  216. ## Repository layout
  217. ```
  218. blindkey/
  219. ├── crates/
  220. │ ├── blindkey-core/ # crypto, format, envelope, memory, rollback
  221. │ ├── blindkey-cli/ # the `blindkey` binary
  222. │ ├── blindkey-gui/ # egui desktop app
  223. │ ├── blindkey-tui/ # ratatui terminal UI
  224. │ ├── blindkey-agent/ # handle broker + MCP server for AI agents
  225. │ ├── blindkey-clip/ # clipboard concealment
  226. │ ├── blindkey-fuse/ # FUSE mount adapter for encrypted volumes
  227. │ ├── blindkey-sys/ # mlock, setrlimit — only `unsafe` boundary
  228. │ └── blindkey-hardware/ # optional hardware unlock: YubiKey CR, FIDO2, TPM (need OS tools) — see docs/guides/hardware-factor-status.md
  229. ├── docs/ # specs, threat model, CONSTRAINT_INDEX
  230. ├── samples/ # synthetic keys.txt for import demo
  231. ├── research/ # security research behind the design
  232. └── blindkey_intent.yaml # constraint specification (source of truth)
  233. ```
  234. ## Community
  235. - **Questions:** [GitHub Discussions](https://github.com/leocelis/blindkey/discussions)
  236. - **Bugs:** [issue tracker](https://github.com/leocelis/blindkey/issues) · **Security:** [SECURITY.md](SECURITY.md)
  237. - **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) · [GOVERNANCE.md](GOVERNANCE.md)
  238. Maintained by [Leo](MAINTAINERS.md) and [Juan](MAINTAINERS.md).
  239. ## License
  240. Dual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE). See [COPYRIGHT](COPYRIGHT).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.