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
| Variable | Default | What it does |
|---|---|---|
PORT | 8080 | Port the web UI listens on in the Docker image. |
DATA_DIR | /app/data | Where Termix keeps its database, keys, plugins and uploads. Mount a volume here. Outside Docker the default is ./db/data. |
ALLOW_EMPTY_DATA_DIR | false | Start 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) | 1000 | User id the container runs as. Match it to the owner of your data volume. |
PGID (Docker only) | 1000 | Group id the container runs as. |
BASE_PATH | Serve Termix under a sub path, like /termix. Set the same path in your reverse proxy. | |
NODE_ENV | production | Set by the image. Leave it alone. |
VERSION | Set by the image to the Termix version. Leave it alone. | |
SETTINGS_CACHE_REFRESH_SECONDS | 30 | How often each server instance reloads admin settings from the database. 0 turns the refresh off. |
SSH_AUTH_SOCK | SSH agent socket used for hosts set to agent auth when they do not name their own socket. | |
SERVE_OPENAPI | false | Set 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.
| Variable | Default | What it does |
|---|---|---|
ENABLE_SSL | false | Serve HTTPS. Termix makes a self-signed certificate on first boot unless you give it one. |
SSL_PORT | 8443 | Port for HTTPS. |
TERMIX_NGINX_TEMPLATE | /app/nginx/nginx-https.conf.template | The HTTPS nginx template Termix renders when a certificate is added. Set it on an install outside Docker. |
TERMIX_NGINX_CONF | /tmp/nginx/nginx.conf | Where Termix writes the rendered nginx config before it reloads nginx. |
TERMIX_NGINX_PID | /tmp/nginx/nginx.pid | The nginx pid file. Termix only reloads nginx when it exists. |
TERMIX_APP_DIR | /app | Where Termix is installed, used in place of /app in the nginx template. |
SSL_CERT_PATH | /app/data/ssl/termix.crt | Certificate file for HTTPS. |
SSL_KEY_PATH | /app/data/ssl/termix.key | Private key file for HTTPS. |
SSL_DOMAIN | localhost | Domain put in the self-signed certificate. |
Database
See database.
| Variable | Default | What it does |
|---|---|---|
DATABASE_DIALECT | sqlite | sqlite, postgres or mysql. |
DATABASE_URL | Connection URL for postgres or mysql, like postgres://user:pass@db:5432/termix. | |
DATABASE_POOL_MAX | 10 | Most connections Termix opens to postgres or mysql. |
DATABASE_SSL | TLS for postgres or mysql: require, no-verify or disable. | |
DB_FILE_ENCRYPTION | true | Encrypt the SQLite file at rest. Set false only if something else already encrypts the disk. |
DB_FILE_KEY | Only used to open SQLite files encrypted by very old versions. You almost never need it. | |
DATABASE_LAYER_SKIP_PREUPGRADE_BACKUP | false | Skip the backup Termix takes of the data folder before an upgrade changes the database. |
DATABASE_LAYER_PREUPGRADE_BACKUP_KEEP | 3 | How 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.
| Variable | Default | What it does |
|---|---|---|
JWT_SECRET | Signs 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_KEY | Key for the encrypted SQLite file, 64 hex characters. Made for you if not set. Also read from DATABASE_KEY_FILE. | |
ENCRYPTION_KEY | Wraps 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_PREVIOUS | Old 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_PREVIOUS | Old 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_TOKEN | Token the server uses to call itself. Made for you if not set. Also read from INTERNAL_AUTH_TOKEN_FILE. | |
TERMIX_REQUIRE_EXTERNAL_SECRETS | false | Refuse to start unless the four secrets above come from env vars or _FILE files, so none are written to disk. |
OIDC_SYSTEM_SECRET | Only read to move data from installs older than 2.5. Never change it on an install that has it. | |
WEBAUTHN_SYSTEM_SECRET | Only 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.
| Variable | Default | What it does |
|---|---|---|
TERMIX_ADMIN_HOLD_MINUTES | Minutes 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_LOGIN | true or false. Overrides the admin setting for signing in with a username and password. | |
ALLOW_REGISTRATION | true or false. Overrides the admin setting for creating new accounts. | |
ALLOW_PASSWORD_RESET | true or false. Overrides the admin setting for resetting a password from the sign in page. | |
EXTERNAL_ALLOW_REGISTRATION | true or false. Overrides the admin setting for creating accounts the first time someone signs in with SSO or LDAP. | |
EXTERNAL_FORCE_HTTPS | false | Build 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_REGISTRATION | Old name for EXTERNAL_ALLOW_REGISTRATION. Still read in 26.10. | |
OIDC_FORCE_HTTPS | Old name for EXTERNAL_FORCE_HTTPS. Still read in 26.10. | |
TRUSTED_PROXY_AUTH_ENABLED | false | Let a proxy like Authelia or Authentik sign people in by sending their username in a header. |
TRUSTED_PROXY_AUTH_TRUSTED_PROXIES | Comma separated IPs or CIDRs of the proxies allowed to send the headers. Required when trusted proxy login is on. | |
TRUSTED_PROXY_AUTH_USERNAME_HEADER | x-forwarded-username | Header that holds the username. |
TRUSTED_PROXY_AUTH_ROLE_HEADER | x-forwarded-role | Header that holds the user's groups or roles. |
TRUSTED_PROXY_AUTH_ROLE_MAP | JSON 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.
| Variable | Default | What 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_ORIGINS | Comma 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_ORIGINS | Comma separated extra origins allowed to open WebSockets. | |
HTTP_PROXY | Proxy for outbound HTTP requests, like plugin registry downloads and webhooks. | |
HTTPS_PROXY | Proxy for outbound HTTPS requests. | |
NO_PROXY | Comma separated hosts that skip the proxy. | |
NODE_EXTRA_CA_CERTS | Path 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
| Variable | Default | What it does |
|---|---|---|
LOG_LEVEL | info | debug, info, warn or error. |
LOG_TIMESTAMP_FORMAT | iso or 24h. Unset uses the local time format. | |
AUDIT_LOG_RETENTION_DAYS | Delete audit entries older than this many days. Unset keeps them until the entry cap. | |
AUDIT_LOG_MAX_ENTRIES | 10000 | Most audit entries kept. The oldest go first. |
SESSION_RECORDING_RETENTION_DAYS | Only read once to carry a 2.8 value into the session-recording plugin. |
Plugins
| Variable | Default | What it does |
|---|---|---|
TERMIX_FRAME_DIR | /app/html/frame | Where 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_URL | Use another plugin index instead of the official registry. | |
TERMIX_COMMUNITY_REGISTRY_URL | Use another plugin index instead of the community registry. Its plugins still have to be signed with the community key. | |
TERMIX_PLUGIN_STATS_URL | Where plugin download counts are read from. Defaults to stats.json next to the registry index. | |
TERMIX_PLUGIN_REGISTRY_PRIVATE_HOSTS | Comma-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_PLUGINS | false | Only load plugins signed by a trusted key. Blocks uploads of unsigned files even in developer mode. |
TERMIX_SAFE_LAYOUT | false | Start everyone in the layout repair view instead of the chosen layout. Use it when a layout plugin breaks the app. |
TERMIX_SAFE_MODE | false | Start 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_MINUTES | 10 | Minutes 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_ON | Comma separated plugin ids whose process is never stopped when idle. | |
TERMIX_PLUGIN_MEMORY_MB | 256 | Heap limit in MiB for each plugin process, unless the plugin asks for its own. A plugin over it is restarted. |
TERMIX_PLUGIN_CPU_LIMIT | 80 | Percent of one CPU core a plugin process may use for a minute straight before it is restarted. |
TERMIX_BUNDLED_PLUGINS_DIR | Where the plugins shipped with Termix are read from. Set by the image. | |
TERMIX_PLUGIN_PUBLIC_RATE_LIMIT | 120 | Requests per minute one IP may make to a plugin's public routes. |
PLUGIN_MAX_KV_KEYS | 10000 | Most key value entries one plugin may store. |
Desktop app
| Variable | Default | What it does |
|---|---|---|
ENABLE_INSECURE_MODE | false | Desktop app only. Skip TLS certificate checks for the linked server. Only for testing. |
ELECTRON_DISABLE_GPU | Desktop app only. Set to 1 to turn off GPU acceleration if the window is blank or flickers. | |
TERMIX_FORCE_DEVICE_SCALE_FACTOR | Linux 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_SHELL | Desktop 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
| Variable | Default | What it does |
|---|---|---|
AUDIT_LOG_FORWARD_URL | Collector URL audit entries are posted to. The URL set in the plugin's settings wins over this. | |
AUDIT_LOG_FORWARD_TOKEN | Bearer token sent with the entries. Only used when the URL comes from this variable. |
Host Metrics
| Variable | Default | What it does |
|---|---|---|
METRICS_POLL_CONCURRENCY | How many hosts to poll at the same time, up to 50. Unset scales with the number of hosts, from 5 to 50. |
Hosts Config
| Variable | Default | What it does |
|---|---|---|
TERMIX_HOSTS_CONFIG | Path to the hosts file (.yaml, .yml or .json). Unset means the plugin loads nothing and locks no hosts. |
OPKSSH
| Variable | Default | What it does |
|---|---|---|
OPKSSH_VERSION | v0.19.2 | Use another opkssh release than the one Termix pins. Needs OPKSSH_SHA256 too. |
OPKSSH_SHA256 | SHA-256 of the opkssh binary for OPKSSH_VERSION. OPKSSH_SHA256_AMD64 and OPKSSH_SHA256_ARM64 set it per CPU. | |
OPKSSH_SHA256_AMD64 | SHA-256 of the x64 binary for OPKSSH_VERSION. | |
OPKSSH_SHA256_ARM64 | SHA-256 of the ARM64 binary for OPKSSH_VERSION. | |
OPKSSH_BUNDLED_DIR | opkssh-bundled | Folder with a copy of opkssh baked into the image, used before downloading. |
Remote Desktop
| Variable | Default | What it does |
|---|---|---|
REMOTE_DESKTOP_ENGINE | builtin | builtin 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-drive | Folder the built-in engine keeps RDP drive files in. Each user gets a folder under it. |
GUACD_HOST | localhost | Host an external guacd listens on. Only used with Use external guacd. Overrides the guacd URL setting. |
GUACD_PORT | 4822 | Port an external guacd listens on. |
GUACD_URL | An external guacd as host:port, in place of GUACD_HOST and GUACD_PORT. | |
GUACD_TUNNEL_HOST | termix | Address 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_PATH | Folder an external guacd writes recordings to, as guacd sees it. | |
GUACD_RECORDING_BACKEND_PATH | /app/data/plugin-data/remote-desktop/session_recordings/guacamole | Folder Termix keeps remote desktop recordings in. With an external guacd, the same folder as Termix sees it. |
GUACD_DRIVE_PATH | /drive | Folder an external guacd keeps RDP drive files in. Each user gets a folder under it. |
GUACAMOLE_ENCRYPTION_KEY | Key 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
| Variable | Default | What it does |
|---|---|---|
LIBC | glibc or musl. Picks the serial port binary on Linux. Found on its own when not set. |
Session Sharing
| Variable | Default | What it does |
|---|---|---|
REDIS_URL | Redis that several Termix servers share for meeting rooms, like redis://redis:6379. Not needed with one server. | |
TERMIX_REDIS_PREFIX | termix:collab | Prefix for the keys it writes in Redis. |
Single sign-on
| Variable | Default | What it does |
|---|---|---|
OIDC_CLIENT_ID | Client ID of an OIDC provider set from the environment. Needs the next four too. | |
OIDC_CLIENT_SECRET | Its client secret. | |
OIDC_ISSUER_URL | Its issuer URL. | |
OIDC_AUTHORIZATION_URL | Its authorization endpoint. | |
OIDC_TOKEN_URL | Its token endpoint. | |
OIDC_USERINFO_URL | Its userinfo endpoint, if it is not the usual one. | |
OIDC_IDENTIFIER_PATH | sub | Claim that identifies a user. |
OIDC_NAME_PATH | preferred_username | Claim used as the Termix username. |
OIDC_SCOPES | openid email profile | Scopes to ask for. |
OIDC_ALLOWED_USERS | Emails allowed to sign in, comma separated. Empty allows everyone. | |
OIDC_ADMIN_GROUP | Members of this group are admins. | |
OIDC_GROUP_CLAIM | Claim with the groups, if not groups, roles or group. | |
OIDC_ROLE_MAP | Groups to Termix roles as group:role pairs, comma separated. Works for every OIDC provider, not just this one. | |
OIDC_SIGN_OUT_AT_PROVIDER | false | true also signs people out of the provider above when they sign out of Termix. |
OIDC_END_SESSION_URL | The provider's sign out page, if it is not in its discovery document. | |
OIDC_ENV_OVERRIDE | false | true makes the provider above the only one, even when providers are set up in the app. |
OIDC_LEGACY_CALLBACK | true | false 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_DEFAULT | true or false. Sends visitors straight to SSO, and locks the setting. |
Snippets
| Variable | Default | What it does |
|---|---|---|
SNIPPET_EXECUTION_TIMEOUT_SECONDS | Stop a snippet run on hosts after this many seconds. Unset means no limit. |
SSH Terminal
| Variable | Default | What it does |
|---|---|---|
TERMIX_IMAGE_STORAGE_MODE | Where pasted terminal images go: auto, local or remote. Only used until an admin saves the setting. | |
TERMIX_IMAGE_DIR | DATA_DIR/termix-image-v0 | Folder on the Termix server for local image storage. |
TERMIX_IMAGE_HOST_PATH | /tmp/termix-image-v0 | The same folder as the host sees it, for agents that read images. |
TERMIX_IMAGE_TTL_MS | 3600000 | How long an image is kept, in milliseconds. |
TERMIX_MAX_IMAGE_COUNT | 100 | Most images kept at once. |
TERMIX_MAX_IMAGE_STORAGE_BYTES | 5368709120 | Most bytes of images kept at once. |
Usage Statistics
| Variable | Default | What it does |
|---|---|---|
ENABLE_TELEMETRY | true or false. Turns usage statistics on or off and locks the setting. | |
POSTHOG_API_KEY | Send reports to your own PostHog project instead of the Termix one. | |
POSTHOG_HOST | https://us.i.posthog.com | PostHog server to send to. |