Configuration

RelayCore is configured primarily through CLI flags, environment variables, and a default data directory. There is no unified config.toml loader today.

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-cli ca generate, relay-core-cli run reads from these paths. If CA files are missing, run exits with an actionable error.

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-cli` and `relay-core-probe`
`RELAY_CA_KEY`	CA key path (must be paired with `RELAY_CA_CERT`)
`RELAY_LOG`	Log filter level (e.g. `info`, `debug`, `trace`)
`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_PORT`	`relay-core-probe` proxy port (default 8080)
`RELAY_PROBE_TRANSPORT`	MCP transport: `stdio` (default) or `sse`
`RELAY_PROBE_PORT`	MCP listen port in SSE mode (default 3000)
`RELAY_PROBE_BIND`	MCP bind address in SSE mode (default 127.0.0.1)

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

TUI config file

The TUI reads a small TOML file at ~/.relay-core/config.toml to set persistent preferences. The only key currently consumed is the TUI theme:

# ~/.relay-core/config.toml
[tui]
theme = "high-contrast"   # relay | slate | high-contrast

Resolution order for the TUI theme: --theme flag > RELAY_CORE_TUI_THEME env > [tui].theme in this file > default (relay).

Common CLI flags (run)

relay-core-cli run [options]

  --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>      Enable REST + SSE HTTP API
  --api-token <TOKEN>    Bearer auth for the HTTP API
  --rules <PATH>         Load rules file (JSON/YAML)
  --script <PATH>        Load Deno script
  --script-env-allow      Comma-separated env var names scripts may read
  --ui                   Enable TUI
  --theme <NAME>         TUI color preset
  --upstream <URL>       Route all traffic through a parent proxy
  --save-stream <PATH>   Append every flow 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