Secret store
Since v0.10.0 Falak has a secret store: named secrets with immutable versions, an access log, and optional links to an external provider (Vault, AWS, 1Password, Doppler, Infisical or your own HTTPS endpoint). Sites read them with ${{ secrets.NAME }} references, so a value lives in one place and never has to be copied into each site.
Scopes
Section titled “Scopes”A secret belongs to one scope. Names are environment variable names (^[A-Z_][A-Z0-9_]*$), unique per scope.
| Scope | Where to manage it | Seen by |
|---|---|---|
| Organization | Settings → Secrets | every service of the organization |
| Project | Project Settings → Secrets | every service of the project |
| Environment | Project Settings → Secrets | the services of one environment |
| Service | Project Settings → Secrets | one service |
A reference resolves to the nearest secret of that name: the service’s own, then its environment’s, its project’s, then the organization’s. So a project secret can override an organization default, and a production secret can override the project’s.
Create a secret
Section titled “Create a secret”-
Open Settings → Secrets (organization) or the project’s Settings → Secrets, then New secret.
-
Fill in:
Field Meaning Name Capital letters, digits and underscores, like an environment variable Scope Organization, project, environment or service Source Value (stored in Falak) or Linked to a provider (see Secret providers) Sensitive On by default. Write-only: once saved, no one can read the value back, only replace it Available to preview environments Off by default. Only these secrets reach preview environments Rotate every Days. Flags the secret, and fires secrets.rotation_due, when its value is olderDescription Optional -
Save.
Use it in a site
Section titled “Use it in a site”Reference the secret from a site’s variables:
STRIPE_SECRET=${{ secrets.STRIPE_SECRET }}It resolves at deploy time, like other references. A secret that doesn’t exist fails the deployment before anything changes on your servers:
STRIPE_KEY: secret STRIPE_KEY is not defined for this service …Each read is recorded in the secret’s access log (once per deployment and version): who or what read which version, and why.
Promote a variable
Section titled “Promote a variable”A plain variable can become a secret in one step: Promote a variable to a secret on the Secrets page. Pick the service and the variable, name the secret, and choose whether it is sensitive. The value moves into a new secret of that service, and the variable becomes ${{ secrets.NAME }} — in its current version and every older one, so restoring an old environment version can’t bring the value back. Only plain values can be promoted, not ${{ … }} references.
Versions and rollback
Section titled “Versions and rollback”Every new value is a new immutable version; the history is never rewritten. A new value is used from the next deployment.
- Roll back to a version: Falak creates a new version holding that version’s value.
- Disable a version: it can no longer be restored.
- Deleting a secret deletes every version; the access log stays, and references to it fail the next deployment.
For linked secrets, rolling back to a version that recorded its value upstream pins the secret to that value; see Rolling back a linked secret.
Reveal
Section titled “Reveal”Only non-sensitive secrets can be revealed. Revealing needs secrets.reveal and a recent re-authentication: Falak asks for your password (and your authentication code with two-factor authentication) when you haven’t confirmed it in the last 5 minutes. Every reveal is in the access log and the audit log, and more than 20 reveals by one user within 10 minutes fire secrets.unusual_reveals.
API tokens need the secrets.reveal ability by name; * is not enough.
How secrets are protected
Section titled “How secrets are protected”- Every value is encrypted with AES-256-GCM under the organization’s data key and bound to its organization, secret and version: a value copied to another row no longer decrypts.
- Data keys are wrapped by the control plane’s key-encryption key (KEK), which is neither
APP_KEYnor stored in the database or.env. See Encryption keys. - The UI and the API return metadata only (name, scope, versions, last access), never values, unless revealed.
On your servers
Section titled “On your servers”- Classic sites (PHP, Node, Bun, Deno, static): the site’s
.envlives on a tmpfs,/run/falak/env/<site>.env(mode 0440, the site’s user and group); the release’s.envis a symlink to it. After a reboot the agent reports the missing file and the control plane sends it again, so secrets are never written to persistent disk. Compose releases’.envworks the same way. - Docker sites: Settings → Deploy → Secrets chooses Environment variables (default) or Files in /run/secrets — each secret variable becomes a file such as
/run/secrets/DB_PASSWORDon a tmpfs, sodocker inspectnever shows it. Applies from the next deploy. - Masking: the values of secret variables are replaced with
••••in deploy, hook, build and command output before anything leaves the server (also their base64 and URL-encoded forms), and the control plane masks the deployment log again. Secret variables are those that reference a secret, and those whose name looks like one (*PASSWORD*,*SECRET*,*TOKEN*,*_KEY,DATABASE_URL, …; notVITE_,NEXT_PUBLIC_and other browser variables).
Permissions
Section titled “Permissions”| Action | Permission | Roles |
|---|---|---|
| See names, metadata, versions, access log and usage (never values) | secrets.view |
owner, admin, developer, viewer |
| Create secrets, set values, roll back, disable versions, delete | secrets.manage |
owner, admin, developer |
| Reveal non-sensitive values | secrets.reveal |
owner, admin, developer |
| Add, edit, test and delete providers | secrets.providers.manage |
owner, admin |