Env and secrets

Your app's configuration lives in two stores. Both arrive at your process as ordinary environment variables, and from inside the app you cannot tell them apart. The difference is what happens to the value on the way there, and it is worth getting right the first time.

Plain config goes in carlos env:

carlos env set -app hello LOG_LEVEL=debug

Credentials go in carlos secrets. Same shape:

carlos secrets set -app hello STRIPE_KEY=sk_live_example

Which store a value belongs in

Ask whether you would mind the value appearing in a screenshot. A log level, a feature flag, the public URL of a service you call — nobody cares, and carlos env keeps them readable, which is what you want when you are working out why staging behaves oddly.

An API key, a database URL with a password in it, a signing secret, anything a third party issued you: carlos secrets. If in doubt, the sealed store costs you nothing except the ability to read the value back, so put it there.

What sealing actually does

carlos secrets set seals the value on your machine, using the deployment's public key, before anything leaves your terminal. What gets stored is an envelope. The private half of that key lives on the box that runs your app and never leaves it, so the console holds a secret it cannot itself open.

The consequence is the one thing people trip over: nothing can show you the value again. carlos secrets list prints key names and stops there. Lose the value and your only move is setting a new one.

One practical wrinkle. The value is on your command line when you type it, so your shell history keeps a copy of it. Clear that out on a machine other people use.

Getting the new value into your app

Changing config converges on its own. The write bumps a marker, every box serving the app notices within seconds, rewrites the environment file for each of the app's routes, and cycles the process so it comes back holding the new value. There is no separate deploy, and no restart for you to remember.

Two things follow from the cycling. A config change is a small interruption for a running app, so batch related changes into one call — carlos env set takes several KEY=value pairs at once. And a change that appears not to have taken effect is more likely to be your app reading the variable once at startup than the platform failing to deliver it.

To see what is set:

carlos env list -app hello

That prints values as well as names, and the sealed store's list prints names alone. Both families also take unset with a key name, and the reference pages for carlos env and carlos secrets have their remaining sub-verbs.

If you take one thing from this page: put the credential in the sealed store on the day you first set it. Moving it later means rotating it, because by then it has been sitting somewhere readable.