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

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

SaaS

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

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