Configuration

TrixOS reads its configuration from the environment. With Docker Compose that is the .env file in the installation directory. After changing .env, apply it with docker compose up -d.

This page is generated from the code of the current release, so it lists every setting with its real default. DATABASE_URL, REDIS_URL, API_HOST, API_PORT, TRUST_PROXY, VIEWER_URL and METRICS_PORT are set per container by docker-compose.yml; POSTGRES_PASSWORD and WEB_PORT (default 8088) are read from .env by Compose itself.

TrixOS core

Setting	Default	Description
`NODE_ENV`	`development`	`production` for every real installation.
`TRIXOS_PUBLIC_URL`	`http://localhost:5173`	The address users open. Used for links TrixOS generates, such as console URLs.
`API_HOST`	`127.0.0.1`	Address the API listens on.
`API_PORT`	`8080`	Port the API listens on.
`TRUST_PROXY`	`loopback`	Proxies whose `X-Forwarded-For` is trusted: `loopback`, `true` or a comma-separated list of addresses, CIDRs and host names (`web` = the nginx container in Docker Compose; names are resolved every 30 s, only the direct peer counts).
`DATABASE_URL`	`postgres://trixos:trixos@localhost:5432/trixos`	Postgres connection URL.
`REDIS_URL`	`redis://localhost:6379`	Redis connection URL.
`QUEUE_PREFIX`	`trixos`	BullMQ/lock key prefix (lets several test runs share one Redis).
`MIGRATE_ON_START`	`true`	Apply database migrations and refresh the built-in OS catalogue when the API starts.
`LOG_LEVEL`	`info`	`fatal`, `error`, `warn`, `info`, `debug` or `trace`.
`TRIXOS_API_DOCS`	`admin`	The panel’s own Swagger UI and spec at `/api/docs`: `admin` (signed-in admins only), `public` or `off`. The public reference is api.trixos.sh.
`TRIXOS_MASTER_KEY`	empty	Encrypts BMC, switch and webhook credentials, TOTP secrets and job secrets (AES-256-GCM). 32 random bytes, base64: `openssl rand -base64 32`. Back it up: without it the stored credentials are lost.
`TRIXOS_SESSION_SECRET`	empty	Signs session cookies. Generate with `openssl rand -hex 32`.

Safety

Setting	Default	Description
`TRIXOS_ALLOW_DESTRUCTIVE`	`false`	While `false`, every call that would change hardware is only logged (dry-run). See Safety switches.

Console viewer

KVM / BMC web UI in a throw-away browser container.

Setting	Default	Description
`VIEWER_SECRET`	empty	Shared secret between the API and the viewer launcher service (openssl rand -hex 32). Build the viewer image once: docker compose –profile tools build kvm-viewer The viewer has no Docker socket: the docker-proxy service holds it and lets through only viewer containers.

TenantOS compatibility

Setting	Default	Description
`COMPAT_CONSOLE_BASE_URL`	empty	Base for console accessUrl returned by /api/servers/:id/console/start (defaults to TRIXOS_PUBLIC_URL)

PXE service

Disabled by default; never run alongside another DHCP server on the same relay.

Setting	Default	Description
`PXE_ENABLED`	`false`	DHCP and TFTP on the panel itself, only for a panel inside the servers’ network. Sites with an agent don’t need it. See Safety switches.
`PXE_HTTP_BASE`	`http://localhost:8080`	URL the servers reach during provisioning (iPXE scripts, installer files, boot file cache)
`PXE_INTERFACE`	empty	Interface the panel’s own DHCP/TFTP listens on. Empty: all.
`PXE_STATE_DIR`	`/var/lib/trixos/pxe`	Boot-file cache and per-job PXE state.
`PXE_TFTP_ROOT`	`/var/lib/trixos/tftp`	TFTP root for the panel’s own PXE service.
`PXE_DNSMASQ_BIN`	`dnsmasq`	Path of the dnsmasq binary.
`PXE_DHCP_MODE`	`authoritative`	Authoritative (default) or proxy (only add PXE options next to an existing DHCP server)
`PXE_BIOS_FILE`	`undionly.kkpxe`	iPXE image for legacy BIOS clients.
`PXE_EFI_FILE`	`ipxe.efi`	iPXE image for UEFI clients.
`PXE_PREFETCH_ASSETS`	`false`	Download the boot files of all enabled OS profiles at start instead of on first use.

Poller

Setting	Default	Description
`POLLER_BANDWIDTH_INTERVAL_S`	`300`	Seconds between switch counter reads.
`POLLER_SENSORS_INTERVAL_S`	`300`	Seconds between BMC sensor reads.
`POLLER_POWER_INTERVAL_S`	`60`	Power state + BMC reachability of every server (`trixos power refresh` does the same on demand).
`POLLER_PDU_INTERVAL_S`	`300`	PDU readings (totals, outlet states and power) over SNMP.

Watchdog (0.7.5): stops jobs that run far too long, reports slow polls

0.7.5.

Setting	Default	Description
`TRIXOS_WATCHDOG`	`true`	False = never stop anything (the dashboard still shows the actions it took before)
`TRIXOS_WATCHDOG_LIMITS`	empty	Limit overrides in minutes (1 min – 24 h), JSON; the setting “watchdog” (PUT /api/v1/settings) wins TRIXOS_WATCHDOG_LIMITS={“jobs”:{“reinstall”:240},“steps”:{“wait:installer-started”:90},“tasks”:{“power”:5}}
`METRICS_PORT`	`0`	Worker/poller/pxe /healthz + /metrics on 127.0.0.1:<port> (0 = off)

rDNS

PowerDNS authoritative HTTP API.

Setting	Default	Description
`PDNS_API_URL`	empty	PowerDNS HTTP API for reverse DNS. Empty: PTR records are stored but not pushed.
`PDNS_API_KEY`	empty	PowerDNS API key.
`PDNS_SERVER_ID`	`localhost`	PowerDNS server ID.

Notifications

Setting	Default	Description
`SMTP_URL`	empty	SMTP server for e-mail notifications, for example `smtp://user:[email protected]:587`. Empty: no e-mail.
`NOTIFY_FROM`	`[email protected]`	Sender address of notification e-mails.

TenantOS importer

READ-ONLY token, GET requests only.

Setting	Default	Description
`TENANTOS_URL`	empty	TenantOS address for the one-time importer.
`TENANTOS_API_TOKEN`	empty	Read-only TenantOS API token for the importer (GET requests only).

Advanced

Settings that most installations leave at their default.

Setting	Default	Description
`CORS_ORIGINS`	empty	Comma-separated browser origins allowed to call the API. Empty: same origin only.
`TRIXOS_LICENSE_URL`	`https://license.trixos.sh`	License server. Leases are verified with the public key compiled into TrixOS, so pointing this elsewhere cannot unlock anything.
`TRIXOS_LICENSE_KEY`	empty	Pro / Enterprise key to activate automatically on start (instead of Settings → License).
`TRIXOS_RELEASES_URL`	`https://trixos.sh/releases`	Where releases are published (latest.json, packages, signatures). Releases are verified with the signing key compiled into TrixOS, so pointing this elsewhere cannot install anything unsigned.
`TRIXOS_UPDATE_DIR`	`/var/lib/trixos/update`	Folder shared with the host updater (request/ writable by TrixOS, state/ read-only); see docs/RELEASES.md.
`TRIXOS_ALLOW_PRIVATE_URLS`	`false`	Let webhooks, custom ISO downloads and PXE boot-file downloads reach internal addresses (RFC 1918, loopback, metadata). Off by default: checked when connecting, so DNS rebinding gets nowhere.
`VIEWER_URL`	empty	Address of the console launcher service.
`VIEWER_IMAGE`	`trixos/kvm-viewer:latest`	Image of the throw-away console viewer containers.
`VIEWER_NETWORK`	`trixos_default`	Docker network the viewer containers join.
`VIEWER_LISTEN_PORT`	`8091`	Port of the console launcher service.
`CUSTOM_ISO_DIR`	`/var/lib/trixos/isos`	Custom ISOs (downloaded by URL or copied onto the host), booted via iPXE sanboot.
`CUSTOM_ISO_MAX_GB`	`16`	Largest custom ISO accepted, in GB.
`PXE_STRICT_SOURCE_IP`	`true`	Only hand the per-job iPXE script to the IP the server got via DHCP (prevents token theft by MAC spoofing on other IPs).
`TRIXOS_HEALTH_DISK_PATH`	`/`	Filesystem whose usage the dashboard shows for the control server (inside the container “/” is the disk behind Docker’s storage).