Skip to main content

Environment variables

Set these on the Termix server. In Docker Compose they go under environment:. You never need most of them. Termix works with none set.

This page is made from env.catalog.json in the Termix repo and from each plugin's manifest, so it matches the code.

Most switches here also exist as a setting in the app. When both are set, the environment variable wins.

Core​

Server​

VariableDefaultWhat it does
PORT8080Port the web UI listens on in the Docker image.
DATA_DIR/app/dataWhere Termix keeps its database, keys, plugins and uploads. Mount a volume here. Outside Docker the default is ./db/data.
ALLOW_EMPTY_DATA_DIRfalseStart even when DATA_DIR is empty but an older data folder exists elsewhere. Only set this if you really want a fresh install.
PUID (Docker only)1000User id the container runs as. Match it to the owner of your data volume.
PGID (Docker only)1000Group id the container runs as.
BASE_PATHServe Termix under a sub path, like /termix. Set the same path in your reverse proxy.
NODE_ENVproductionSet by the image. Leave it alone.
VERSIONSet by the image to the Termix version. Leave it alone.
SETTINGS_CACHE_REFRESH_SECONDS30How often each server instance reloads admin settings from the database. 0 turns the refresh off.
SSH_AUTH_SOCKSSH agent socket used for hosts set to agent auth when they do not name their own socket.
SERVE_OPENAPIfalseSet to true to serve this server's API spec, core and every plugin that is on, at /version/openapi.json to signed in users and API keys.

HTTPS​

See HTTPS.

VariableDefaultWhat it does
ENABLE_SSLfalseServe HTTPS. Termix makes a self-signed certificate on first boot unless you give it one.
SSL_PORT8443Port for HTTPS.
TERMIX_NGINX_TEMPLATE/app/nginx/nginx-https.conf.templateThe HTTPS nginx template Termix renders when a certificate is added. Set it on an install outside Docker.
TERMIX_NGINX_CONF/tmp/nginx/nginx.confWhere Termix writes the rendered nginx config before it reloads nginx.
TERMIX_NGINX_PID/tmp/nginx/nginx.pidThe nginx pid file. Termix only reloads nginx when it exists.
TERMIX_APP_DIR/appWhere Termix is installed, used in place of /app in the nginx template.
SSL_CERT_PATH/app/data/ssl/termix.crtCertificate file for HTTPS.
SSL_KEY_PATH/app/data/ssl/termix.keyPrivate key file for HTTPS.
SSL_DOMAINlocalhostDomain put in the self-signed certificate.

Database​

See database.

VariableDefaultWhat it does
DATABASE_DIALECTsqlitesqlite, postgres or mysql.
DATABASE_URLConnection URL for postgres or mysql, like postgres://user:pass@db:5432/termix.
DATABASE_POOL_MAX10Most connections Termix opens to postgres or mysql.
DATABASE_SSLTLS for postgres or mysql: require, no-verify or disable.
DB_FILE_ENCRYPTIONtrueEncrypt the SQLite file at rest. Set false only if something else already encrypts the disk.
DB_FILE_KEYOnly used to open SQLite files encrypted by very old versions. You almost never need it.
DATABASE_LAYER_SKIP_PREUPGRADE_BACKUPfalseSkip the backup Termix takes of the data folder before an upgrade changes the database.
DATABASE_LAYER_PREUPGRADE_BACKUP_KEEP3How many of those upgrade backups to keep.

Secrets​

Termix makes these on first boot and saves them in DATA_DIR/.env. Set them yourself only if you keep secrets somewhere else. Each one can also be read from a file: add _FILE to the name, like JWT_SECRET_FILE=/run/secrets/jwt. See security.

VariableDefaultWhat it does
JWT_SECRETSigns sign-in sessions. At least 64 characters. Made for you and saved in DATA_DIR/.env if not set. Also read from JWT_SECRET_FILE.
DATABASE_KEYKey for the encrypted SQLite file, 64 hex characters. Made for you if not set. Also read from DATABASE_KEY_FILE.
ENCRYPTION_KEYWraps the data keys that encrypt passwords and SSH keys, 64 hex characters. Made for you if not set. Also read from ENCRYPTION_KEY_FILE.
ENCRYPTION_KEY_PREVIOUSOld ENCRYPTION_KEY values after a rotation, comma separated. Data sealed with them still opens, and the server moves it to the new key at start. Remove once the log says nothing uses it. Also read from ENCRYPTION_KEY_PREVIOUS_FILE.
DATABASE_KEY_PREVIOUSOld DATABASE_KEY values after a rotation, comma separated. The SQLite file still opens with them and is saved with the new key at start. Also read from DATABASE_KEY_PREVIOUS_FILE.
INTERNAL_AUTH_TOKENToken the server uses to call itself. Made for you if not set. Also read from INTERNAL_AUTH_TOKEN_FILE.
TERMIX_REQUIRE_EXTERNAL_SECRETSfalseRefuse to start unless the four secrets above come from env vars or _FILE files, so none are written to disk.
OIDC_SYSTEM_SECRETOnly read to move data from installs older than 2.5. Never change it on an install that has it.
WEBAUTHN_SYSTEM_SECRETOnly read to move data from installs older than 2.5. Never change it on an install that has it.

Sign in​

See trusted proxy login for the TRUSTED_PROXY_AUTH_ ones.

VariableDefaultWhat it does
TERMIX_ADMIN_HOLD_MINUTESMinutes a dangerous admin change (a new admin, password login off, a plugin with dangerous access) waits when the server has two or more admins, so the others can cancel it. 0 turns it off. Overrides the admin setting, which admins then can't change.
ALLOW_PASSWORD_LOGINtrue or false. Overrides the admin setting for signing in with a username and password.
ALLOW_REGISTRATIONtrue or false. Overrides the admin setting for creating new accounts.
ALLOW_PASSWORD_RESETtrue or false. Overrides the admin setting for resetting a password from the sign in page.
EXTERNAL_ALLOW_REGISTRATIONtrue or false. Overrides the admin setting for creating accounts the first time someone signs in with SSO or LDAP.
EXTERNAL_FORCE_HTTPSfalseBuild sign in callback URLs with https even when the request came in over http. Use it behind a proxy that does not send X-Forwarded-Proto.
OIDC_ALLOW_REGISTRATIONOld name for EXTERNAL_ALLOW_REGISTRATION. Still read in 26.10.
OIDC_FORCE_HTTPSOld name for EXTERNAL_FORCE_HTTPS. Still read in 26.10.
TRUSTED_PROXY_AUTH_ENABLEDfalseLet a proxy like Authelia or Authentik sign people in by sending their username in a header.
TRUSTED_PROXY_AUTH_TRUSTED_PROXIESComma separated IPs or CIDRs of the proxies allowed to send the headers. Required when trusted proxy login is on.
TRUSTED_PROXY_AUTH_USERNAME_HEADERx-forwarded-usernameHeader that holds the username.
TRUSTED_PROXY_AUTH_ROLE_HEADERx-forwarded-roleHeader that holds the user's groups or roles.
TRUSTED_PROXY_AUTH_ROLE_MAPJSON map from proxy roles to Termix roles, like {"admins":["admin"],"staff":["user"]}. Required when trusted proxy login is on.

Proxies and origins​

See reverse proxy.

VariableDefaultWhat it does
TRUSTED_PROXIES (Docker only)Comma separated IPs or CIDRs nginx takes the client IP from (X-Forwarded-For). Set it to your reverse proxy.
CORS_ALLOWED_ORIGINSComma separated extra origins allowed to use the login cookie from a browser, also for WebSockets. Other origins can still call the API with a Bearer token or API key. The desktop app is always allowed; on a server older than 26.11.2 add app://termix for desktop apps 26.11.2 and newer.
TERMIX_ALLOWED_ORIGINSComma separated extra origins allowed to open WebSockets.
HTTP_PROXYProxy for outbound HTTP requests, like plugin registry downloads and webhooks.
HTTPS_PROXYProxy for outbound HTTPS requests.
NO_PROXYComma separated hosts that skip the proxy.
NODE_EXTRA_CA_CERTSPath to a PEM file with extra root certificates to trust, like a private CA. Used for outbound connections and by plugins, also in the desktop app.

Logs and audit​

VariableDefaultWhat it does
LOG_LEVELinfodebug, info, warn or error.
LOG_TIMESTAMP_FORMATiso or 24h. Unset uses the local time format.
AUDIT_LOG_RETENTION_DAYSDelete audit entries older than this many days. Unset keeps them until the entry cap.
AUDIT_LOG_MAX_ENTRIES10000Most audit entries kept. The oldest go first.
SESSION_RECORDING_RETENTION_DAYSOnly read once to carry a 2.8 value into the session-recording plugin.

Plugins​

VariableDefaultWhat it does
TERMIX_FRAME_DIR/app/html/frameWhere the built page for sandboxed plugin views is. Set it on an install outside Docker when the UI build sits somewhere else.
TERMIX_PLUGIN_REGISTRY_URLUse another plugin index instead of the official registry.
TERMIX_COMMUNITY_REGISTRY_URLUse another plugin index instead of the community registry. Its plugins still have to be signed with the community key.
TERMIX_PLUGIN_STATS_URLWhere plugin download counts are read from. Defaults to stats.json next to the registry index.
TERMIX_PLUGIN_REGISTRY_PRIVATE_HOSTSComma-separated host names or IP addresses that plugin registry downloads may reach on a private address, like a registry in your LAN. List bare hosts: entries with a scheme, port or path are ignored. Matched by name only, on any port, so only list names your own DNS answers for. With HTTPS_PROXY set, add them to NO_PROXY too.
TERMIX_REQUIRE_SIGNED_PLUGINSfalseOnly load plugins signed by a trusted key. Blocks uploads of unsigned files even in developer mode.
TERMIX_SAFE_LAYOUTfalseStart everyone in the layout repair view instead of the chosen layout. Use it when a layout plugin breaks the app.
TERMIX_SAFE_MODEfalseStart only layout and theme plugins. Every other plugin stays off until a restart without it, so you can turn off a plugin that breaks the server or the app.
TERMIX_PLUGIN_IDLE_MINUTES10Minutes a plugin that starts on first use may sit idle before its process is stopped. It starts again on the next request.
TERMIX_PLUGIN_ALWAYS_ONComma separated plugin ids whose process is never stopped when idle.
TERMIX_PLUGIN_MEMORY_MB256Heap limit in MiB for each plugin process, unless the plugin asks for its own. A plugin over it is restarted.
TERMIX_PLUGIN_CPU_LIMIT80Percent of one CPU core a plugin process may use for a minute straight before it is restarted.
TERMIX_BUNDLED_PLUGINS_DIRWhere the plugins shipped with Termix are read from. Set by the image.
TERMIX_PLUGIN_PUBLIC_RATE_LIMIT120Requests per minute one IP may make to a plugin's public routes.
PLUGIN_MAX_KV_KEYS10000Most key value entries one plugin may store.

Desktop app​

VariableDefaultWhat it does
ENABLE_INSECURE_MODEfalseDesktop app only. Skip TLS certificate checks for the linked server. Only for testing.
ELECTRON_DISABLE_GPUDesktop app only. Set to 1 to turn off GPU acceleration if the window is blank or flickers.
TERMIX_FORCE_DEVICE_SCALE_FACTORLinux desktop app only. Forces the window scale, like 1 or 2. Set it if the app looks too small or clicks land in the wrong place.
TERMIX_LOCAL_SHELLDesktop app only. Shell the local terminal opens, like /bin/zsh or pwsh.exe.

Plugins​

Plugins only read these while they are installed and on.

Audit Tools

VariableDefaultWhat it does
AUDIT_LOG_FORWARD_URLCollector URL audit entries are posted to. The URL set in the plugin's settings wins over this.
AUDIT_LOG_FORWARD_TOKENBearer token sent with the entries. Only used when the URL comes from this variable.

Host Metrics

VariableDefaultWhat it does
METRICS_POLL_CONCURRENCYHow many hosts to poll at the same time, up to 50. Unset scales with the number of hosts, from 5 to 50.

Hosts Config

VariableDefaultWhat it does
TERMIX_HOSTS_CONFIGPath to the hosts file (.yaml, .yml or .json). Unset means the plugin loads nothing and locks no hosts.

OPKSSH

VariableDefaultWhat it does
OPKSSH_VERSIONv0.19.2Use another opkssh release than the one Termix pins. Needs OPKSSH_SHA256 too.
OPKSSH_SHA256SHA-256 of the opkssh binary for OPKSSH_VERSION. OPKSSH_SHA256_AMD64 and OPKSSH_SHA256_ARM64 set it per CPU.
OPKSSH_SHA256_AMD64SHA-256 of the x64 binary for OPKSSH_VERSION.
OPKSSH_SHA256_ARM64SHA-256 of the ARM64 binary for OPKSSH_VERSION.
OPKSSH_BUNDLED_DIRopkssh-bundledFolder with a copy of opkssh baked into the image, used before downloading.

Remote Desktop

VariableDefaultWhat it does
REMOTE_DESKTOP_ENGINEbuiltinbuiltin runs RDP, VNC and Telnet inside Termix. guacd sends them to an external guacd instead. Overrides the Use external guacd setting.
RDP_DRIVE_PATH/app/data/plugin-data/remote-desktop/rdp-driveFolder the built-in engine keeps RDP drive files in. Each user gets a folder under it.
GUACD_HOSTlocalhostHost an external guacd listens on. Only used with Use external guacd. Overrides the guacd URL setting.
GUACD_PORT4822Port an external guacd listens on.
GUACD_URLAn external guacd as host:port, in place of GUACD_HOST and GUACD_PORT.
GUACD_TUNNEL_HOSTtermixAddress an external guacd uses to reach Termix for hosts behind jump hosts and VNC without a username. In Compose, the Termix container name. In Kubernetes it defaults to the pod IP.
GUACD_RECORDING_PATHFolder an external guacd writes recordings to, as guacd sees it.
GUACD_RECORDING_BACKEND_PATH/app/data/plugin-data/remote-desktop/session_recordings/guacamoleFolder Termix keeps remote desktop recordings in. With an external guacd, the same folder as Termix sees it.
GUACD_DRIVE_PATH/driveFolder an external guacd keeps RDP drive files in. Each user gets a folder under it.
GUACAMOLE_ENCRYPTION_KEYKey that encrypts connection tokens, 64 hex characters. Made for you on each start if not set. Set it when you run more than one Termix server.

Serial

VariableDefaultWhat it does
LIBCglibc or musl. Picks the serial port binary on Linux. Found on its own when not set.

Session Sharing

VariableDefaultWhat it does
REDIS_URLRedis that several Termix servers share for meeting rooms, like redis://redis:6379. Not needed with one server.
TERMIX_REDIS_PREFIXtermix:collabPrefix for the keys it writes in Redis.

Single sign-on

VariableDefaultWhat it does
OIDC_CLIENT_IDClient ID of an OIDC provider set from the environment. Needs the next four too.
OIDC_CLIENT_SECRETIts client secret.
OIDC_ISSUER_URLIts issuer URL.
OIDC_AUTHORIZATION_URLIts authorization endpoint.
OIDC_TOKEN_URLIts token endpoint.
OIDC_USERINFO_URLIts userinfo endpoint, if it is not the usual one.
OIDC_IDENTIFIER_PATHsubClaim that identifies a user.
OIDC_NAME_PATHpreferred_usernameClaim used as the Termix username.
OIDC_SCOPESopenid email profileScopes to ask for.
OIDC_ALLOWED_USERSEmails allowed to sign in, comma separated. Empty allows everyone.
OIDC_ADMIN_GROUPMembers of this group are admins.
OIDC_GROUP_CLAIMClaim with the groups, if not groups, roles or group.
OIDC_ROLE_MAPGroups to Termix roles as group:role pairs, comma separated. Works for every OIDC provider, not just this one.
OIDC_SIGN_OUT_AT_PROVIDERfalsetrue also signs people out of the provider above when they sign out of Termix.
OIDC_END_SESSION_URLThe provider's sign out page, if it is not in its discovery document.
OIDC_ENV_OVERRIDEfalsetrue makes the provider above the only one, even when providers are set up in the app.
OIDC_LEGACY_CALLBACKtruefalse makes the provider above send the new redirect URI, /plugin-api/sso/callback, instead of the 2.8 one, /users/oidc/callback.
OIDC_SILENT_LOGIN_DEFAULTtrue or false. Sends visitors straight to SSO, and locks the setting.

Snippets

VariableDefaultWhat it does
SNIPPET_EXECUTION_TIMEOUT_SECONDSStop a snippet run on hosts after this many seconds. Unset means no limit.

SSH Terminal

VariableDefaultWhat it does
TERMIX_IMAGE_STORAGE_MODEWhere pasted terminal images go: auto, local or remote. Only used until an admin saves the setting.
TERMIX_IMAGE_DIRDATA_DIR/termix-image-v0Folder on the Termix server for local image storage.
TERMIX_IMAGE_HOST_PATH/tmp/termix-image-v0The same folder as the host sees it, for agents that read images.
TERMIX_IMAGE_TTL_MS3600000How long an image is kept, in milliseconds.
TERMIX_MAX_IMAGE_COUNT100Most images kept at once.
TERMIX_MAX_IMAGE_STORAGE_BYTES5368709120Most bytes of images kept at once.

Usage Statistics

VariableDefaultWhat it does
ENABLE_TELEMETRYtrue or false. Turns usage statistics on or off and locks the setting.
POSTHOG_API_KEYSend reports to your own PostHog project instead of the Termix one.
POSTHOG_HOSThttps://us.i.posthog.comPostHog server to send to.