Secrets

A secret is the encrypted-at-rest storage primitive; a credential (an LLM provider API key, an integration token, a git access token) is the auth material it backs. TulipFarm stores credentials as secrets in two layers.

Two layers

• Bootstrap env config are environment variables set before the instance starts: ENCRYPTION_KEY, JWT_SECRET, WEBHOOK_SIGNING_SECRET, and the database connection. The setup script generates the random ones into .env.local. Most of these values aren't credentials at all — ENCRYPTION_KEY is the one genuinely secret value in this bucket.
• Application secrets are everything you add at runtime — provider credentials and custom values. These are encrypted with AES-256-GCM and stored in the datastore, never in plaintext and never in the soul.

The ENCRYPTION_KEY protects the application secrets — it wraps the data key that actually encrypts them. Its length is validated at startup, so a malformed key fails fast rather than silently corrupting writes. See Encryption for how the wrapping, recovery, and at-rest validation work.

Values are write-only

You can store a secret and you can delete it, but you can never read its value back. The status view lists which keys are set and their metadata — never the values themselves. Writing secrets is restricted to admins.

Key rotation without breakage

Rotating your ENCRYPTION_KEY does not re-encrypt your secrets. Each secret is encrypted under a data key that the ENCRYPTION_KEY only wraps, so rotation re-wraps that single key rather than every value. Set the old key as ENCRYPTION_KEY_PREVIOUS alongside the new ENCRYPTION_KEY and run keys rotate-kek; reads keep working because unwrapping tries the current key first, then the previous one. A lost ENCRYPTION_KEY is recoverable through an offline recovery key — see Encryption.

To add or remove a secret, see Store a secret.