Version: Next

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

Process environment
.env in the data directory
Built-in defaults

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

→ Glossary

Secrets​

Network​

TLS and cookies​

Authentication​

Paths and storage​

Execution​

Connections and liveness​

First-run bootstrap​

Diagnostics​

Sample .env​

Precedence​

Next​