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. For API keys and passwords shared between services, use the secret store and reference them with ${{ secrets.NAME }}.
Edit variables
Section titled “Edit variables”- Open the site’s panel → Variables.
- Add a row with New variable, or switch to the Raw editor to paste a whole dotenv file (you see a diff before saving).
- Save. A bar reminds you that changes apply on the next deploy.
- Click Deploy.
Values are masked. Revealing a value is recorded in the audit log.
Versions
Section titled “Versions”Each save creates a new version of the environment. The API returns it:
{"data": {"content": "APP_ENV=production\nAPP_KEY=base64:…\n", "version": 3}}Variables Falak adds
Section titled “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
Section titled “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.
Secrets
Section titled “Secrets”Reference a secret from the secret store instead of pasting its value:
STRIPE_SECRET=${{ secrets.STRIPE_SECRET }}An existing variable can be moved into the store with Promote a variable to a secret on the Secrets page.
Where the values live on a server
Section titled “Where the values live on a server”- Classic sites: the
.envis on a tmpfs (/run/falak/env/<site>.env, mode 0440);shared/.envand the release’s.envare symlinks to it. After a reboot the agent asks for it again, so variables never reach persistent disk. - Docker sites: environment variables by default, or secret variables as files in
/run/secrets(Settings → Deploy → Secrets). - Output masking: values of secret variables (secret references, and names like
*PASSWORD*,*TOKEN*,*_KEY,DATABASE_URL) are shown as••••in deploy, hook and build output.
Variables at build time
Section titled “Variables at build time”Builds only see:
- variables starting with
VITE_,NEXT_PUBLIC_,NUXT_PUBLIC_,PUBLIC_orREACT_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
Section titled “Pull and push with the CLI”falak env pull shop > .env.production # to stdoutfalak env pull shop --file .env.production # written with mode 0600falak env push shop --file .env.production # replaces ALL variablesfalak env push shop < .env.production # same, from stdinfalak deploy shop --wait # applypush 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
Section titled “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"}'{"data": {"version": 4, "changed": true, "keys": ["APP_ENV", "APP_DEBUG"]}}422 with errors.content when the dotenv cannot be parsed. See Sites API.
Permissions
Section titled “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
Section titled “Limits”- Up to 500 variables when creating a site through the API; each value up to 64 KiB.
- Edit variables in Falak, not in
.envon a server: the file is on a tmpfs that Falak writes on every deploy and after a reboot, and hand edits on one server do not reach the others.