EnvVault

Keep real secrets out of project .env files and coding-agent prompts.

EnvVault replaces plaintext .env secrets with repository-safe envvault:// references. At runtime, it resolves credentials from the OS credential store or starts a localhost proxy that gives the app a local URL and local proxy token.

Links: Documentation | Homebrew tap

The default compatibility path stores the real credential in the OS credential store and keeps only a repository-safe direct reference in .env:

APP_SECRET=envvault://app/dev
DATABASE_URL=envvault://database/dev

For APIs and SDKs that accept a custom endpoint, EnvVault also has an experimental localhost proxy mode. The child process receives a local proxy URL and local token instead of the real upstream credential:

APP_BASE_URL=envvault://api-proxy/dev/base-url
APP_API_TOKEN=envvault://api-proxy/dev/token

Public reference forms are intentionally small:

• envvault://<credential> resolves a direct credential.
• envvault://<proxy>/base-url and envvault://<proxy>/token resolve generated proxy outputs.

Install

Install EnvVault from the Homebrew tap:

brew install trknhr/tap/envvault

Common commands:

envvault admin start
envvault credential list
envvault proxy list
envvault exec --env APP_SECRET=envvault://app/dev -- npm run dev
envvault exec --env-file .env -- npm start

envvault admin start starts the local browser UI for adding credentials and creating optional proxies. The printed URL includes a per-run local admin token. The UI does not display stored credential values.

The default flow intentionally passes the resolved credential to the child process environment at launch. Use proxy mode only when an API client accepts a custom base URL and you want to avoid passing the real upstream credential to the child process.

Security Limitations

EnvVault reduces credential exposure; it does not create a sandbox.

• A child process can read any credential value or local proxy token placed in its environment until it exits.
• A process running as the same OS user can use the same OS credential store permissions as the user.
• If the OS credential store is compromised, stored credentials are compromised.
• EnvVault does not redact prompts, stdout, stderr, HTTP bodies, shell history, or application logs outside its own outputs.
• Direct envvault://<credential> references resolve to raw credential values. This is the default compatibility path for local development.
• Proxy mode can reduce raw-secret exposure, but it requires the app or SDK to accept a custom base URL and bearer token.

Status

This repository contains the local-first implementation path: strict reference parsing, OS keyring abstraction, browser admin server, direct credential resolution, optional provider proxies, process environment construction, metadata-only audit records, reset/doctor support, runnable examples, and acceptance fixtures.

Local archive packaging is available through go run ./cmd/envvault-release package, and local Homebrew/Scoop metadata can be generated with go run ./cmd/envvault-release package-manifests. .github/workflows/ci.yml defines the test, vet, race, release, and secret-scan gate for macOS and Ubuntu runners. .github/workflows/release.yml publishes tagged release archives and updates the Homebrew tap.

Documentation

• Documentation site
• Quickstart
• Proxies
• Threat model
• Uninstall
• Recovery
• Third-party notices

Agent Skill

EnvVault includes an agent skill at skills/envvault/SKILL.md. Install it with the skills CLI:

npx skills add trknhr/envvault --skill envvault

From a local checkout, use:

npx skills add . --skill envvault

Check installed skills:

npx skills list

Use the skills CLI options to choose global/project scope or a specific agent, for example -g for global installation or -a <agent>. Restart your agent after installing or updating skills.

Examples

• Gemini SDK app example
• Env app example
• OpenAI-compatible proxy app example
• Gemini AI SDK proxy app example

Development

Run the standard verification set:

go test ./...
go vet ./...
go test -race ./...

No command should print raw secrets, resolved credentials, Authorization headers, or local proxy bearer tokens.