@omarei/hush

Envelope-encrypted team secrets your AI agent can use but never read.

You keep your API keys in a .env file. It is plaintext, every process you launch can read it, and the day you pointed an AI coding agent at the repo it went into the agent's context window — and from there, wherever transcripts go.

hush fixes that without a server, an account, or a shared password. Your secrets live encrypted inside the repo itself. hush npm run dev puts them in that one process and nowhere else. Your coding agent gets tools that can use a key but never read one. A teammate gets access with one command, and removing them re-encrypts everything. Zero dependencies; one npm install.

hush init acme                  # a vault in .hush/vault.json — commit it
hush add .env --as "Dev"        # your existing secrets, now encrypted, as a set called dev
hush npm run dev                # injected into the process, never onto disk
hush team add sam hush_pk_1xM…  # commit; sam can decrypt. no invite email.
hush team rm sam                # re-keys the vault, re-seals every value

[!IMPORTANT] Status: early. This works and is heavily tested, but it is pre-1.0, it has one author, and it has not had an external security review. The crypto is a standard construction (age's, rebuilt on node:crypto) rather than anything invented here, and there is a differential test suite against an independent reimplementation — but that is not the same as someone qualified having looked at it. docs/REVIEW-SCOPE.md is the brief for the review it needs.

Development happens on macOS; Linux is covered by CI. Windows is in beta: your key is kept with DPAPI, approvals are a native Windows dialog, hush run npm … works through npm.cmd, secret files get owner-only ACLs, and there is a PowerShell hook — a Windows CI job checks those paths, but it has not had much real use yet. Fingerprint approval (Windows Hello) is not there yet. Tell me what broke if you try it somewhere unusual.

Found a way to read a vault you should not? Please report it privately rather than opening an issue.

Install

One file, no Node needed — macOS, Linux (glibc and musl), and Windows (beta):

curl -fsSL https://raw.githubusercontent.com/omarei-omoto/hush/main/scripts/install.sh | sh
brew install omarei-omoto/tap/hush

irm https://raw.githubusercontent.com/omarei-omoto/hush/main/scripts/install.ps1 | iex
scoop install https://github.com/omarei-omoto/hush/releases/latest/download/hush.json

The installer refuses a binary whose sha256 is not the one in the release's SHA256SUMS, checks its build-provenance attestation too when the GitHub CLI is signed in, and installs to ~/.local/bin without sudo. To check a download by hand: gh attestation verify hush-darwin-arm64 --repo omarei-omoto/hush.

Or from npm, with Node ≥ 22.6:

npm install -g @omarei/hush

From a clone there is no build step — Node ≥ 22.18 runs the TypeScript directly (on 22.6–22.17, run npm run build first):

git clone https://github.com/omarei-omoto/hush.git
cd hush && node src/cli.ts --help

Why the published package ships compiled output

Node will not strip TypeScript types for anything under node_modules, so an installed copy cannot run src/. The tarball ships JavaScript in dist/ (built by npm run build, run automatically by prepack). The hush command decides by where it lives, not by what exists: under node_modules it runs dist/; in a checkout (including one npm linked) it runs src/, so a stale build can never shadow your edits. Still zero runtime dependencies.

Quick start

cd your-project
hush start

That is the whole thing. It looks for your keys, gets them in, asks whether an AI assistant will be near them, and offers to run your project. A few questions, nothing you have to know already.

Prefer to see every step yourself? The same thing, by hand:

hush init                    # creates your key + a vault, safe to commit
hush add .env --as "Dev"     # what you already have, encrypted, as a set called dev
rm .env                      # you don't need it any more
git add .hush && git commit -m "encrypted secrets"

From now on, put hush in front of whatever you run:

hush npm run dev             # anything after hush runs with the secrets injected
hush dev                     # or: find package.json and run its dev script

Secrets exist in that process's environment and nowhere else. Not on disk, not in your shell, not in your scrollback.

Why this exists

.env files have quietly become the worst artifact in your repo. They are plaintext, they are readable by every process you launch, and they are now routinely slurped into an LLM's context — researchers caught a coding agent uploading whole repos with .env credentials verbatim and unredacted.

The existing tools each cover part of this:

	What it gets right	What it costs you
SOPS / age	per-recipient crypto, real revocation	no idea agents exist; YAML and key juggling
secretctl	the agent story	explicitly single-user
dotenvx / nevr-env	encrypted file in git	one key for the whole team, so no real revocation
1Password CLI + MCP	real vault, real hardware, real audit, agent access	an account and a subscription for everyone on the team
Doppler / Infisical + MCP	proper secrets management, agent access	a server to run or seats to buy

hush is the local, free, no-account option, not a replacement for the last two. If your team already pays for 1Password or Doppler, their MCP servers do what hush does with better hardware and a real audit trail — use them. hush is for the solo developer and the small team who want age's security model and an agent that cannot read a value, with nothing to sign up for and nothing to deploy: the git repo is the backend.

Where the line is: the moment you need dynamic credentials, leasing, expiry, or an audit log someone else cannot edit, you have outgrown a file in git. hush will not get you there and does not pretend to. Full comparison in RESEARCH.md.

Documentation

Everything else is in the guide — on GitHub under docs/guide, or as a site at omarei-omoto.github.io/hush.

• Using it — Sets · Coming from another tool · Several keys for one service · Running things · Credentials that are a file · The app · The shell hook
• Checking config — What a value should look like · Finding what a codebase needs
• Agents — Connecting your agent · What your agent gets · Adding a key off-transcript · Approvals · Policy
• Your team — Adding someone · Only some sets · Removing someone · Membership changes · Merging · CI · After someone leaves
• Hardening — The security ladder · Touch ID · Hardware keys
• Reference — Commands · How the crypto works · What hush does not do · The approval relay · Architecture · Hardware unlock
• Trust — SECURITY.md (threat model, reporting) · Review scope · Red team · Every defect found · RESEARCH.md

Contributing

Very welcome, especially: running it somewhere I cannot (Linux, Windows, a YubiKey I do not own), finding a way to get a value out that should not come out, or telling me where it confused you.

• CONTRIBUTING.md — how to set up, and the bar for a change
• docs/ARCHITECTURE.md — how it fits together, and the tests that hold it
• Development — running the suite, the fuzzers and the binary
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1
• SECURITY.md — threat model, and how to report a vulnerability
• docs/AUDIT.md — every defect found so far, and what changed

Security problems do not go in issues. Open a private advisory instead.

License

MIT — see LICENSE.