Configuration - kubed-io/selenium-flow GitHub Wiki

Configuration

Every setting can be set in a YAML config file, in the environment, or on the command line, and a later one wins: default < config < env < args. A setting's file path is its name: redis.host is REDIS_HOST and --redis-host.

The file is named by --config-file or CONFIG_FILE. There is no default location. A file with an unknown key stops the server with the reason.

server

Where it listens, and where it lives.

Config Env Flag Default What
config_file CONFIG_FILE --config-file β€” The YAML file read at start.
transport TRANSPORT --transport http http, or stdio for one local client.
host HOST --host 0.0.0.0 Address to listen on.
port PORT --port 8000 Port to listen on.
log_level LOG_LEVEL --log-level INFO DEBUG, INFO, WARNING or ERROR.
route_prefix ROUTE_PREFIX --route-prefix / Path the whole server is mounted under.
public_base_url PUBLIC_BASE_URL --public-base-url β€” Where browsers reach this server, for links.
link_ttl LINK_TTL --link-ttl 3600 Seconds a file link opens for, at least 60.

auth

The bearer token every request needs.

Config Env Flag Default What
auth.token AUTH_TOKEN --auth-token β€” Bearer token for every request. Unset is open. Sensitive.

oidc

Accept a JWT from an OIDC issuer beside the token, on /mcp and in the admin UI.

Config Env Flag Default What
oidc.issuer OIDC_ISSUER --oidc-issuer β€” The issuer a JWT must name; setting it turns OIDC on.
oidc.audience OIDC_AUDIENCE --oidc-audience β€” The audience a JWT must include.
oidc.jwks_uri OIDC_JWKS_URI --oidc-jwks-uri β€” Where the issuer publishes its signing keys.
oidc.roles OIDC_ROLES --oidc-roles β€” A JWT must hold one of these roles; empty checks none.
oidc.roles_claim OIDC_ROLES_CLAIM --oidc-roles-claim roles The claim holding the roles; dots walk into objects.
oidc.client_id OIDC_CLIENT_ID --oidc-client-id β€” The admin UI's public client; setting it offers Sign in with OIDC.
oidc.admin_roles OIDC_ADMIN_ROLES --oidc-admin-roles β€” A JWT from the admin UI holding one of these is the admin.

grid

The Selenium Grid it drives.

Config Env Flag Default What
grid.url GRID_URL --grid-url http://selenium-grid-selenium-hub.flow.svc.cluster.local:4444 The Selenium Grid hub.
grid.console_url GRID_CONSOLE_URL --grid-console-url / Where the Grid console tab is framed from.

workspace

How workspaces are kept.

Config Env Flag Default What
workspace.store WORKSPACE_STORE --workspace-store memory memory; redis.host or redis.url switches it to redis.
workspace.ttl WORKSPACE_TTL --workspace-ttl 86400 Seconds a workspace is kept after its last use.

session

How a session opens a browser.

Config Env Flag Default What
session.browser SESSION_BROWSER --session-browser β€” chrome or firefox, for new sessions.
session.width SESSION_WIDTH --session-width β€” Window width for new sessions.
session.height SESSION_HEIGHT --session-height β€” Window height for new sessions.
session.page_load_timeout SESSION_PAGE_LOAD_TIMEOUT --session-page-load-timeout β€” Seconds a page may take to load.
session.script_timeout SESSION_SCRIPT_TIMEOUT --session-script-timeout β€” Seconds a script may run.

redis

The workspace store’s connection.

Config Env Flag Default What
redis.url REDIS_URL --redis-url β€” A full Redis URL, instead of host and port. Sensitive.
redis.host REDIS_HOST --redis-host localhost Redis host.
redis.port REDIS_PORT --redis-port 6379 Redis port.
redis.db REDIS_DB --redis-db 0 Redis database number.
redis.username REDIS_USERNAME --redis-username β€” Redis username.
redis.password REDIS_PASSWORD --redis-password β€” Redis password. Sensitive.
redis.ssl REDIS_SSL --redis-ssl false Connect to Redis over TLS.
redis.prefix REDIS_PREFIX --redis-prefix selenium-flow:workspace: Prefix on every key, so a shared database is safe.

data

Where workspaces, their flows and files, and recordings live.

Config Env Flag Default What
data.dir DATA_DIR --data-dir β€” Where workspaces and recordings live. Unset turns flows, kept files and recordings off.

recording

Video of a browser's whole life, from the Grid's recorder.

Config Env Flag Default What
recording.enabled RECORDING_ENABLED --recording-enabled false The Grid's recordings reach recording.dir.
recording.dir RECORDING_DIR --recording-dir β€” Where the Grid's recordings arrive. Unset is data.dir/recordings.
recording.wait RECORDING_WAIT --recording-wait 600 Seconds after a browser ends to wait for its recording.
recording.watch RECORDING_WATCH --recording-watch auto auto, events or poll: how recording.dir is watched.
recording.poll RECORDING_POLL --recording-poll 1000 Milliseconds between looks, when polling.
recording.settle RECORDING_SETTLE --recording-settle 10 Seconds a finished recording sits unchanged before it is filed, so its transport is done with it.

capture

Console and network capture, for open_session(capture=true).

Config Env Flag Default What
capture.ttl CAPTURE_TTL --capture-ttl 10800 Seconds captured console and network entries are kept after the last one arrived.

secrets

Where secrets are read from.

Config Env Flag Default What
secrets.dirs SECRETS_DIRS --secrets-dirs β€” Directories of secrets. First match wins.

mcp

What MCP clients are offered beyond tools.

Config Env Flag Default What
mcp.skill MCP_SKILL --mcp-skill true Serve the agent skill: resources and the Skills extension.
mcp.apps MCP_APPS --mcp-apps true Offer MCP Apps views.

security

Who may frame the admin page.

Config Env Flag Default What
security.frame_ancestors SECURITY_FRAME_ANCESTORS --security-frame-ancestors β€” Origins allowed to frame the admin page, e.g. a Nextcloud or Grafana host; empty forbids framing.

One value in each place

# /etc/selenium-flow/config.yaml
workspace:
  ttl: 86400
redis:
  host: redis.data
  db: 2
export CONFIG_FILE=/etc/selenium-flow/config.yaml
export GRID_URL=http://selenium-hub:4444
selenium-flow --log-level DEBUG

The Settings tab of the admin UI shows every value and where it came from.

Worth setting

session.page_load_timeout: with no bound, one hung page holds a Grid slot until the Grid reaps it.

The environment is lenient, the file is not

An environment variable the server does not know is ignored: Kubernetes injects <SERVICE>_PORT variables into every pod. A key the file does not know stops the boot, because it is a typo.

The exception: a Kubernetes Service literally named redis injects REDIS_PORT=tcp://…, which is a known leaf and stops the boot on a value that was never meant as one. Hence enableServiceLinks: false on the pod.

Lists and booleans in env and flags

secrets.dirs splits like PATH, on the OS path separator (:). A boolean setting accepts true/false, 1/0, yes/no and on/off.

Secrets

The file's secrets.entries section defines secrets. See Secrets.

OIDC needs the token

oidc without auth.token stops the boot. oidc.roles_claim walks objects on dots: realm_access.roles reads {"realm_access": {"roles": [...]}}.

The action pages are generated from openapi.yaml, which is itself generated from the live MCP tool schemas β€” so they describe the server that shipped, not the one someone remembered. Prose belongs in wiki-notes/<tool>.md in the repo.

selenium-flow Β· MIT

⚠️ **GitHub.com Fallback** ⚠️