Skip to content
Dr K edited this page Nov 14, 2026 · 3 revisions

Config

Every setting the server reads has one name and three places to set it: a YAML file, the environment and the command line. This area is the rules of that machinery: where a value comes from and in what order, how the file is found, how a value is checked and what a bad one does at start, how a credential is referenced and kept out of sight, and what must change together when a key is added. What an individual key means is in the area that uses it, and the key-by-key table is generated into the wiki's Configuration page from the code.

Use cases

  • An operator runs the server from environment variables alone, as a container does, or keeps the stable settings in a mounted file and overrides one with a variable or a flag.
  • An operator mistypes a key and the server refuses to start, saying which key and where.
  • An operator declares a secret in the file, with its allowed sites and where its values live.
  • A contributor adds a setting and knows which files change with it.

Neighbours

CFG-1. Which area owns which key:

Keys Area
auth.*, oidc.* auth-and-roles.md
workspace.*, redis.*, grid.url, session.keep_alive workspaces-and-sessions.md
session.* session-settings.md
secrets.* secrets-and-scope.md
capture.* capture.md
live.* live-view-and-control.md
data.dir, recording.*, public_base_url, link_ttl workspace-files.md
security.frame_ancestors, grid.console_url, the Settings tab's drawing admin-ui.md
mcp.apps surfaces.md
mcp.skill plugin.md
transport, host, port, log_level, route_prefix, config_file this file

One setting, three spellings

CFG-2. A setting is a field of a section model in config.py. Its path is its name: redis.host for a field of the redis section, port for a field with no section.

CFG-3. The other two spellings are derived from the path. The environment name is the path with . turned into _, in capitals (REDIS_HOST). The flag is -- and the path with . and _ turned into - (--redis-host). No spelling is declared by hand, and environment names match case-insensitively.

CFG-4. A section name has no underscore, because the first _ of an environment name splits the section from the key. A section is never named browser or selenium: BROWSER is the shell's, and SELENIUM_FLOW_PORT and its kind sit too close.

CFG-5. secrets.entries is the one field with no environment name and no flag. It is structure, and only the config file can set it.

CFG-6. A list given in the environment or on the command line is one string. It is split on , for oidc.roles, oidc.admin_roles and security.frame_ancestors, and on the platform's path separator (:) for secrets.dirs. Each part is trimmed and a blank part is dropped. In the file the same fields are YAML lists, and a string there is split the same way.

CFG-7. session.capabilities is a JSON object. In the environment and on the command line it is a JSON string, and a string that is not a JSON object is refused as must be a JSON object.

Where a value comes from

CFG-8. There are four layers, lowest first: the field's default, the config file, the environment, the command line. For each setting the highest layer that set it supplies the value. config.load is the one function that reads the file, the environment and the arguments.

CFG-9. The layers merge one section deep. A section's keys come from each layer separately, so a redis.host in the file survives a redis.db in the environment.

CFG-10. In every layer an empty or whitespace-only string means not set. REDIS_URL="", which a compose file sends for an unset variable, is the default, and so is --auth-token "" and a quoted blank in the file. A blank AUTH_TOKEN means no auth, never an empty credential.

CFG-11. Each setting records the layer it came from: default, config, env or args. The server keeps them, keyed by path, for the Settings tab.

CFG-12. workspace.store is derived when no layer sets it. It is redis when redis.url or redis.host was set by any layer above the default, and memory otherwise. Its recorded source is the highest of the two that was set. Naming memory explicitly wins over a Redis setting.

CFG-13. A flag is generated for every setting but secrets.entries. The parser keeps only what was typed, so args is a true answer about where a value came from. Abbreviated flags are refused: --redis-h does not mean --redis-host. A flag the parser does not know exits with argparse's own message and code 2.

CFG-14. The process environment is read in two modules only: config.py at load, and secrets.py when a secret key names an environment variable. Everything else receives a Settings.

CFG-15. Settings() reads nothing and is every default, whatever the environment holds. A Settings built in code reports each value that differs from its default as coming from args.

Finding the file

CFG-16. The file is named by --config-file, else by CONFIG_FILE. The flag wins. There is no default location and no search: with neither, there is no file layer. The name is trimmed.

CFG-17. The file is read once, with yaml.safe_load, as UTF-8. An empty file is no settings. It has no templating and no interpolation of ${...}.

CFG-18. A named file that does not exist is refused as config file <path> does not exist. A directory is config file <path> is not a file. A file that cannot be read is config file <path> cannot be read: <exception type>.

CFG-19. A file that is not valid YAML is refused as config file <path> is not valid YAML, with at line L, column C when the parser gave a place. The parser's own message is never used, because it quotes the offending line, which may be an inline secret.

CFG-20. A file whose top level is not a mapping is refused as config file <path> must be a mapping of sections, not a <type>. A config_file key inside the file is refused, since the file cannot name itself.

Strict file, lenient environment

CFG-21. Every model refuses a key it does not define, at every level of the file. A typo in the file stops the start.

CFG-22. The environment drops a name that is not a setting. Kubernetes puts a <SERVICE>_PORT variable in every pod, and FLOW_UI_PORT would read as flow.ui_port; the variable is ignored, not refused. A bare section name (REDIS, SESSION) is dropped too.

CFG-23. An environment variable that is a setting is used as that setting. A Service named redis injects REDIS_PORT=tcp://..., a real setting with a bad value, and stops the start.

CFG-24. A retired name is refused, never dropped, where dropping would start a server quietly missing a feature.

  • FLOW_DATA_DIR and a flow section in the file are refused as FLOW_DATA_DIR is now DATA_DIR, ....
  • SESSION_STORE and SESSION_TTL are refused naming WORKSPACE_STORE and WORKSPACE_TTL, and so are session.store and session.ttl in the file.
  • A blank variable, and a name that only starts with SESSION_ (SESSION_PORT), are not retired names.

Validation and what a failure says

CFG-25. The file is validated on its own, then the merged result is validated. The first pass exists because a later layer that supplies a section would otherwise overwrite a malformed one in the file, and the file would be accepted.

CFG-26. A validation failure is one ConfigError whose message lists every problem, separated by ; . A problem reads <path>: <message> (<where>).

Where Printed as
the config file in <file path>
the environment from env <NAME>
the command line from <flag>
a default as a default

CFG-27. A message never carries the rejected input. A value may be a credential, a URL with userinfo or a secret's inline value, so a message names the key and the rule and nothing of what was written. A rejected allowed_urls line is shown as its rebuilt origin.

CFG-28. A field's own bounds and choices are checked with the type: an integer field refuses a non-number, a field with ge or le refuses a value outside it, and a Literal field refuses a value outside its list. log_level is case-folded first, and session.browser is normalised (Firefox is firefox) and refused when unknown.

CFG-29. Two rules read more than one setting, so they run on the merged result and not in a field: OIDC's (AUTH-45 to AUTH-47) and recording's (recording.enabled needs data.dir, and recording.dir must not overlap <data.dir>/workspaces). OIDC's is not a model validator because the file is validated alone (CFG-25) and a deployment may set oidc in the file and the token in the environment. The retired names (CFG-24) are checked earlier, on the raw environment and the raw file.

CFG-30. A Settings built in code skips load, so the server repeats the recording rule and the auth doors repeat the OIDC rule, both as the same ConfigError.

CFG-31. session.capabilities is checked at load for keys the server owns, and a key it owns is refused naming session.capabilities. The keys are in session-settings.md.

What a bad configuration does at start

CFG-32. main catches a ConfigError from load and from building the server, and exits with SystemExit("selenium-flow: <message>"), which is exit code 1 with the message on stderr. Nothing listens. Logging is not configured when load fails.

CFG-33. Checks that need the machine, and not only the settings, raise ConfigError while the server is built: a recording.dir that is not a readable and writable directory, a data directory that cannot be read, a data directory holding a folder in the old layout, and an OIDC rule broken in code.

CFG-34. Redis named and unreachable raises StoreUnavailable, which is a RuntimeError and not a ConfigError. main does not catch it, so the process ends with a traceback, and the message carries the host without the password or the URL's userinfo.

CFG-35. After a good load main sets the root log level from log_level (DEBUG to CRITICAL) and logs one config= line: the file or none, the Grid URL without userinfo, and which parts are on. It carries no token and no secret.

CFG-36. main warns at start when oidc.roles is empty while OIDC is on, and when no token is set on an HTTP server whose host is not localhost, 127.0.0.1 or ::1.

Keys with no other area

CFG-37. transport is http or stdio, defaulting to http. host and port, defaulting to 0.0.0.0 and 8000, are where http listens, and stdio ignores them.

CFG-38. route_prefix mounts every route, /mcp and /admin included, under one path. / and the empty string both mean no prefix, and slashes at either end are trimmed.

Credentials

CFG-39. An ordinary setting takes a plain value in any layer. No setting but a secret's key takes a reference to a file or a variable, and the file does not substitute variables into a value.

CFG-40. auth.token, redis.url and redis.password are the sensitive settings. Each is held as a secret string, so none appears in a repr or a JSON dump of the settings.

CFG-41. See SEC-7: a secret's key in secrets.entries is exactly one of {file: <path>}, {env: <NAME>} and {value: <text>}, and a reference with two, with none, or with another key is refused.

CFG-42. A file or env reference is resolved when a value is bound, never when the file is loaded. Loading checks the shape alone. A value is held as a secret string from the moment it is parsed.

CFG-43. An entry's names and allowed_urls follow SEC-2, SEC-7 and SEC-11, and a line with a path, query, fragment or credentials stops the start. The message shows the rebuilt origin and none of the credentials (CFG-27).

CFG-44. The file declares a secret's name, its description, its allowed sites and where each key's value lives (SEC-5, SEC-6). It holds no value except through value.

Schema and the wiki

CFG-45. The schema is the section models in config.py. No JSON Schema document of the config file is generated or published.

CFG-46. Every setting has a one-sentence description of at most 100 characters ending in a full stop. Every section has a description and a place in SECTION_ORDER, which is server and then the sections in the order Settings declares them.

CFG-47. The wiki's Configuration page is generated by scripts/generate_wiki.py from leaves(). It has one table per section with the columns Config, Env, Flag, Default and What, marks a sensitive setting, and omits secrets.entries. The hand-written prose in docs/notes/Configuration.notes.md follows the tables. tests/test_wiki.py fails when the committed page differs from what the generator prints.

The Settings tab and its payload

CFG-48. GET /admin/settings answers config.describe(settings, sources) behind the admin door. It has no tool and no resource.

CFG-49. The payload is {"sections": [...]} in SECTION_ORDER. A section has name, description and settings. A setting has key (its path), name (the path without its section), description, value and source.

CFG-50. A sensitive setting has value: null, sensitive: true and set, true only when it holds a non-empty value. No other fact about it is published.

CFG-51. grid.url, grid.console_url, public_base_url, oidc.issuer and oidc.jwks_uri are shown with any userinfo removed. Their path is kept: the default grid.console_url of / is shown as /, and grid.url defaults to http://localhost:4444 (GRID-3).

CFG-52. The payload has no secrets.entries and no env name, flag or default. The config source carries no path; the path is the value of the config_file row.

Change without a restart

CFG-53. Settings are read once. Nothing watches the file, no signal reloads it, and the Settings tab shows what the process started with. Any change to a setting needs a restart.

CFG-54. Three things are read from disk or the environment after start and so follow a change there, without a restart. The directories of secrets.dirs are re-read, the listing cache lasting 30 seconds (SEC-8). A secret key given by file or env is read when it is bound. The file live.password_file names is read at every connect (LIVE-6). The settings that name them are not reloaded.

Adding a key

CFG-55. A new setting is a field on a section model in config.py, with a default and a one-sentence description (CFG-46). Its environment name, flag, help text, wiki row and Settings row need nothing more.

CFG-56. A list or mapping that arrives as a string needs NoDecode and a mode="before" validator, or pydantic-settings reads a list from the environment as JSON and SECRETS_DIRS=/a:/b fails.

CFG-57. A credential is declared as SecretStr. tests/test_config_schema.py names the sensitive set, which is the three of CFG-40 today, so the test changes with it.

CFG-58. A new section is a Section subclass and a field on Settings with a description and default_factory. Its name has no underscore and does not collide (CFG-4).

CFG-59. A URL setting shown on the Settings tab that may carry userinfo is added to URL_LEAVES.

CFG-60. A rule over two or more settings is a function called by load and by the object that depends on it (CFG-30), not a field validator. The consumer takes its section of Settings from server.py and never reads the environment (CFG-14).

CFG-61. The wiki page is regenerated with python scripts/generate_wiki.py, and the new key's meaning goes into its own area file in this directory. A key that replaces another is renamed outright, with no alias; where dropping the old name would hide a misconfiguration, the old name is added to the retired names (CFG-24).

Clone this wiki locally