notenv

Encrypted secrets, no infrastructure, no plaintext on disk.

notenv replaces .env files: secrets are encrypted on your machine with age, kept as ciphertext in a local vault or on storage you already own (Backblaze B2, S3, Google Drive, SFTP, WebDAV, anything rclone speaks), and decrypted only into the environment of the command you run. Plaintext never touches disk.

Why

A .env file is plaintext: everything on your machine can read it, and sharing it means pasting it somewhere it will outlive. notenv removes the file instead of guarding it.

• You hold the key, not a provider. Secrets are age-encrypted locally; storage only ever sees ciphertext. No account to create, no SaaS to trust, no vendor that can read, lock, or lose your data.
• Storage you already own. A local folder, the NAS under your desk, B2, S3, Drive, SFTP, WebDAV, dozens more, and you can move between them when syncing across machines starts to matter.
• Nothing on disk to leak. A test runner, a package's postinstall script, or a coding agent in your checkout cannot read a secret that exists only inside the process you ran, only while it runs.
• Easy to share, clean to leave. Share a vault with a collaborator in seconds, and when they leave, they can no longer read it, instead of you just hoping they deleted their copy. No lock-in either; you can leave with your secrets for a different solution easily.
• Nothing to operate. Setup is one passphrase and zero accounts. No server to stand up, patch, or pay for.

Not this if you want a platform: there is no web console or SSO, and access is scoped per vault, not per secret (everyone in a vault can read that vault). If a platform team already runs Vault, keep Vault.

Install

uv tool install notenv                                  # also: pipx install notenv, or pip
go install github.com/DvGils/notenv/cmd/notenv@latest   # with Go

Or download a prebuilt binary for Linux, macOS, or Windows (amd64 / arm64) from Releases and put notenv on your PATH. Releases are reproducible, signed with cosign (keyless), and carry SLSA build provenance; the installation guide shows how to verify a download.

Quick start

notenv setup                   # 1. set up this machine once (local vault by default)
cd my-project && notenv init   # 2. declare the project (writes notenv.toml, which you commit)
notenv namespace import .env && rm .env  # 3. import existing secrets (or `notenv secret set KEY` one at a time)
notenv run -- npm run dev      # 4. run anything with the secrets injected

That is the whole loop. notenv is a process wrapper, so it works with any language that reads environment variables. On a new machine: git clone, then notenv setup with your escrowed passphrase, and you are ready. When syncing across machines starts to matter, notenv vault copy moves the same vault to a cloud remote in one command.

Documentation

Full docs live at dvgils.github.io/notenv:

• Quick start and installation
• Guides: share a vault with your team, cloud remotes, export or delete a vault, AI agents
• Reference: commands, configuration
• Concepts: how it works, keys and slots
• Security: threat model

How it works

notenv run -- cmd
  |
  |-- fetch ciphertext   <- rclone <-  your B2 / S3 / Drive / ...
  |-- unlock the master key (from your passphrase; cached after first use)
  |-- decrypt secrets in memory
  |-- build the child environment from notenv.toml
  |-- exec cmd, stream its I/O, exit with its code
        nothing written to disk

A random master key encrypts every secret and never exists in plaintext at rest: a small header holds it wrapped under one or more key slots (a person's passphrase or a machine's age public key), the way LUKS and restic do it. The header is authenticated and version-pinned, so a party who can write your storage but holds no key cannot tamper with it or roll it back undetected. Full detail in Concepts.

For AI agents

A .env on disk eventually lands in a coding agent's context. notenv handoff -- <agent> runs the agent against an ephemeral vault holding only one namespace, so it can use your secrets but never holds the key to the rest of your vault, and injected values are masked out of its output. Inside the session it uses notenv run -- cmd and notenv namespace inspect, never touching a raw value. Its MCP servers can draw their own credentials from notenv too, so a token never sits in plaintext in your shell or .mcp.json. An installable agent skill (skills/notenv/) teaches it the commands. See the AI agents guide and MCP servers.

How it compares

dotenvx and op run both nail encrypted injection; the difference is the master. dotenvx keeps the encrypted file in your repo and leaves distributing and rotating the private key to you; 1Password is excellent but is a service that holds your secrets and that you depend on. SOPS + age give you the keys but leave storage and onboarding as homework. notenv is the one combination of all three: keys you hold, storage you already own, and onboarding built in, with nobody in the loop.

Security

At rest, anywhere, only age ciphertext exists; it is useless without your key, which lives in your password manager and never on the storage backend. The threat model covers what notenv defends, against whom, and the explicit non-goals. To report a vulnerability, see SECURITY.md.

Building from source

git clone https://github.com/DvGils/notenv
cd notenv
make build       # compile ./notenv
make test        # run the test suite
make install     # install into $(go env GOPATH)/bin

Releases are produced with GoReleaser; make snapshot builds the full set of release artifacts locally without publishing.

Status

Stable. notenv follows a compatibility contract: within the 1.x line the storage format and documented interface stay compatible, so upgrading never breaks a vault or a script. See the roadmap for what works today, what is planned, and the non-goals.

License

Apache-2.0.