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.
Badge for your README
Markdown
[](/listings/leocelis--blindkey)HTML
<a href="/listings/leocelis--blindkey"><img src="/api/listings/leocelis--blindkey/badge.svg" alt="findsafeskills safety rating" /></a>Install
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
- <div align="center">
- # 🔑 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.
- [](https://github.com/leocelis/blindkey/actions/workflows/ci.yml)
- [](https://github.com/leocelis/blindkey/actions/workflows/scorecard.yml)
- [](rust-toolchain.toml)
- [](#license)
- [](#project-status)
- [Install](#install) · [Documentation](#documentation) · [Quickstart](#quickstart) · [Contributing](CONTRIBUTING.md) · [Support](SUPPORT.md)
- </div>
- > [!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](docs/adr/0005-format-v1-freeze.md)) — vault files from
- > alpha releases open on 1.x without migration. See [ROADMAP.md](ROADMAP.md) and [SECURITY.md](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](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 | **102 constraints** with distributed tests ([index](docs/CONSTRAINT_INDEX.md)) | 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.
- ```mermaid
- 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`.
- ```mermaid
- 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.
- ```sh
- 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:
- ```sh
- 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).
- ```sh
- # 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`.
- ## Quickstart
- Downloaded the binary and don't have the repo cloned? Create the sample file first:
- ```sh
- cat > keys.txt <<'EOF'
- github=synthetic-example-token-do-not-use
- EOF
- ```
- (Cloned the repo? Use the bundled `samples/keys.txt` instead — same format.)
- ```sh
- 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):
- ```console
- $ 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](#developers-recommended). Drag `samples/keys.txt` onto the window to import credentials.
- ## Documentation
- | Topic | Doc |
- |-------|-----|
- | Doc hub (start here) | [docs/README.md](docs/README.md) |
- | Install & build | [docs/INSTALL.md](docs/INSTALL.md) |
- | CLI reference | [docs/CLI.md](docs/CLI.md) |
- | Agent broker | [docs/AGENT_BROKER.md](docs/AGENT_BROKER.md) |
- | Threat model | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) |
- | Cryptography | [docs/CRYPTO.md](docs/CRYPTO.md) |
- | File format | [docs/FILE_FORMAT.md](docs/FILE_FORMAT.md) |
- | Architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
- | 102 security constraints | [blindkey_intent.yaml](blindkey_intent.yaml) · [test index](docs/CONSTRAINT_INDEX.md) |
- | Use-case specs (30) | [docs/specs/](docs/specs/README.md) |
- | Roadmap | [ROADMAP.md](ROADMAP.md) |
- | Release verification | [docs/VERIFYING_RELEASES.md](docs/VERIFYING_RELEASES.md) |
- | Export & sanctions compliance (contains cryptography) | [docs/EXPORT_COMPLIANCE.md](docs/EXPORT_COMPLIANCE.md) |
- | EU Cyber Resilience Act status | [docs/EU_CRA_STATUS.md](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](.github/workflows/ci.yml))
- - ✅ CLI, TUI, desktop GUI on shared `blindkey-core`
- - ✅ **v1.1.0** — Blindfolder, local volumes, desktop craft; format v1 frozen ([ADR-0005](docs/adr/0005-format-v1-freeze.md))
- - ✅ **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)).
- - ✅ **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.
- - ✅ `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))
- - ⏳ Hardware FFI polish, sync/merge, optional third-party audit — [ROADMAP.md](ROADMAP.md)
- ### macOS live mount (optional)
- ```bash
- # 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](https://github.com/leocelis/blindkey/discussions)
- - **Bugs:** [issue tracker](https://github.com/leocelis/blindkey/issues) · **Security:** [SECURITY.md](SECURITY.md)
- - **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) · [GOVERNANCE.md](GOVERNANCE.md)
- Maintained by [Leo](MAINTAINERS.md) and [Juan](MAINTAINERS.md).
- ## License
- 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 inFree to use. If it’s helped, pass it on.