openmixerGitHub →

Environment variables

Every environment variable the openmixer server reads. Anything not listed here is either a build-time parameter (see configuration files) or belongs to the transport (see the transport's own knobs).

An unset variable always means "use the default". The empty string counts as unset for OPENMIXER_CONSOLE, OPENMIXER_GIG, OPENMIXER_CATALOG and the network knobs — but not for all of them: OPENMIXER_ADAPTER= and OPENMIXER_DEVICE_HOST= are parsed, fail their schema (ServerConfigSchema's adapter and device.host fields) and the server exits at boot with a validation error. Unset the variable rather than blanking it.

Where environment variables sit in the precedence chain

For the network fields:

persisted Setup value  >  CLI flag  >  environment variable  >  config file  >  built-in default

For everything else the environment is the override and the config file (or the built-in default) is the base — the same order, so the whole chain reads one way.

Startup and configuration

Variable Effect Default
OPENMIXER_CONFIG Path to the JSON server-config file. The --config flag outranks it. /etc/openmixer/config.json via the unit
OPENMIXER_ADAPTER Console family: software, midas, x32, roland, mock. An unknown name is an error. mock (the packaged config selects a rig instead)
OPENMIXER_RIG Retired. Named the startup rig while there were two; bare, demo and console still parse and are ignored (the console is the only rig), with a line at startup saying so. —
OPENMIXER_CONSOLE Pin the console size as IN:OUT, e.g. 32:16. A malformed value is logged and ignored. detected
OPENMIXER_GIG A label for the session. unset
OPENMIXER_CATALOG Explicit plugin-catalog JSON path. the catalog package's bundled data file
OPENMIXER_STATE_DIR Persisted-state directory. The --state-dir flag outranks it. $XDG_STATE_HOME/openmixer, else ~/.local/state/openmixer
OPENMIXER_ADAPTERS_CONFIG Path to the adapter definitions. <state-dir>/adapters.yaml
OPENMIXER_PERF 0 disables the engine's own performance sampling (the seam timings behind /perf and the process gauge at /telemetry/process). Any other value, or unset, leaves it on. enabled

Network

Variable Effect Default
OPENMIXER_WEB_HOST HTTP bind address. localhost (both loopbacks, nothing else — a LAN device goes through nginx)
OPENMIXER_WEB_PORT HTTP port. 8080
OPENMIXER_MANUAL_DIR Override only — leave it unset. The console works out where its documentation site is: /usr/share/openmixer/manual (the openmixer-manual package), else packages/website/.output/public in a workspace checkout. It serves whichever it finds at /help, so the surface's help deep-links (/help/manual/user#<anchor>) resolve offline, on the desk. No site in either → /help answers 404 and the console says so in its log rather than faking a page. Set it only for an unusual layout; the RPM may set it, an operator should not have to. Whatever is set must be the build root, never a directory inside it — a prerendered page's stylesheet, chunks and fonts sit beside the pages, and the manual's topic pages are under docs/, so a subtree serves HTML whose every asset 404s. The console warns at boot when the value is not a site built for this mount. derived
OPENMIXER_DEVICE_HOST Address of a physical desk, when an adapter drives one. Ignored: the console hardcodes the software adapter and overwrites device (console-rig.ts), as it does OPENMIXER_ADAPTER. There is no longer a rig that honours them. 127.0.0.1
OPENMIXER_DEVICE_PORT Its port. per-adapter: Midas 10002, X32 10023
OPENMIXER_PATCHBAY_HOST Bind address of the standalone openmixer-patchbay tool (read directly in its bin/patchbay.ts entry point). Loopback by default — not reachable from a tablet. 127.0.0.1
OPENMIXER_PATCHBAY_PORT Its port (see ports). 8890
OPENMIXER_PHYSICAL_SURFACES off keeps this console's hands off every physical control surface (the X-Touch family): it never probes or opens one, and its surface entries report why. Read once at boot. Every launcher of a console that is NOT the live one — a deploy shadow, a preview, a test console — sets it off, because the ALSA sequencer is shared by the whole machine and a second console opening the surface stalls the live one (surface map §9). The live unit leaves it unset. unset (surfaces open)
OPENMIXER_CONSOLE_DROP_IN Override only — leave it unset. The systemd unit drop-in /console/allocation GENERATES when a reshape is accepted, carrying the size the next boot builds at (console-allocation-boot.ts). It sorts after a hand-written zz-console-*.conf, so where both exist the generated one wins; a file this console did not generate is left alone and reported, never overwritten. Set by a test to a scratch path; production never sets it, and under a test runner with no value set the console generates NOTHING rather than writing into a real deployment's unit directory. $XDG_CONFIG_HOME/systemd/user/openmixer-engine.service.d/zz-console-size.conf
OPENMIXER_TLS_CERT_DIR Override only — leave it unset. Where /console/addresses (console-addresses-row.ts) reads console.crt from, the same directory issue-local-ca.sh issues into. Set by a test to a scratch directory; production never sets it. /etc/openmixer/tls

Remember that a value persisted through Setup → Network outranks both of the network variables. If setting one appears to do nothing, that is why — check <state-dir>/network-settings.json.

Engine behaviour

Variable Effect Default
OPENMIXER_MOD_HOST_BIN Absolute path of the mod-host binary the console spawns — a local build while mod-host itself is under development (ruling 36: published releases by default; set in ~/.config/openmixer/dev.env). A relative path is refused at startup. /usr/bin/mod-host (the installed release)
OPENMIXER_DEMO_SOURCES 1 spawns the real, patchable demo source nodes instead of modelling them virtually. off
OPENMIXER_REAC_FORCE 1 tells the discovery probe to assume it has raw-socket capability rather than testing for it. Useful only when the capability was granted in a way the probe cannot see. off
OPENMIXER_RELAY_SETTLE_MS Overrides the CAP on the post-pace-write re-lay, in milliseconds. The re-lay normally fires as soon as the graph goes quiet; this only bounds how long it waits when no port churn arrives. For measuring what that bound should be. 2000

Not for production

Variable What it is
REACPW_DIR Locates a reac-pw source checkout for the RPM build (packaging/publish-repo.sh's REACPW_DIR default). It does not steer the running prober — that takes an injected reacpwBin option and otherwise resolves reac-pw on PATH (reacPwProber in packages/server/src/reac-pw-prober.ts). Setting it will not make the mixer probe a dev binary.
OPENMIXER_CATALOG_JSON, OPENMIXER_VERSION Build-time inputs read by the RPM build script, not by the server.
OPENMIXER_REPO_BASEURL A build ARG of packaging/image/Containerfile, not a server variable. It is the dnf repository the console image installs from, substituted into the .repo file at image-build time so the host is never baked into a committed file. It must be a plain HTTP tree of directories — the layout packaging/publish-repo.sh emits — and never a container registry, which serves OCI manifests and cannot answer a dnf baseurl. Setting it on a running console does nothing.
OPENMIXER_RATCHET_PRUNE, OPENMIXER_RATCHET_PRUNE_LOG Test infrastructure, read only by @freemixer/ratchet under vitest (packages/ratchet/src/prune.ts). OPENMIXER_RATCHET_PRUNE=1 makes a ratchet's shrink-only arms rewrite its debt list, removing the keys that no longer deviate; =dry reports them and fails as usual; OPENMIXER_RATCHET_PRUNE_LOG names a file that gets one JSON line per key. harness/lane-finish.sh step retire-debt sets both. The server never reads them.
OPENMIXER_KIOSK_URL Read by the image's kiosk session script (packaging/image/usr/share/openmixer/kiosk/gnome-kiosk-script.openmixer.sh), not by the server: the URL the desk variant's Chromium opens at login. A surface-only kiosk points it at another machine's console.

The REAC transport's variables

~/.config/reac-pw/ supplies the transport's configuration — interface, role, desk model, desk profile. It is written by the mixer's Setup screen and documented on its own page: REAC configuration.

The transport's knobs

reac-pw has a small number of behaviour knobs of its own, all default-off and byte-identical on the wire when unset. They are documented in the transport's repository at docs/ENV-KNOBS.md and listed in reac-pw --help:

  • REACPW_GRANT_DWELL_S — hold the recognised-but-ungranted dwell for a whole number of seconds, for boxes that want a longer wait than the built-in one.
  • REAC_DEBUG — set to any value for diagnostic counters on stderr roughly every two seconds: received, duplicate, other-source, bad and gap counts, plus ring statistics. The duplicate counter is what tells you whether you are on a mirrored port — on a correctly-cabled interface it stays at zero.

Set them in the unit with a drop-in:

systemctl --user edit reac-pw

[Service]
Environment=REAC_DEBUG=1