Configuration reference¶

Every parameter below exists in the code (or, where marked, in the compose/installer layer only). Grouped by category; "Edition" marks EE-only parameters. Unless noted, changing a value requires recreating the containers (docker compose up -d) for it to reach the backend.

Application¶

Parameter	Required	Default	Description	Edition
`APP_ENV`	recommended	`dev`	`dev`/`development`/`test`/`production`. In production: `ENCRYPTION_KEY` becomes mandatory, `COOKIE_SECURE` defaults on, rate-limiter active	both
`UPLOAD_ROOT`	no	`/data/uploads`	Root for uploads, loot files, audit JSONL, generated keys	both
`WORKER_BACKEND`	no	`internal`	`internal` (in-process pool) or `arq` (Redis-queued worker)	both
`WORKER_POOL_MAX_WORKERS`	no	`8`	Total job slots	both
`WORKER_POOL_MAX_PER_PROJECT`	no	`3`	Job slots per project	both
`MODULES_DIR`	no	`/app/modules`	Module plugins directory (compose mounts `./modules` read-only)	both
`SECURE_DELETE`	no	`false`	`shred -uzn 3` (fallback: single zero pass) before deleting files	both
`ENABLE_API_DOCS`	no	`false`	Expose `/docs`, `/redoc`, `/openapi.json` (off by default — they mount outside the authed `/api` prefix)	both
`LOG_LEVEL` / `LOG_FORMAT`	no	`INFO` / `text`	Backend logging level; `json` option	both

Database¶

Parameter	Required	Default	Description	Edition
`DATABASE_URL`	yes	`sqlite://` (dev)	SQLAlchemy URL; compose builds it from `DB_*`	both
`DB_USER` / `DB_PASSWORD` / `DB_NAME`	compose: yes	`umbryx` / — / `umbryx`	DSN parts + PostgreSQL service credentials	both
`DB_HOST` / `DB_PORT`	no	`db` / `5432`	Point at a VIP for external/HA clusters	both
`DB_SSLMODE`	no	`prefer`	e.g. `require` for HA clusters	both
`DATABASE_REPLICA_URL`	no	—	Read-replica engine for read-heavy lists	both
`DATABASE_POOL_SIZE` / `_MAX_OVERFLOW` / `_POOL_RECYCLE`	no	`10` / `20` / `1800`	Connection pool tuning	both
`DATABASE_STATEMENT_TIMEOUT`	no	`30000`	PostgreSQL `statement_timeout`, ms (`0` disables)	both
`POSTGRES_PASSWORD`	prod-compose: yes	—	Used by the `db` service in prod/demo compose variants	both
`PGBOUNCER_POOL_SIZE` / `PGBOUNCER_MAX_CLIENT_CONN`	no	`25` / `200`	Optional PgBouncer sidecar (service commented out)	both

Authentication and sessions¶

Parameter	Required	Default	Description	Edition
`JWT_SECRET`	yes	auto-generated, persisted to `/data/.jwt_secret`	HS256 signing key; known-weak values are rejected	both
`JWT_EXPIRE_HOURS`	no	`8`	Access-token lifetime	both
`JWT_REFRESH_EXPIRE_HOURS`	no	`24`	Refresh-token lifetime (rotating)	both
`SETUP_TOKEN`	recommended	—	Gates first-run `/api/auth/setup`	both
`ADMIN_USERNAME` / `ADMIN_PASSWORD`	first start	`admin` / generated	Bootstrap admin (only when the users table is empty)	both
`COOKIE_SECURE`	no	auto (`true` in production)	`Secure` flag on the session cookie	both
`CORS_ORIGINS`	no	empty (same-origin)	Comma-separated origins; never wildcard	both
`REDIS_URL`	compose: yes	`redis://localhost:6379/0`	Enables JWT blacklist, login lockout, WS presence, leader election	both
`REDIS_PASSWORD`	no	empty	Password for the Redis instance, applied when `REDIS_URL` carries no inline credentials (`redis_factory.py`)	both
`JWT_BLACKLIST_FAIL_CLOSED`	no	`true`	Reject tokens when Redis is unavailable	both

Cryptography¶

Parameter	Required	Default	Description	Edition
`ENCRYPTION_KEY`	yes in production	dev: auto-generated `/data/secret.key`	Fernet key (KEK) for credential/secret encryption; invalid or missing in production is a startup error	both
`PLUGIN_SIGNING_KEY`	for signing	—	Enables module signing (`POST /api/admin/modules/sign`)	both
`PLUGIN_REQUIRE_SIGNATURE`	no	`true`	Reject unsigned module uploads	both
`SYNC_SIGNING_KEY`	for sync	— (sync disabled)	HMAC over instance-to-instance sync events; must match across instances	both
`AUDIT_INTEGRITY_KEY`	no	—	HMAC fingerprints on timeline events (`GET /api/admin/audit/verify`)	both
`OLD_KEY` / `NEW_KEY`	rekey only	—	Consumed by `backend/scripts/rekey.py` for key rotation	both

Integrations and infrastructure¶

Parameter	Required	Default	Description	Edition
`WEBHOOK_HMAC_SECRET`	for webhooks	— (webhooks disabled)	Fail-closed HMAC for `/api/webhooks/{token}`	both
`PUBLIC_BASE_URL`	recommended	derived from request host	Canonical external URL (OIDC `redirect_uri`, workstation callbacks)	both
`PLATFORM_HOST`	no	empty	Fallback callback base for workstation action hooks (`http://<host>:8888`), probed when `PUBLIC_BASE_URL` is unset (`core/workstation/actions.py`)	both
`OUTBOUND_PROXY`	no	— (or DB setting)	HTTP(S) proxy for outbound egress	both
`REGISTRY_URL` / `REGISTRY_EXTERNAL_URL` / `REGISTRY_USER` / `REGISTRY_PASS`	no	`http://registry:5000` / — / `""`	Internal Docker registry for infra images	both
`KUBECONFIG_PATH` / `KUBECTL_TIMEOUT`	no	— / `60`	kubectl access for k8s deploy methods	both
`EVIDENCE_BACKEND` + `S3_*` / `EVIDENCE_LOCAL_DIR`	for S3	`local` / `/data/evidence`	Evidence storage backend (S3/Minio)	both
`DNS_SERVER_1` / `DNS_SERVER_2`	no	`8.8.8.8` / `1.1.1.1`	DNS for the backend container (compose-level)	both
`DOCKER_HOST` / `DOCKER_SOCKET`	no	`unix:///var/run/docker.sock`	Docker API access for instance management	both

Audit logging¶

Parameter	Required	Default	Description	Edition
`AUDIT_LOG_DIR`	no	`UPLOAD_ROOT/audit`	Append-only JSONL mirror of timeline events	both
`AUDIT_S3_BUCKET` / `AUDIT_S3_PREFIX` / `AUDIT_S3_ENDPOINT_URL` + `AWS_*`	for S3	— / `timeline/`	WORM forward of audit events	both

High availability (application side; recipe ships with EE)¶

Parameter	Default	Description
`REDIS_SENTINEL_HOSTS`	—	Enables Sentinel (takes precedence over `REDIS_URL`)
`REDIS_SENTINEL_MASTER`	`mymaster` (recipe: `umbryx-master`)	Monitored master name
`REDIS_SENTINEL_PASSWORD`	—	Sentinel auth
`HA_MONITOR_HOST/PORT/DB/USER/PASSWORD`	— / `5433` / `pg_auto_failover`	Read-only pg_auto_failover monitor for the HA status page

All five are read by both editions' application code; the packaged HA cluster recipe (docker-compose.ha.yml, installer modes) is EE.

EE-only¶

Parameter	Required	Default	Description
`INFRA_TLS_VERIFY`	no	`true`	TLS verification for infra provisioning calls (lab self-signed opt-out; the C2 agent-login always verifies)
`INFRA_SSH_KNOWN_HOSTS`	no	`/data/infra_known_hosts`	TOFU known-hosts file for infra SSH
`UMBRYX_VERIFY_DEPLOY`	no	`1`	Post-deploy health verification on/off
`Umbryx_STATE_DIR`	no	`/data/infra_states`	Cloud provisioning state directory (note the non-standard capitalization — a known quirk of the source)
`LICENSE_SERVER_URL`	no	`https://update.umbryx.pro`	License heartbeat endpoint (read in both editions' code; only EE has a token to renew)

Ports and build-time (compose layer only)¶

Parameter	Default	Description
`PORT`	`3000`	Published HTTP port
`HTTPS_PORT`	`3443`	Optional TLS termination variant (commented out; use your reverse proxy)
`DATA_DIR`	`./data`	Host path mounted at `/data`
`BACKEND_IMAGE` / `FRONTEND_IMAGE` / `IMAGE_TAG`	`umbryx-backend` / `umbryx-frontend` / `latest`	Deploy prebuilt images (EE licensed registry)
`UMBRYX_EDITION`	auto (by tree)	Build-time frontend edition (`ce` forces Core)

Secrets in all examples must be placeholders — never commit real values. Rotate anything shipped in .env.example before production use.