This page explains how runtime configuration moves from files and CLI overrides into validated runtime state.
- Resolve config pathUse --config when provided; otherwise use the app directory location.
- Generate local examplesFirst run can create local example files without overwriting the tracked repository example.
- Parse config.tomlLoad TOML into the typed config schema.
- Validate invariantsRequired providers, routes, protocols, and timeout values are checked before startup completes.
- Build runtime stateValidated config becomes AppState used by request handling.
| Concern | Owner |
|---|
| Config schema | src/config.rs |
| App directory resolution | src/paths.rs |
| CLI flags and temporary overrides | src/cli/ |
| Provider selection from config | src/routing/ and pipeline routing step |
| Runtime request access | AppState in src/lib.rs |
| User-facing examples | config.example.toml, using/configuration, reference/configuration |
| Invariant | Why |
|---|
| Invalid config fails startup | A partially-valid proxy would be harder to diagnose than a startup error. |
| Provider protocol controls outbound wire behavior | Provider names are arbitrary labels and cannot imply protocol semantics. |
Route request_protocol guards are strict | Endpoint-specific routing must not fall through silently. |
tool_calls.timeout_secs must be positive | Tool-call stalls need a bounded semantic timeout. |
| Local private config is not committed | config.toml, captures, and logs can contain secrets or prompts. |
- Add the typed field in
src/config.rs.
- Add a concise example/comment in
config.example.toml.
- Wire the setting into
src/main.rs, src/lib.rs, or the owning module.
- Update user docs if behavior is user-facing.
- Update reference docs and tests for defaults/validation.