Skip to content

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.

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.

  1. Open Settings → Secrets (organization) or the project’s Settings → Secrets, then New secret.

  2. 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 older
    Description Optional
  3. Save.

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:

Example deployment error
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.

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.

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.

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.

  • 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_KEY nor 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.
  • Classic sites (PHP, Node, Bun, Deno, static): the site’s .env lives on a tmpfs, /run/falak/env/<site>.env (mode 0440, the site’s user and group); the release’s .env is 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’ .env works 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_PASSWORD on a tmpfs, so docker inspect never 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, …; not VITE_, NEXT_PUBLIC_ and other browser variables).
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