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_UI_ORIGINS Comma-separated browser origins, beyond the console's own names and the Nuxt dev server (http://localhost:3000), that may call the API, e.g. https://ui.studio.example. A page on any other origin is refused (403) on every write and every read of the API; clients that send no Origin are not affected. Every request to the API (browser or not, with or without Origin) is refused (403 HOST_NOT_ALLOWED) unless its Host is a loopback name, an IP address, the machine's hostname or <hostname>.local, or the host of a listed origin; a hostile name that resolves to the console is refused. A request with no Host at all (an HTTP/1.0 client, never a browser) is answered. A console reached by any other DNS name (e.g. console.studio.example) must list that name here, as https://console.studio.example. A UI served from a LAN address against a console on loopback is a different origin: set this to that UI's origin, e.g. OPENMIXER_UI_ORIGINS=http://192.0.2.20:3000, or its writes get 403. The standalone patchbay (openmixer-patchbay, port 8890) reads the same variable. Same as web.uiOrigins in the config file. none
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_DATA_DIR The data home the person's own files live under, <data home>/omx/: the profiles (profiles-and-layers §6) and the preset library's house presets (omx/house/presets) and profile presets (omx/profiles/<profile>/presets). Meant for tests; leave it unset on a console. with --state-dir or OPENMIXER_STATE_DIR set, <state-dir>/data (whatever XDG_DATA_HOME says); else $XDG_DATA_HOME; else ~/.local/share
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 the documentation site built 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 by that tool's own 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_C24 1 attaches every Digidesign Control|24 the console hears, on whichever interface it announces, as soon as it appears: all 24 desk strips, a page of 24 from the console's strip order, faders both ways, MUTE/SOLO/SELECT, four-character names and meters. Needs the @freemixer/surface-native addon and diginet-packet-helper; without either the console logs why and boots as usual. Ignored when OPENMIXER_PHYSICAL_SURFACES=off. Each desk is attached only under its diginet-<mac> claim. The DEFAULT of the switch at /surface/control24, for a console that has never been switched there; once switched, the console keeps its own choice in its state and this is no longer read. The switch turns the desk on and off on a running console, with no restart (Control|24). unset (off)
OPENMIXER_C24_BANK Which bank (a page of 24 strips, the desk's width) a Control|24 opens on (0 = the first page), until the desk's bank keys are mapped. Read once at boot. 0
OPENMIXER_DIGINET_HELPER The diginet-packet-helper the Control|24 takes its packet socket from (it holds cap_net_raw; the console holds none). Read once at boot. The packaged control24.conf drop-in sets it to /usr/libexec/openmixer/diginet-helper-sg, which runs the helper in the diginet group without restarting the user manager. diginet-packet-helper in PATH
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
OPENMIXER_CONSOLE_ORIGIN Web UI server only: the console it reads the session's look from for the first paint. A value that is not a URL is ignored. http://127.0.0.1:8800

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_ASSISTANT_ORIGIN Where the Nuxt dev server forwards /api/assistant (the omx-assist serve listener; production nginx does this itself). Set in ~/.config/openmixer/dev.env. http://127.0.0.1:8890
OPENMIXER_PLUGIN_HOSTD_BIN Absolute path of the shared plugin supervisor the console spawns, its one plugin host (every LV2 runs in omx-clap-host's LV2 adapter, the console never spawns mod-host) — a run tree points it at what the native engine's plugin-hostd.sh bin tool prints. A relative path is refused at startup. plugin-hostd on PATH
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
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 the console image's Containerfile, not a server variable. It is the channel's rpm/ tree the console image installs openmixer-release from, the package that adds the repository, so the host is never baked into a committed file. It must be a plain HTTP tree of directories — the layout the project's repository publisher 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_TARGET, OPENMIXER_PRIVATE_REPO_BASEURL Repository variables of the image workflow (.github/workflows/image.yml), not server variables. OPENMIXER_TARGET is where the image takes openmixer from: private until launch (the default) or channel. OPENMIXER_PRIVATE_REPO_BASEURL is the private repository, which release.yml reads too; it defaults to the Worker. Setting them on a running console does nothing.
OPENMIXER_REPO_READ_USERNAME, OPENMIXER_REPO_READ_PASSWORD Secrets of the image and release workflows, not server variables: the read credential for the private repository. The image workflow passes them to the image build as a build secret; with target private and neither set, its preflight stops with an error naming both.
OPENMIXER_RATCHET_PRUNE, OPENMIXER_RATCHET_PRUNE_LOG Test infrastructure, read only by @freemixer/ratchet under vitest. 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. The development workflow's retire-debt step sets both. The server never reads them.
OPENMIXER_KIOSK_URL Read by the image's kiosk session script (/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