Configuration
Broker settings
Every environment variable the broker itself reads, with its default and what it controls.
Everything here is set with an environment variable, and the broker reads
them once, when it starts up. You don't need to set any of these in the
stock image except BROKER_SECRET, plus SUBFOLDER if you've mounted the
container somewhere other than /streaming/.
| Env var | Default | Purpose |
|---|---|---|
SUBFOLDER | /streaming/ | The URL path the whole app lives under. This one value feeds the container's nginx (the web server in front of the broker) setup, the FastAPI app (the broker itself) mount point, and the vite (the tool that builds the room UI) base path. |
BROKER_SECRET | unset | A shared password for the session lifecycle endpoints (the URLs RomM uses to run a session, start to finish), sent as the X-Broker-Secret header. Leave it unset outside dev mode and the broker refuses to start; leave it unset in dev mode and it starts anyway with those endpoints unauthenticated, so dev mode should never be exposed beyond local development. |
BROKER_HOST | 127.0.0.1 | The network interface uvicorn (the server process that runs the broker) listens on. Only nginx is meant to talk to it directly. |
BROKER_PORT | 8000 | The port uvicorn listens on. The image's nginx setup already expects 8000. |
ROM_ROOT | /romm | The folder your ROMs live in. Activate (the call that launches a game) refuses any ROM path outside this folder. The default already covers the recommended /romm/library mount, so you only need this if the library is mounted outside /romm. |
BROKER_EXPORT_DIR | /config/broker-exports | Where exit writes save archives to disk. In dev mode it always writes here; otherwise only if uploading the save fails. |
BROKER_IMPORT_DIR | /config/broker-imports | Where uploaded save archives land, ready for activate to load them via save.archive. |
BROKER_FRONTEND_DIST | /usr/share/webstation-broker/www | Where the built room UI is served from outside dev mode. |
BROKER_PID_FILE | /config/broker-emulator.json | Where the running emulator's process ID is recorded, so if the broker restarts it can still find and stop that emulator. |
BROKER_SAVE_UPLOAD_PATH | /api/webstation/saves | The path added to the callback URL when exit uploads the save archive. |
BROKER_SAVE_UPLOAD_TIMEOUT | 30 | How many seconds exit is allowed to spend uploading the save. |
BROKER_EMULATOR_WATCH_INTERVAL | 15 | How many seconds apart the broker checks that the open session's emulator is still running. It logs one line per session when the emulator exits while the session is open (see The game froze mid-session). 0 turns the check off. |
BROKER_STATE_FILE_MAX_BYTES | 268435456 | The largest a single state file (a save-state snapshot) is allowed to be on the state-file routes, 256 MiB. RomM enforces the same limit on its side, so raising just this one only shifts which side rejects the file first. |
BROKER_STATE_SCREENSHOT_SIZE | 640 | The longest side, in pixels, of the thumbnail saved with a state. The broker captures the whole streamed desktop, then shrinks it to this size before saving it as the thumbnail. |
SAVE_FILE_MAX_BYTES | 268435456 | The largest a save or memory-card archive is allowed to be, 256 MiB, checked on import, on exit, and on the memory-card routes. Unlike the other settings on this page, this one has no BROKER_ prefix. |
BROKER_SAVE_FILE_MAX_ENTRIES | 10000 | The most files a save or memory-card archive may contain. This is separate from SAVE_FILE_MAX_BYTES: a size limit alone wouldn't stop an archive packed with huge numbers of tiny, deeply nested files from using up disk inodes (the fixed number of file-record slots a filesystem has, separate from its storage space) or stalling the restore. |
BROKER_GAMEPAD_SLOTS | 4 | How many virtual gamepad slots the room can hand out. |
BROKER_MAX_ROOM_VIEWERS | 32 | The most viewers who can be in the room at once. Once that limit is hit, a disconnected anonymous viewer's seat can be given to a new arrival; a signed-in user's seat never gets reassigned this way. |
BROKER_FRAME_ANCESTORS | unset | Which sites may show the room inside a frame, as a Content-Security-Policy frame-ancestors list (the browser rule that stops other sites from embedding a page). Use 'self' when RomM serves the room under its own SUBFOLDER, or RomM's origin, such as https://romm.example.com, when it embeds the room from a different address. Unset, any site can frame the room. A wrong value leaves the player blank, so check it in a browser after setting it. |
BROKER_CSP_ENFORCE | unset | Set to true to enforce the room page's Content-Security-Policy (the browser rule listing where the page may load scripts, styles and connections from). Unset, the policy is only reported: nothing is blocked, and anything it would block shows up in the browser console as a [Report Only] message. Turn it on once your deployment runs with no such messages. |
ROM_CACHE_* | off | An opt-in local copy of recently played games, for a library on a slow network mount. Its eight settings have their own page. |
BROKER_DEV_MODE | unset | Set to true to run from your mounted source code, with uvicorn and vite hot reload (changes show up without a rebuild), and to skip the exit save upload (it just reports what it would have done instead). See Dev mode. |
Variables the image sets for the broker
You don't set these yourself. The container's own startup scripts set them, and they're listed here just so you can make sense of them if you spot them in the logs.
| Env var | Set by | Purpose |
|---|---|---|
SELKIES_CONTROL_URL | init-romm-config | The base URL of the selkies (the video/input streaming layer) control plane, http://127.0.0.1:<CUSTOM_WS_PORT><SUBFOLDER>stream. The broker sends its token maps to <url>/api/tokens, falling back to <url>/tokens. If this is unset, it tries 127.0.0.1:8082 and 8083 directly instead. |
SELKIES_MASTER_TOKEN | init-romm-config | The bearer token (an access key sent with each request) for those token pushes. Generated fresh each boot if none is supplied. |
XDG_RUNTIME_DIR | base image | Where PCSX2's PINE socket (the file PCSX2 uses to accept remote commands) is expected, pcsx2.sock, under the default /config/.XDG. |
Paths the launchers share
Inside the container, HOME is /config, and XDG_CONFIG_HOME and
XDG_DATA_HOME (standard folders an app looks in for its settings and data)
are used wherever a given emulator honours them. The per-emulator defaults on
the next page all follow from that, so you
shouldn't need to set any of them unless you've changed the image's folder
layout.