Repository navigation
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.
- 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.
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 |
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.
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.
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.
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_DIRand aflowsection in the file are refused asFLOW_DATA_DIR is now DATA_DIR, .... -
SESSION_STOREandSESSION_TTLare refused namingWORKSPACE_STOREandWORKSPACE_TTL, and so aresession.storeandsession.ttlin the file. - A blank variable, and a name that only starts with
SESSION_(SESSION_PORT), are not retired names.
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.
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.
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.
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.
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.
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.
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.
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).
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network