Configuration

Configuration comes from four layers, in this order: CLI flag > environment variable > config file > built-in default. A one-off override therefore never requires editing a file, and settings that must survive across commands go in $RELAY_DATA_DIR/config.toml.

relay-core config init writes a commented config file, relay-core config show prints the settings in effect (file values merged over the defaults), and relay-core config path prints where the file lives. A config file that cannot be parsed stops the command instead of falling back to defaults: silently ignoring a typo runs a daemon with settings nobody asked for.

Default data directory

The default directory is ~/.relay-core (override with RELAY_DATA_DIR). HTTPS interception files:

ca_cert.pem — CA certificate
ca_key.pem — CA private key
ca_cert.json — CA metadata (required for persistent load)

After relay-core ca generate, the daemon reads from these paths. When the files are missing it creates them on first start; HTTPS interception still needs ca install to trust that CA, plain HTTP does not.

The same directory also holds daemon.db (SQLite for flows and audit), daemon.json (discovery manifest), and logs. The CLI and MCP share this directory by default; set a different RELAY_DATA_DIR to isolate an experiment, or use relay-core start --in-memory.

Flow retention

Since 0.13.1 the product default is at most 5000 flows, and drop anything older than 7 days (audit events stay unbounded by default). Hot data is an in-memory LRU of about 200 flows; persistence remains SQLite. Use MCP clear_flows or policy retention to purge / retune; an explicitly empty retention means unbounded.

Config file

# ~/.relay-core/config.toml — set only what you change; the rest uses built-in defaults
[daemon]
api_port = 8082        # control API / Web UI port (an ephemeral port is used when taken)
mcp_port = 18083       # MCP endpoint port
mcp = true             # serve the MCP endpoint from the daemon
idle_timeout = 0       # stop the proxy after N seconds without traffic; 0 = never
save_stream = ""       # append every flow update as JSONL here (empty = no recording)

[proxy]
port = 8080            # port `start` / `run` use when none is named

[client]
autostart_daemon = true   # may the MCP bridge start a daemon on its own?

[tui]
# theme = "relay"      # relay | slate | high-contrast (see below)

Environment variables

Variable	Description
`RELAY_DATA_DIR`	Data directory (default `~/.relay-core`)
`RELAY_CA_CERT`	CA cert path (must be paired with `RELAY_CA_KEY`); applies to `relay-core` and `relay-core-probe`
`RELAY_CA_KEY`	CA key path (must be paired with `RELAY_CA_CERT`)
`RUST_LOG`	Log filter (e.g. `info`, `debug`, `trace`). `RELAY_LOG` appears in the CLI help but is not read
`RELAY_CORE_TUI_THEME`	TUI color preset when `--theme` is omitted (`relay`, `slate`, `high-contrast`). See TUI themes.
`RELAYCORE_UPSTREAM_PASSWORD`	Upstream proxy HTTP Basic auth password. Paired with `--upstream-auth-user`. Never pass the password via CLI — it would land in shell history. See Proxy Modes § upstream.
`RELAY_API_PORT` / `RELAY_MCP_PORT` / `RELAY_PROXY_PORT`	Port overrides for the daemon and the proxy (`--api-port` / `--mcp-port` / `--listen`)
`RELAY_PROXY_IDLE_TIMEOUT`	Seconds without captured traffic before the proxy stops; `0` never stops it
`RELAY_MCP_URL` / `RELAY_MCP_TOKEN`	Point the MCP bridge at an explicit endpoint instead of discovering the daemon
`RELAY_MCP_NO_AUTOSTART`	Set to `1` to forbid the MCP bridge from starting a daemon itself

Path precedence: CLI args > environment variables > default data directory.

TUI theme

The TUI takes its theme from [tui].theme in the file above — one file, one reader, so relay-core config show reports it too. Resolution order: --theme flag > RELAY_CORE_TUI_THEME env > [tui].theme > default (relay).

Common CLI flags

relay-core start [options]      # daemon + proxy (idempotent)
relay-core run [options]        # the same daemon, in the foreground

  -l/--listen <ADDR>     Proxy listen address (default 127.0.0.1:8080)
  --ca-cert <PATH>       CA certificate path (optional override)
  --ca-key <PATH>        CA private key path (must pair with --ca-cert)
  --api-port <PORT>      Control API / Web UI port (ephemeral when taken)
  --api-token <TOKEN>    Bearer token (the daemon generates one by default)
  --mcp-port <PORT>      Serve the MCP endpoint from the daemon
  --rules <PATH>         Load rules file (JSON/YAML)
  --script <PATH>        Load Deno script
  --script-env-allow      Comma-separated env var names scripts may read
  --ui                   Foreground daemon with the TUI attached as a client
  --theme <NAME>         TUI color preset
  --upstream <URL>       Route all traffic through a parent proxy
  --save-stream <PATH>   Append every flow update as JSONL to disk

Production notes

Bind to 127.0.0.1 for local-only use
When using --api-port, protect access with --api-token
For shared team CA, align on RELAY_DATA_DIR or explicit --ca-cert / --ca-key