hush

[hush]

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

[CI] [npm] [node] [license] [runtime deps] [OpenSSF Best Practices]

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 ithush add .env --as "Dev"        # your existing secrets, now encrypted, as a set called devhush npm run dev                # injected into the process, never onto diskhush 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

[A .env file goes into a hush vault; what is committed is ciphertext; hush run gives the program the key and prints [redacted:FAL_KEY]]

[!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 | shbrew install omarei-omoto/tap/hush

irm https://raw.githubusercontent.com/omarei-omoto/hush/main/scripts/install.ps1 | iexscoop 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.gitcd hush && node src/cli.ts --help

Quick start

cd your-projecthush 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. Run it again any time: it picks up whatever is left, and hush setup shows where you are.

Or let your coding agent set it up. Paste this into Claude Code, Codex or Cursor:

Set up hush in this project. Run hush setup --json and follow it: run each step's command as written, ask me in the chat for anything marked "choice", and for anything marked "person", run it and wait for me. Never open a .env file or ask me for a key in the chat.

Anything that needs you, such as a new key or deleting a .env, asks you on your own screen, not in the chat. More in Setting up.

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

hush init                    # creates your key + a vault, safe to commithush add .env --as "Dev"     # what you already have, encrypted, as a set called devrm .env                      # you don't need it any moregit 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 injectedhush 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.

Then a quick checkup of what is already out there:

hush scan --agents           # plaintext keys in your agents' config files; --fix moves them into hushhush scan --transcripts      # your keys in agents' saved conversations (read-only)

Agents on other machines (a server, a devcontainer) can use keys that stay on yours: hush on a tailnet.

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 tryhush.dev.

• Using it — Sets · Coming from another tool · Several keys for one service · Running things · Credentials that are a file · The app · The shell hook (including Nushell)
• 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.