Environment Variables

QUBIQ reads configuration from the environment and from a .env file in its data directory. The file is created automatically on first boot with generated secrets.

Most of these are set for you by the installer. Edit .env only for the deployment-specific settings — TLS, allowed origins, trusted proxies, login policy.

.env holds ENCRYPTION_KEY

Losing it makes every stored connection credential and the configuration database unrecoverable. Back it up separately from the data directory, and never commit it.

Secrets

Variable	Default	Description
JWT_SECRET	required	Protects Platform sign-ins. Generated on first run. Missing ⇒ hard startup failure — there is no insecure default.
ENCRYPTION_KEY	required	64 hex characters. Derives the key protecting the configuration database and connection secrets. Generated on first run. Missing or malformed ⇒ hard startup failure.
LIVE_JWT_SECRET	derived from JWT_SECRET	Protects LiveView sign-ins. Set it explicitly if you want to reset operator sign-ins without affecting engineers.

Network

Variable	Default	Description
PORT	8182	CoreServer HTTP/WS port — the interface and API
REALTIME_PORT	8183	RealtimeGateway telemetry WebSocket
REST_GATEWAY_PORT	8090	RestGateway — pipeline-published REST ingress
SCRIPTING_GATEWAY_PORT	8091	ScriptingGateway
HOST	0.0.0.0	Bind address
ALLOWED_ORIGINS	http://localhost:3000,http://localhost:5173	Comma-separated CORS origins. Set this to your real origins in production.
TRUSTED_PROXIES	(none)	Comma-separated CIDRs or IPs. Without it, X-Forwarded-For is ignored and the peer address is used — so a spoofed header cannot rotate the login-lockout bucket.

TLS and cookies

Variable	Default	Description
TLS_ENABLED	false	Terminate TLS at QUBIQ
TLS_CERT_FILE	(none)	Certificate chain path
TLS_KEY_FILE	(none)	Private key path
QUBIQ_COOKIE_SECURE	follows TLS_ENABLED	Force the Secure cookie flag. Set it when a proxy terminates TLS but this process serves HTTP.
CSRF_ENABLED	true	CSRF protection

Cookie Secure derives from TLS so that an HTTP-only on-premise deployment is never broken by an unsendable cookie — with the explicit override for the proxy case.

Authentication

Variable	Default	Description
LOGIN_MAX_ATTEMPTS	10	Failures before lockout
LOGIN_WINDOW	15m	Window in which failures are counted
LOGIN_LOCKOUT	15m	Lockout duration

Paths and storage

Variable	Default	Description
QUBIQ_DATA_DIR	Set by the installer	The data directory. Pinned at install time so a service account with no user profile resolves it.
ENVIRONMENT	production (set by the installer)	Deployment mode.
DATABASE_PATH	in the data directory	Configuration database
QUBIQ_DB_ENCRYPTION	on	on/off. Applies to a fresh database only — there is no migration; the configuration database must be deleted to change mode.

Uploads and library folders are not environment variables. They are configured in Settings → Storage Folders and stored in the database, so there is one source of truth. Until set, storage fails closed.

Execution

Variable	Default	Description
PYTHON_PATH	The bundled runtime, set by the installer	Interpreter for the Python worker. Do not repoint this at a system Python — the bundled runtime is version-pinned against the worker.
PYTHON_WORKER_REPLICAS	(platform default)	Parallel Python workers
EXECUTION_TIMEOUT	5m	Default execution timeout
MAX_CONCURRENT_JOBS	10	Concurrent execution ceiling
QUBIQ_BROWSER_SCRIPT_SCOPES	on	off restores the earlier behaviour, where a Gateway script started from a browser button ran unclamped. On, its capabilities are derived from the caller's own realm and write level. → The sandbox 1.0.4

Connections and liveness

Variable	Default	Description
LIVENESS_MODE	passive	passive (5 min safety-net probe), hybrid (30 s), active (10 s, probe everything)

First-run bootstrap

Variable	Default	Description
QUBIQ_INIT_ENV	production	The ENVIRONMENT written into a generated .env
QUBIQ_INIT_PYTHON	The bundled runtime	The PYTHON_PATH written into a generated .env
QUBIQ_OPEN_BROWSER	(unset)	Open a browser on start

Diagnostics

Variable	Default	Description
QUBIQ_MERGE_DEBUG	(unset)	1 logs the historian's live-tail merge decisions per series query. Look for [MERGE] in the historian's output. Off by default; for tuning flush-lag only.

Sample .env

.env — a Linux production install

# --- Written by the installer; do not hand-edit ---
ENVIRONMENT=production
QUBIQ_DATA_DIR=/var/lib/qubiq
PYTHON_PATH=/opt/qubiq/python/bin/python3

# --- Generated on first boot. Back these up SEPARATELY from the data dir ---
JWT_SECRET=<64 hex chars>
ENCRYPTION_KEY=<64 hex chars>
LIVE_JWT_SECRET=<64 hex chars>

# --- Yours to set for this deployment ---
PORT=8182
REALTIME_PORT=8183
REST_GATEWAY_PORT=8090
SCRIPTING_GATEWAY_PORT=8091
ALLOWED_ORIGINS=https://qubiq.example.com
TRUSTED_PROXIES=10.0.0.0/8
QUBIQ_COOKIE_SECURE=true          # TLS terminated at a reverse proxy
LOGIN_MAX_ATTEMPTS=5
LOGIN_WINDOW=15m
LOGIN_LOCKOUT=30m

Precedence

1. Process environment
2. .env in the data directory
3. Built-in defaults

.env is generated with owner-only permissions (0600) on first boot.

Next

→ Glossary