Introduction

What enveil is, who it is for, and why it is shaped the way it is

What enveil is

enveil stores the secrets for a project: API keys, database URLs, signing keys. A project holds environments (dev, staging, prod), and each environment holds one versioned value per key.

Values are encrypted at rest under a key that belongs to the project. Every time a value leaves the server, the read is recorded against whoever asked. And an agent gets its own credential, scoped to the environments it needs, instead of borrowing a person's.

Who it is for

Projects where people and coding agents work side by side. A person signs in through a browser and acts with their own role in the organization. An agent runs with a machine identity that reaches only the environments it was given, at a bounded rate, and can often use a key without being able to read it.

Both use the same CLI, the same store and the same audit trail. What differs is what each credential is allowed to do.

Why it is shaped this way

An agent is not a user

A personal API key carries everything its owner can reach, which in a secret manager is every project in the organization. That is too much for something that runs unattended.

enveil issues machine identities instead: a token with an explicit list of scopes, its own expiry, and revocation that leaves the person who created it untouched.

A scope is not a limit

An identity scoped to one environment can still read every secret in it, in a loop, in seconds. So each identity also has a read budget, per minute and per hour, charged per secret disclosed: an export of twenty keys costs twenty.

Going over is refused and recorded, and the organization's owners and admins are emailed, at most once a day per identity. This bounds mass reads and slow enumeration and makes a runaway agent visible. It does not stop one authorised export of what is already in scope. See Audit and budgets.

Undoing a bad rotation should not require seeing the secret

Writes append. A new value archives the one it replaces, and rollback copies an archived value forward without decrypting it. Recovering from a broken deploy never puts a credential in front of a person, or an agent, who only needed the outage to stop. See Versions and rollback.

The read is the interesting event

A write is deliberate. A read is how a credential actually leaves the system. Every read is recorded with who, what, when and from where, and the audit write sits in the same function that decrypts, so a new endpoint cannot return a value without recording it.

Secrets should not need to touch disk

enveil run -- your-command puts the environment into a child process and writes nothing. enveil pull exists for tools that insist on a real .env, and warns when the file it wrote is not gitignored.

For a key that only ever goes to known HTTPS APIs, enveil run --proxy goes further: the command gets a placeholder, and the server injects the real value into requests to the allowed hosts. See Proxy mode.

Where next