# Environment Variables

- Canonical URL: https://docs.fairvisor.com/docs/deployment/env/
- Section: docs
- Last updated: n/a
> Complete reference for all Fairvisor Edge environment variables.


Fairvisor Edge is configured entirely through environment variables. The `entrypoint.sh` validates required variables at startup and fails fast if the configuration is invalid.

## Core variables

| Variable | Type | Required | Default | Description |
|---|---|---|---|---|
| `FAIRVISOR_MODE` | string | No | `decision_service` | Operating mode. `decision_service` or `reverse_proxy`. |
| `FAIRVISOR_CONFIG_FILE` | string | Conditional | — | Path to local policy bundle JSON. Required when `FAIRVISOR_SAAS_URL` is not set. |
| `FAIRVISOR_SAAS_URL` | string | Conditional | — | Base URL for SaaS config delivery (e.g., `https://api.fairvisor.com`). |
| `FAIRVISOR_EDGE_ID` | string | Conditional | — | Edge instance identifier. Required when `FAIRVISOR_SAAS_URL` is set. |
| `FAIRVISOR_EDGE_TOKEN` | string | Conditional | — | Bearer token for SaaS API authentication. Required when `FAIRVISOR_SAAS_URL` is set. |
| `FAIRVISOR_BACKEND_URL` | string | Conditional | `http://127.0.0.1:8081` | Upstream backend URL. Required when `FAIRVISOR_MODE=reverse_proxy`. |

## Timing variables

| Variable | Type | Default | Description |
|---|---|---|---|
| `FAIRVISOR_CONFIG_POLL_INTERVAL` | integer (seconds) | `30` | How often to poll SaaS for a new config bundle. Must be > 0. |
| `FAIRVISOR_HEARTBEAT_INTERVAL` | integer (seconds) | `5` | How often to send a heartbeat to SaaS. Must be > 0. |
| `FAIRVISOR_EVENT_FLUSH_INTERVAL` | integer (seconds) | `60` | How often to flush the event buffer to SaaS. Must be > 0. |

## Runtime tuning

| Variable | Type | Default | Description |
|---|---|---|---|
| `FAIRVISOR_SHARED_DICT_SIZE` | string | `128m` | Size of the Lua shared dict that holds all counter state. Accepts nginx size syntax: `128m`, `256m`, `1g`. |
| `FAIRVISOR_LOG_LEVEL` | string | `info` | Nginx `error_log` level. Valid values: `debug`, `info`, `notice`, `warn`, `error`, `crit`, `alert`, `emerg`. |
| `FAIRVISOR_WORKER_PROCESSES` | string | `auto` | Nginx `worker_processes` directive. Set to a number (e.g., `4`) or `auto`. |
| `FAIRVISOR_DEBUG_SESSION_SECRET` | string | — | Enables the per-session debug endpoints (`POST /v1/debug/session`, `POST /v1/debug/logout`). When set, requests carrying a valid signed debug cookie receive `X-Fairvisor-Debug-*` headers. |

## Validation rules

The startup script (`entrypoint.sh`) enforces these rules and exits non-zero if violated:

```
1. FAIRVISOR_MODE must be "decision_service" or "reverse_proxy"
2. If FAIRVISOR_MODE = "reverse_proxy":
     → FAIRVISOR_BACKEND_URL is required
3. If FAIRVISOR_SAAS_URL is set:
     → FAIRVISOR_EDGE_ID is required
     → FAIRVISOR_EDGE_TOKEN is required
4. Else (no SAAS_URL):
     → FAIRVISOR_CONFIG_FILE is required
5. *_INTERVAL values must be positive integers
```

## Mode reference

### Standalone

```bash
FAIRVISOR_MODE=decision_service
FAIRVISOR_CONFIG_FILE=/etc/fairvisor/policy.json
```

### SaaS

```bash
FAIRVISOR_MODE=decision_service
FAIRVISOR_SAAS_URL=https://api.fairvisor.com
FAIRVISOR_EDGE_ID=edge-prod-us-east-1
FAIRVISOR_EDGE_TOKEN=fvt_live_xxxxxxxxxxxxx
FAIRVISOR_HEARTBEAT_INTERVAL=5
FAIRVISOR_CONFIG_POLL_INTERVAL=30
FAIRVISOR_EVENT_FLUSH_INTERVAL=60
```

### Reverse proxy

```bash
FAIRVISOR_MODE=reverse_proxy
FAIRVISOR_CONFIG_FILE=/etc/fairvisor/policy.json
FAIRVISOR_BACKEND_URL=http://my-api-service:3000
```

## Sensitive values

`FAIRVISOR_EDGE_TOKEN` is a bearer secret. Do not log or expose it:

- In Docker: use a secrets mount or pass it at runtime (`-e`)
- In Kubernetes: mount as a `Secret` volume or use `envFrom`
- In CI/CD: store as a masked/protected variable, never in source code