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

#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

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

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.