The problem
enveil run -- cmd puts real values into the child's environment. That keeps them off disk and out of the transcript as long as nothing prints them, but an agent that can run cmd can also run env, or write a script that sends os.environ somewhere. A scope decides which secrets a credential gets; it cannot stop the process that received them from doing what it likes with them.
Most API keys are only ever sent to one or two HTTPS hosts. Proxy mode uses that: the command gets a placeholder, and the real value is put into the request only on its way to an allowed host, by the server.
Allowed hosts
Each secret can have a list of hosts it may be sent to. The list is stored on the server, per secret, and applies in every environment:
enveil hosts STRIPE_SECRET_KEY api.stripe.com # set the allowed hosts
enveil hosts STRIPE_SECRET_KEY # show them
enveil hosts STRIPE_SECRET_KEY --clear # stop proxying it
enveil set STRIPE_SECRET_KEY --hosts api.stripe.com,files.stripe.comChanging hosts needs write access to the whole project, and every change is recorded as secret_proxy_hosts_changed: adding a host widens where a credential can go.
Running with --proxy
enveil run --proxy -- bun run devWhat happens:
- The CLI fetches metadata only: which keys have allowed hosts, and those hosts. No value is downloaded.
- The child gets a random placeholder per key, such as
__enveil_STRIPE_SECRET_KEY_…__, new on every run. - The CLI starts a local HTTPS adapter and points the child at it with
HTTPS_PROXYand friends. - For an HTTPS request to an allowed host, the adapter sends the request, placeholders included, over authenticated HTTPS to the enveil server.
- The server checks the credential and the allowed hosts on that request, decrypts only the secrets whose placeholders appear in it, substitutes them, and connects to the upstream itself. The response streams back, SSE included.
At startup the CLI prints, on stderr, each proxied key and the hosts it goes to. It contains no value and is safe to show. What was actually injected, and where, is in the audit trail.
What is substituted
Request headers, the URL path and query string (percent-encoded), and Authorization: Basic credentials. Request bodies are never substituted, so an API that wants its key in a JSON body cannot be used this way. A value in a body is one the application chose to send, and rewriting arbitrary payloads would put credentials into places no host list can reason about.
Plain HTTP requests, and HTTPS requests to hosts on no secret's list, pass through the adapter untouched, placeholders and all.
What the server refuses
Upstream requests go only to the allowed hosts, over HTTPS on port 443. Private, loopback and link-local addresses are refused, DNS answers are pinned to the connection, and redirects are returned to the client rather than followed, so the next hop gets a fresh policy check.
Changes apply live, mostly
The server reads the credential, the hosts and the value on every request. Revoking the identity, its expiry, rotating the value or removing a host takes effect on the next request without restarting the command.
The local adapter learns the allowed hosts at startup. A host added while the command runs is not relayed until the command restarts.
Which secrets the command gets
Only secrets with allowed hosts. Everything else, DATABASE_URL for example, is left out, and there is no plaintext fallback, also not against an older server. If an environment has no proxied secrets at all, run --proxy stops with an error. Supply the rest from your application's development configuration.
The enveil server URL must use HTTPS; loopback HTTP is allowed for local development.
The local CA
The adapter terminates TLS for allowed hosts, so the child has to trust its certificate authority. The CA lives in ~/.config/enveil/proxy-ca (or $XDG_CONFIG_HOME/enveil/proxy-ca), created on first use, with the key readable only by its owner. The CLI writes a bundle of that CA plus the public roots and points the child at it through:
SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO, DENO_CERT
It also sets HTTPS_PROXY, HTTP_PROXY (and the lowercase forms), NODE_USE_ENV_PROXY=1, and extends NO_PROXY with localhost,127.0.0.1,::1, keeping any NO_PROXY you had.
Clients must honour these settings. Certificate pinning and non-HTTP protocols do not work through the proxy.
Proxy-only identities
Proxy mode protects most when the credential cannot read values either. Give an agent a machine identity with the proxy capability: it can use secrets through the proxy and is refused reads, exports, history and writes. With such a token in ENVEIL_TOKEN, plain enveil run switches to --proxy by itself and says so on stderr.
A read or write credential works with --proxy too, but it can still fetch plaintext some other way.
Each use is metered against the credential's read budget, one unit per secret injected, and recorded as secret_proxied, separately from secret_read. If the audit write fails, nothing is injected.
Approvals
A secret can also need a person's approval before the proxy injects it for a machine identity:
enveil hosts STRIPE_SECRET_KEY --approval on # ask first
enveil hosts STRIPE_SECRET_KEY --approval off # stop askingThe first time an identity uses the key at a host, the server refuses the request with a 403 and a body the agent can pass on:
Approval needed to use STRIPE_SECRET_KEY at api.stripe.com: https://enveil.example/approvalsThe CLI prints the same line once on stderr, for whoever is watching the command. The request now waits on the Approvals page in the web app. Approve it for 1 hour, 1 day, 30 days or until revoked, or deny it; then the agent retries. Nothing is decrypted, metered or recorded as secret_proxied while it waits, and the agent never sees the value either way.
- A grant covers one identity, one secret, one environment and one host. The same agent using the key in
prod, or at another host, asks again. - Retries while a request waits update it rather than adding more. A denied, revoked or expired grant is asked for again on the next use.
- Only machine identities are asked. Your own login is the person who would approve.
- Turning approval on or off needs write access to the whole project and is recorded as
secret_proxy_approval_changed. A machine identity can do neither, nor approve. - Anyone who can write the project can approve, deny or revoke, except in a protected environment, where it takes an admin. Each decision is in the audit trail.
What it is not
- Not a sandbox. The command still runs with your user's permissions and network.
- Not an operation allowlist. A proxy-only identity can do anything at the allowed host that the key itself allows: create charges, delete data.
- Not a guarantee the value stays hidden. The proxy controls where a credential is sent. It cannot stop an upstream from reflecting it in a response, logging it or storing it. Only allow hosts you trust with the key.