Reference

Configuration

Workbench reads its configuration from environment variables (all prefixed WORKBENCH_), an optional YAML file, and command-line flags. Environment variables are the primary surface for the container deployments this manual covers, so the variables below are what you set in practice — the image defaults are safe for a standard deployment, so override only what your environment requires. SSO and dispatch tuning are summarised at the end.

Precedence

When the same setting is given more than one way, Workbench resolves it flag > environment > YAML > built-in default: a command-line flag wins over an environment variable, which wins over a value in the YAML config file, which wins over the image default. The variables below name the environment form; each has an equivalent flag and YAML key. The container image carries the defaults; the master key is the one value with no default — Workbench refuses to boot without it.

Core

Variable	Default	Purpose
WORKBENCH_MASTER_KEY	(required)	Root at-rest encryption key (or `WORKBENCH_MASTER_KEY_FILE` for a mounted file). HKDF-derives the key that unwraps the workspace seed, which protects every stored database password and integration credential. Read from the environment only. Back it up outside the data volume — an intact volume with the wrong or missing key is unrecoverable.
WORKBENCH_HTTP_ADDR	0.0.0.0:8080	TCP listen address (`host:port`) — the single customer-facing port.
WORKBENCH_SQLITE_PATH	/var/lib/arq-workbench/workbench.sqlite	On-disk SQLite store. Must live on a persistent volume.
WORKBENCH_LICENSE_ARTEFACT	/var/lib/arq-workbench/license.json	Where the activated license JSON is persisted — same volume as the store.
WORKBENCH_IDENTITY_DIR	/var/lib/arq	Persistent `instance_id` + `install_secret`. Must exist and be writable at startup (v1 does not auto-create it). Empty disables offline activation.
WORKBENCH_ACTIVATION_ARTEFACT	/var/lib/arq/activation.json	Signed activation file that binds your license to this install. Imported via the activation API.

Licensing

Variable	Default	Purpose
WORKBENCH_REFRESHER_INTERVAL	5m	How often Workbench re-reads the license artefact and refreshes its entitlement cache. Minimum `30s`.
WORKBENCH_CACHE_CADENCE	5m	Freshness window for the entitlement cache.

Operations

Variable	Default	Purpose
WORKBENCH_LOG_LEVEL	info	One of `debug` / `info` / `warn` / `error`.
WORKBENCH_SHUTDOWN_DEADLINE	10s	Max drain time for in-flight requests on `SIGTERM` before force-exit.
WORKBENCH_TRUST_FORWARDED_FOR	false	Take the client IP from the right-most `X-Forwarded-For` entry. Enable only behind a trusted reverse proxy — otherwise a client can spoof its source IP.
WORKBENCH_AUDIT_RETENTION_DAYS	90	Days audit-event rows are kept. `0` retains forever.

SSO and tuning

Single sign-on adds WORKBENCH_OIDC_* (OIDC) and WORKBENCH_SAML_* (SAML 2.0) groups — each gated behind a *_ENABLED master switch, with HTTPS enforced on redirect URIs at startup. Ticket dispatch is tuned with WORKBENCH_DISPATCH_WORKERS (default 4), WORKBENCH_DISPATCH_QUEUE_CAP, and WORKBENCH_DISPATCH_MAX_ATTEMPTS. Set these only when your IdP or throughput requires it.

A minimal Compose environment block needs only the master key — every other value above already has a working default:

environment:
  WORKBENCH_MASTER_KEY_FILE: /run/secrets/workbench_master_key
  WORKBENCH_LOG_LEVEL: "info"

See also: the getting-started tutorial for these in context.