Configuration reference

Settings come from defaults, then config.toml in the data directory, then RELAYBAY_* environment variables, then command-line flags (a later source wins). An invalid value stops relaybay serve with a message that names the key.

Settings

Key (config.toml)	Default	Environment	Flag	Meaning
—	per-user data dir (platformdirs)	RELAYBAY_HOME	--home	Data directory: relaybay.sqlite, token, config.toml.
host	127.0.0.1	RELAYBAY_HOST	--host	Bind address. Anything but loopback prints a warning.
port	8765	RELAYBAY_PORT	--port	Port.
allowed_hosts	[]	RELAYBAY_ALLOWED_HOSTS	—	Extra names accepted in the Host header (LAN names); the environment variable is comma-separated.
[stages.labels]	the stage keys	—	—	Display names per stage (plan, dev, review, test, live, done).
[reports.labels]	built-in	—	—	Display names of report states and sizes.
[reports.hints]	built-in	—	—	Tooltips of report badges.
desktop_link_template	claude://claude.ai/epitaxy/{id}	RELAYBAY_DESKTOP_LINK_TEMPLATE	—	Link for a desktop session id; must contain {id}.
done_window_days	7	RELAYBAY_DONE_WINDOW_DAYS	—	Days a done task stays in the done column (whole number >= 1).
require_tracker_log	false	RELAYBAY_REQUIRE_TRACKER_LOG	—	Done tasks without the tracker mark show "not logged" and are never archived.
owner_names	["owner", "me", "you"]	RELAYBAY_OWNER_NAMES	—	Names that mean you in a task's waiting_on (case-insensitive): those tasks are listed in the Inbox. The environment variable is comma-separated.
[rules]	built-in rules	—	—	Global working rules merged over the defaults (SPEC §6).
rules_mode	warn	RELAYBAY_RULES_MODE	—	warn or strict: what a stage move that misses a rule does.
[permission_defaults]	local = "full", test = "full", live = "read"	—	—	Legacy: agents' level per environment kind (none, read, ask, full); a layer under policy.json (policy reference).
guard_mode	warn	RELAYBAY_GUARD_MODE	—	Legacy: off, log, warn or block, the guard mode; a layer under policy.json (policy reference).
policy_file	policy.json in the data directory	RELAYBAY_POLICY_FILE	—	The global policy layer (JSON, policy reference); a relative path is read from the data directory. A missing file means the default preset.
attachment_roots	[]	RELAYBAY_ATTACHMENT_ROOTS	—	Extra folders attach_file may read screenshots from, besides the project's repo_path and the temp folder (for example a screenshots folder). The environment variable is comma-separated.
attachments_max_mb	10	RELAYBAY_ATTACHMENTS_MAX_MB	—	Largest screenshot in MB (whole number >= 1).
attachments_task_max_mb	200	RELAYBAY_ATTACHMENTS_TASK_MAX_MB	—	Screenshots of one task in all, in MB (whole number >= 1).
plan_reminder_every	30	RELAYBAY_PLAN_REMINDER_EVERY	—	Remind a linked agent of its current plan step every this many tool calls (PostToolUse events); 0 turns the periodic reminder off (session start and todo changes still remind).
claude_home	your home directory	RELAYBAY_CLAUDE_HOME	--claude-home	Folder with Claude Code's .claude/ and .claude.json (setup, doctor, Integrations).

Example config.toml

port = 8765
allowed_hosts = ["my-laptop.lan"]   # needed only when you bind to a LAN address
desktop_link_template = "claude://claude.ai/epitaxy/{id}"
done_window_days = 7
require_tracker_log = false
rules_mode = "warn"
owner_names = ["owner", "me", "alex"]   # waiting_on values listed in the Inbox

[stages.labels]
dev = "in progress"
done = "shipped"

[reports.labels]
verified = "checked"

[reports.hints]
M = "medium change"

[rules]
guidance = "Ask the owner before anything goes live."
description_template = "Goal:\nWhy:\nDone when:"

[rules.report_format]
sizes = ["S", "M", "L"]

[rules.stage_requirements]
test = [{ kind = "report_since_stage_change" }]
done = [{ kind = "field_present", field = "progress" }]