Environment variables

Every site has an encrypted set of environment variables. Falak writes them into each release’s .env and into the environment of the site’s processes. This page shows how to edit them and when changes take effect.

Edit variables

1. Open the site’s panel → Variables.
2. Add a row with New variable, or switch to the Raw editor to paste a whole dotenv file (you see a diff before saving).
3. Save. A bar reminds you that changes apply on the next deploy.
4. Click Deploy.

Values are masked. Revealing a value is recorded in the audit log.

Changes need a deployment

A release keeps the variables it was deployed with. Saving variables does not restart anything. Redeploy to apply them. Rolling back restores the old release with its old variables.

Versions

Each save creates a new version of the environment. The API returns it:

GET /api/v1/sites/shop/env

{"data": {"content": "APP_ENV=production\nAPP_KEY=base64:…\n", "version": 3}}

Variables Falak adds

You do not set these; every release gets them:

Variable	Value
FALAK_SITE_ID, FALAK_SERVER_ID, FALAK_DEPLOYMENT_ID, FALAK_RELEASE_ID	Upper-case ULIDs
FALAK_SITE	The site slug (process environments)
PORT, HOST	The app port and 127.0.0.1 (Node, Bun, Deno web processes; PORT for Docker)
NODE_ENV	production for JavaScript web processes unless you set it

Presets add initial variables when a site is created (for example APP_KEY for Laravel); after that they are yours to edit.

Reference other services

Values can reference another service in the same environment:

DATABASE_URL=${{ shop-db.DATABASE_URL }}
REDIS_HOST=${{ cache.REDIS_HOST }}

See Variable references.

Variables at build time

Builds only see:

• variables starting with VITE_, NEXT_PUBLIC_, NUXT_PUBLIC_, PUBLIC_ or REACT_APP_;
• variables marked Expose to deploy script.

Expose to deploy script is a per-variable switch. Exposed variables are also exported into your deploy script sections, so you can use them in custom steps.

Two variables change the build itself: FALAK_INSTALL_COMMAND and FALAK_BUILD_COMMAND. See Monorepos and build commands.

Pull and push with the CLI

falak env pull shop > .env.production              # to stdout
falak env pull shop --file .env.production         # written with mode 0600
falak env push shop --file .env.production         # replaces ALL variables
falak env push shop < .env.production              # same, from stdin
falak deploy shop --wait                           # apply

push refuses an empty file. It replaces the whole environment, so always pull, edit and push the complete file. Keys that were exposed to the deploy script stay exposed.

Through the API

curl -X PUT https://falak.example.com/api/v1/sites/shop/env \
  -H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"content": "APP_ENV=production\nAPP_DEBUG=false\n"}'

Response

{"data": {"version": 4, "changed": true, "keys": ["APP_ENV", "APP_DEBUG"]}}

422 with errors.content when the dotenv cannot be parsed. See Sites API.

Permissions

Action	Permission	Roles
Reveal / read variables	sites.env.view	owner, admin, developer
Edit variables	sites.env.manage	owner, admin, developer

Viewers cannot read variable values.

Limits

• Up to 500 variables when creating a site through the API; each value up to 64 KiB.
• Edit variables in Falak, not in shared/.env on a server: Falak writes each release’s environment at deploy time, and hand edits on one server do not reach the others.

Next steps

Variable referencesConnect services with ${{ service.KEY }}.

Deploy scriptsUse variables in custom steps.