> ## Documentation Index
> Fetch the complete documentation index at: https://onr.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# onr.yaml

> Core runtime server configuration.

The `onr.yaml` file is the master configuration for your ONR gateway. It dictates server ports, file watch reload behaviors, traffic dump controls, and observability settings.

## Server Settings

Controls the core HTTP server bounds and process signals.

```yaml theme={null}
server:
  listen: ":3300"
  read_timeout_ms: 60000
  write_timeout_ms: 60000
  pid_file: "/var/run/onr.pid"
```

## Global Authentication

You can secure the gateway itself by requiring an API key for incoming requests.

```yaml theme={null}
auth:
  api_key: "change-me"
```

*(If `api_key` is set, all clients must send `Authorization: Bearer change-me` or use a defined key in `keys.yaml`)*

## Upstream Forwarding Proxies

If ONR needs to egress traffic through a corporate proxy (like a NAT gateway or a local VPN client like Clash), you can set this universally per provider.

```yaml theme={null}
upstream_proxies:
  by_provider:
    openai: "http://127.0.0.1:7890"
    gemini: "socks5://172.18.156.198:1081"
```

## Hot Reloads

You can configure ONR to natively watch the `.conf` DSL files and reload itself safely without dropping inflight requests.

```yaml theme={null}
providers:
  dir: "./config/providers"
  auto_reload:
    enabled: true
    debounce_ms: 300
```

*Note: Enabled by default in dev, but usually disabled in Kubernetes in favor of Pod rollouts.*

## Traffic Dumps (Audit)

If you need to capture raw, unadulterated request/response payloads (for debugging or exact payload auditing), activate `traffic_dump`.

```yaml theme={null}
traffic_dump:
  enabled: true
  dir: "./dumps"
  file_path: "{{.request_id}}.log"
  # Set mask_secrets to true to auto-redact bearer tokens
  mask_secrets: true
  # Optional allowlist. Empty means all sections are enabled.
  # Allowed: meta, origin_request, upstream_request, upstream_response, proxy_response, stream
  sections: []
```

## Access Logs & Rotation

Access logs provide the core metrics generation for your cluster.
System logs are written to `stderr` with fixed prefix format:
`[ONR] <time> | <LEVEL> | <category> | <message> | key=value ...`

```yaml theme={null}
logging:
  level: "info" # debug | info | warn | error
  access_log: true
  access_log_path: "./logs/access.log"
  
  # Automatically infer client app names (like Cursor) from the User-Agent
  appname_infer:
    enabled: true
    
  # Enable built-in file rotation if you don't use logrotate
  access_log_rotate:
    enabled: true
    max_size_mb: 100
    max_backups: 14
    max_age_days: 14
    compress: false
```