Configuration

Configuration

Runtime configuration centers on config.toml. Use this page for common configuration tasks; use Configuration Reference for the complete generated config.example.toml and Defaults and Limits for exact default values.

Config is the source of truth

Keep long-lived runtime behavior in config.toml. CLI flags are temporary overrides for local testing or one-off route changes.

Configuration map

Local listeners

HTTP addresses for the proxy and MCP control surface.

[server][mcp]

Routing

Default providers and explicit model/protocol routes.

[routing.default_provider_names][[routing.routes]]

Providers

Upstream endpoints, provider protocols, API keys, and compatibility mode.

[providers.<name>]

Streaming safety

Timeouts for incomplete streamed tool-call arguments and idle upstream reads.

[tool_calls]read_idle_timeout_secs

Diagnostics

Capture switches, log format, and duration coloring thresholds.

[capture][logging][logging.duration_thresholds]

Client-facing errors

Readable text errors for Zed or JSON errors for OpenAI-compatible clients.

[error_responses]

Find the app directory

Generated runtime files live under the user app directory:

Platform	Path
Windows	%USERPROFILE%.proxai\
Linux/macOS	~/.proxai/

Important entries:

Path	Purpose
config.toml	Runtime configuration, intentionally git-ignored
config.example.toml	Generated local example/reference
logs/	Runtime log output
captures/	Optional per-phase capture artifacts

For repository and app-directory boundaries, see Environment and Files.

Minimal local config

A minimal useful setup needs a local listener, default provider mapping, and at least one provider.

[server]
host = "127.0.0.1"
port = 18080

[routing.default_provider_names]
openai_responses = "openai"
openai_chat_completions = "openai"
anthropic_messages = "anthropic"

[providers.openai]
protocol = "openai_responses"
base_url = "https://api.openai.com"
api_key = "..."

[providers.anthropic]
protocol = "anthropic_messages"
base_url = "https://api.anthropic.com"
api_key = "..."

Never commit secrets

api_key values belong in local config.toml, not in tracked examples, logs, docs, captures, or fixtures.

Add a provider

Each provider describes one concrete upstream. This page keeps only the quick shape; use Provider Setup for provider naming, auth headers, defaults, and route examples.

[providers.openai]
protocol = "openai_responses"
base_url = "https://api.openai.com"
api_key = "..."

Provider names are labels. Provider protocol controls outbound wire behavior. See Glossary for the distinction between provider name and provider protocol.

Set default providers

[routing.default_provider_names] declares fallback providers per inbound request protocol. Defaults are used only when no explicit route matches.

[routing.default_provider_names]
openai_responses = "openai"
openai_chat_completions = "openai_chat"
anthropic_messages = "anthropic"

Supported keys are the protocol values from Protocols:

• openai_responses
• openai_chat_completions
• anthropic_messages

Add an explicit route

Use an explicit route when a model pattern needs a specific provider, optional inbound protocol guard, or upstream model rewrite.

[[routing.routes]]
name = "m3_chat"
request_protocol = "openai_chat_completions"
match_kind = "exact"
model_pattern = "MiniMax-M3-preview"
provider = "minimax"
upstream_model = "MiniMax-M3"

Field	Role
name	Optional stable identifier for CLI overrides
request_protocol	Optional inbound protocol guard
match_kind	Optional exact, glob, regex, or auto
model_pattern	Logical model selector
provider	Provider name selected when this route matches
upstream_model	Optional upstream model mapping

For exact matching outcomes, see Route Matching.

Tune streaming timeouts

There are two different timeout concepts:

Setting	Layer	Purpose
[tool_calls].timeout_secs	Protocol semantics	Timeout for incomplete streamed tool-call arguments
[providers.<name>].read_idle_timeout_secs	Transport carrier	Idle-read timeout while waiting for upstream response bytes

Keep them separate: read_idle_timeout_secs watches raw upstream bytes, while tool_calls.timeout_secs watches semantic tool-call completion.

Enable captures

Capture phase switches live under [capture]:

[capture]
inbound_request_enabled = false
provider_request_enabled = false
upstream_response_enabled = false
outbound_response_enabled = false

1. 1Pick the narrowest phaseUse the phase that answers your question.
2. 2Enable it brieflyUse config or `proxai capture enable ...` for one debugging window.
3. 3Reproduce onceSend one sanitized request.
4. 4Disable captureCaptures can contain prompts, tool arguments, model outputs, and upstream payloads.

Capture paths are fixed under the app directory. For phase meanings and privacy risk, see Capture Phases.

Configure logging

[logging] controls output format and color behavior. [logging.duration_thresholds] controls human-log duration coloring.

Field	Meaning
output_format	human for interactive debugging or json for machine consumption
use_color	Enable or disable colored human logs
warn_ms / error_ms	Human log duration coloring thresholds

Logs should stay compact and should not include request bodies, API keys, Authorization headers, or private prompts.

Choose error response format

[error_responses] selects how client-facing errors are rendered.

Value	Meaning
text	Concise Zed-readable error bodies; default
json	OpenAI-style JSON error bodies for non-Zed clients

[error_responses]
format = "text" # or "json"

For upstream status handling and preserved headers, see Error Responses.