Skip to content

Environment variables

Advanced reference for process / container wiring and legacy Settings fallbacks. Most day-to-day tunables live in the Settings UI (SQLite).

Authoritative headless Settings since 0.9.0

To drive every Settings (ConfigItems) value from the environment — with read-only UI locks and values kept out of SQLite — use the NZBDAV_CONFIG__... overlay documented in Headless environment configuration. That page includes a fully hydrated Compose example.

Precedence when both are present: NZBDAV_CONFIG__... > SQLite/UI > legacy fallbacks on this page > defaults.

Container / entrypoint

Variable Default Effect
CONFIG_PATH /config SQLite, blobs, backups, session key. Must already exist as a writable directory before startup; the backend does not create a missing path.
PUID / PGID 1000 Container user/group for /config ownership
TZ unset Schedules and log timestamps
BACKEND_URL http://localhost:8080 Frontend → backend (set by entrypoint if empty)
FRONTEND_BACKEND_API_KEY random if unset Shared API key; also seeds api.key when empty
METRICS_REQUIRE_API_KEY false Require x-api-key for direct backend /metrics scrapes
MAX_BACKEND_HEALTH_RETRIES 30 Entrypoint health wait
MAX_BACKEND_HEALTH_RETRY_DELAY 1 Seconds between health probes

Frontend (Node)

Variable Default Effect
PORT 3000 HTTP listen port
BACKEND_URL required in split deploys Backend base URL
FRONTEND_BACKEND_API_KEY required Injected as x-api-key for authenticated proxy
TRUST_PROXY Settings value 1/true/yes enables and 0/false/no disables proxy-header trust, overriding Settings → General → Trust reverse-proxy headers
SECURE_COOKIES unset true for HTTPS-only UI (recommended behind TLS)
SESSION_KEY file under CONFIG_PATH Stable cookie signing secret
SESSION_MAX_AGE ~1 year (seconds) Session lifetime
DISABLE_FRONTEND_AUTH false true disables UI login (dangerous)
LOG_LEVEL info (prod) Frontend log verbosity
VITE_ALLOWED_HOSTS unset Dev/build host allowlist
NZBDAV_VERSION / NZBDAV_COMMIT_SHA image build Version display
SERVICE_PROVIDER unset Hosted-service branding and UI navigation feature gating

SERVICE_PROVIDER since 0.10.0

Hosted InfiniDysk services can identify the service provider and mark selected navigation destinations as unavailable. Disabled destinations remain visible in the sidebar; selecting one explains that the feature is disabled by the provider and links to the provider's support page (or website). The provider attribution also appears in the page footer.

Set SERVICE_PROVIDER to a JSON object on the frontend process:

environment:
  SERVICE_PROVIDER: >-
    {"name":"ElfHosted","url":"https://elfhosted.com","supportUrl":"https://docs.elfhosted.com","disabledFeatures":["watchtower","search","settings.indexers","settings.profiles","settings.watchtower","settings.warden","settings.rclone"]}

The object requires:

  • name: service provider name shown in the dialog and footer
  • url: provider website using http or https (used in the footer link)
  • disabledFeatures: navigation identifiers to make unavailable

Optional:

  • supportUrl: support page using http or https, used for the "Contact" link in the disabled-feature dialog; falls back to url when omitted

Top-level navigation identifiers are overview, queue, watchdog, watchtower, explore, health, logs, and search. overview cannot be disabled — it is the app's landing page and the fallback destination when closing the "feature not available" dialog, so it always stays reachable.

Settings navigation identifiers are settings.usenet, settings.indexers, settings.profiles, settings.queue, settings.sabnzbd, settings.streaming, settings.webdav, settings.watchdog, settings.preflight, settings.watchtower, settings.warden, settings.arrs, settings.rclone, settings.repairs, settings.maintenance, settings.backup, settings.support, and settings.migration.

This controls frontend presentation only. Providers must separately configure or restrict backend capabilities when enforcement is required.

Backend (.NET)

Variable Default Effect
ASPNETCORE_URLS from hosting Backend listen URLs
CONFIG_PATH /config Same as above
LOG_LEVEL Information Serilog minimum level
LOG_BUFFER_SIZE 2000 In-memory log buffer for UI (100–50000)
STREAM_TRACE_EVENTS 0 (off) Opt-in stream trace capacity, always-on with no expiry; the Settings → Support toggle can also set capacity (20k–200k) for timed captures
ENABLE_API_DOCS since 1.2.0 false Enables the contributor-facing Scalar reference at /scalar/ and its admin-only OpenAPI document at /openapi/admin.json; never enabled by default in Docker
TRUSTED_PROXY_CIDRS loopback Comma-separated IPs/CIDRs trusted for forwarded headers
DISABLE_WEBDAV_AUTH unset Disables WebDAV auth (dangerous)
RESET_ADMIN_PASSWORD unset true deletes the admin account on next startup, forcing re-onboarding. Remove after use.
USENET_DISABLE_CRC_VALIDATION since 0.8.0 unset 1 skips yEnc CRC checks (emergency)
THREADPOOL_MIN_THREADS max(2×CPU, 50) Override min worker/IOCP threads
THREADPOOL_MAX_THREADS max(50×CPU, 1000) Override max threads
NZBDAV_SEGMENT_BUFFER_POOL since 1.3.0 bounded-capacity Segment-buffer retention. Unset and bounded-capacity use the production 32–256 MiB idle-byte cap without expiry or a per-class ceiling. bounded-legacy restores the previous two-minute expiry and 64-buffer class ceiling as a restart-only rollback. shared uses ArrayPool<byte>.Shared as an emergency escape hatch. Unknown values log a Warning and use bounded-capacity.
DOTNET_GCHeapHardLimit runtime default .NET managed-heap ceiling; hexadecimal bytes
DOTNET_GCHeapHardLimitPercent runtime/container default .NET managed-heap ceiling as a hexadecimal percentage
DOTNET_GCRegionRange runtime default .NET regions-GC virtual reservation; hexadecimal bytes
DOTNET_GCRegionSize runtime default .NET SOH region size; hexadecimal bytes
DOTNET_GCConserveMemory 0 .NET heap-conservation level (0–9). Read only at process start; a change requires a restart. Higher values compact the LOH more aggressively and can increase collection frequency and pause duration — start as a measured canary, not a fleet default.
DOTNET_gcServer image default (1) Enables (1) or disables (0) server GC
MAX_REQUEST_BODY_SIZE 300 MiB Max request body bytes
QUEUE_ITEM_STUCK_MINUTES since 1.1.0 5 Minutes without queue progress before the stuck-item watchdog pauses and cancels the worker
NZBDAV_VERSION 0.0.0 Reported app version
DOTNET_DbgEnableMiniDump off Opt-in crash dumps — Logs

PORT and ASPNETCORE_URLS control listeners inside the container; they do not change Docker's published host port. For normal Compose deployments, leave the internal ports unchanged and use a HOST_PORT:CONTAINER_PORT mapping. See Change the published port for bridge networking, host networking, healthcheck, and DUMB examples.

DOTNET_* variables are .NET runtime settings rather than InfiniDysk configuration. Environment-variable numeric values are hexadecimal where the .NET runtime requires it. See Memory-constrained hosts before setting heap or region limits, especially on a host that enforces ulimit -v.

Settings fallbacks (when UI empty)

These apply only when the matching Settings value is empty and no NZBDAV_CONFIG__... overlay supplies that key.

Variable Related setting Default if both empty
FRONTEND_BACKEND_API_KEY API Key required
CATEGORIES Categories audio,software,tv,movies
NZB_GRAB_USER_AGENT User Agent / retrieve UA SABnzbd/5.1.0
NZB_SEARCH_USER_AGENT Search User-Agent nzbdav/{version}
TRUSTED_INTERNAL_HOSTS since 0.8.0 Trusted local hosts none
MOUNT_DIR Rclone Mount Directory /mnt/nzbdav
WEBDAV_USER WebDAV User admin
WEBDAV_PASSWORD WebDAV Password none (hashed when set)
RESOLUTION_CACHE_TTL_HOURS since 0.8.0 Search link lifetime 168
DATABASE_HISTORY_RETENTION_DAYS History retention 90
DATABASE_HEALTHCHECK_RETENTION_DAYS Health-check retention 30
DATABASE_MAINTENANCE_INTERVAL_HOURS Retention sweep cadence 6

Example Compose snippet

Operational wiring only — for a full Settings-via-ENV stack see the headless Compose example.

environment:
  PUID: "1000"
  PGID: "1000"
  TZ: America/New_York
  TRUST_PROXY: "1"
  SECURE_COOKIES: "true"
  TRUSTED_INTERNAL_HOSTS: "prowlarr"

Security

Never enable DISABLE_FRONTEND_AUTH or DISABLE_WEBDAV_AUTH on a network-exposed instance. Prefer TLS + strong WebDAV passwords + SECURE_COOKIES=true.