# Environment variables

> Manage a Falak site's environment variables — the raw dotenv editor, versions, references, variables at build time, and pulling or pushing .env files.

Source: https://falak.sh/docs/guides/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.

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:

```json title="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:

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

See [Variable references](/docs/guides/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](/docs/deploy/monorepos/).

## Pull and push with the CLI

```bash
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

```bash
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"}'
```

```json title="Response"
{"data": {"version": 4, "changed": true, "keys": ["APP_ENV", "APP_DEBUG"]}}
```

`422` with `errors.content` when the dotenv cannot be parsed. See [Sites API](/docs/api/sites/).

## 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