Secrets and keys

An instance runs on two secrets in .env. One you can rotate freely, but the other, if you lose it, takes stored credentials with it. Knowing which is which is most of what this page is for.

The setup builder generates both for you and makes you confirm you've saved the encryption key before the download unlocks. If you edit .env by hand, both must be at least 16 characters, and the api refuses to start if either is missing or too short.

The encryption key is the crown jewel

TENANT_CREDS_ENCRYPTION_KEY encrypts, at rest, the per-workspace credentials Cobblr stores. Treat it differently from every other setting:

• Back it up off the box, the day you create the instance. A password manager entry or an encrypted note is enough. Keep it wherever you keep the recovery material for things you couldn't rebuild.
• Keep it with the data. When you back up ./data/, back up the .env alongside it, so a restore has the key the data was encrypted with.
• Don't rotate it casually. Changing it orphans everything already encrypted. If you must, plan to reconnect every integration afterward.
• Losing it is unrecoverable. There is no backdoor and no reset.

Any strong random string works. openssl rand -hex 32 produces one.

What it protects, and what losing it costs

The credentials it encrypts are the API keys and tokens you enter when you connect an integration or an outside service. Those values are encrypted with AES-256 before they touch the database, using a key derived from this secret.

If the key is gone, or you restore a database without the matching key, every stored credential becomes ciphertext no one can read. The rest of the instance is fine, and the data isn't corrupted, but each affected integration has to be reconnected with its secret entered again.

The JWT secret signs sessions

JWT_SECRET signs the login tokens that keep people signed in.

• Rotating it is safe: it is not tied to stored data, so the one effect is that every active session is invalidated and everyone signs in again, a reasonable move if you think a session token leaked.
• Generate it the same way, openssl rand -hex 32, and keep it out of anywhere public.
• No off-box archival needed, unlike the encryption key: losing it costs a round of re-logins, not data.

Handling secrets as the operator

A few habits keep secrets from leaking through the side door:

• Keep them in .env, never in the compose file or a shell command. .env is the one place for values like these, and it's easy to keep out of version control. A secret typed on a command line lands in your shell history.
• When you need to hand a secret to a helper file (a token for a script, a provider key), point the tool at a file it reads, rather than pasting the value inline. The value stays in one place you control and never scrolls through a terminal.
• Don't commit .env. If you keep your compose setup in a git repo, add .env to .gitignore. Back it up privately instead.

Provider keys and integration credentials that live inside a workspace (your AI key, a connected service's token) are covered separately in Personal connections. The instance encrypts those with the key above and never shows them back to the workspace.

For the full list of configurable values, see Configuration.