Configuration overview

Configuration is read from a single file in TOML or YAML. The format is chosen from the path’s extension: .yaml / .yml → YAML; .toml and anything else (including a missing extension) → TOML. Pass the file path as the positional CONFIG argument or via HUGINN_CONFIG_PATH:

huginn-proxy config.toml
huginn-proxy config.yaml
HUGINN_CONFIG_PATH=config.yaml huginn-proxy

Validate a config file without starting the proxy:

huginn-proxy --validate config.toml
huginn-proxy --validate config.yaml

Hot reload: dynamic sections update on SIGHUP or a file-watcher trigger without dropping connections. Static sections require a process restart — changes are logged as a warning and ignored. See the SETTINGS.md reference on GitHub for the static/dynamic split per section.

Environment variables

These apply to the huginn-proxy process. They do not change how TOML vs YAML is detected: that is always from the config file path you pass (positional argument or HUGINN_CONFIG_PATH) — extension .yaml / .yml → YAML, .toml or other → TOML.

Variable	Role
`HUGINN_CONFIG_PATH`	Path to the config file when you do not pass it as the sole CLI argument (equivalent to `huginn-proxy /path/to/config`).
`HUGINN_WATCH`	Set to `true` to enable a file watcher so config (and other reloadable files, e.g. TLS PEMs) can refresh without sending `SIGHUP`.
`HUGINN_WATCH_DELAY_SECS`	Debounce delay in seconds after a file change before reload (avoids thrashing on editors that rewrite often).
`RUST_LOG`	Overrides log filtering at the Rust tracing layer; can override `[logging].level` — see Logging.

eBPF (TCP SYN path): when the proxy uses pinned BPF maps, it also reads HUGINN_EBPF_PIN_PATH and HUGINN_EBPF_SYN_MAP_MAX_ENTRIES — they must match the agent. Documented in eBPF TCP setup.

Canonical field tables and copy-paste snippets: SETTINGS.md (same content as the shipped reference in the repo).

Use the pages below for narrative, behavior, and examples alongside the reference.

Top-level keys

Rough split: static blocks need a process restart to take effect; dynamic blocks reload on SIGHUP or the config file watcher (see SETTINGS.md for edge cases).

Static (restart required)

Key	Page / notes
`preserve_host`	Top-level bool — Routes (forwarding `Host` upstream)
`[listen]`	Listen
`[tls]`	TLS — PEM paths may still refresh via watcher
`[fingerprint]`	Fingerprinting
`[timeout]`	Timeout
`[logging]`	Logging
`[telemetry]`	Telemetry

Dynamic (hot-reloadable)

Key	Page / notes
`[[backends]]`	Backends
`[[routes]]`	Routes
`[security.ip_filter]`	IP filtering
`[security.rate_limit]`	Rate limiting
`[security.headers]`	Security (HSTS, CSP, custom — reloadable)
`[headers]`	Headers
`[backend_pool]`	Backends

[security] also includes max_connections (Security), which is static — restart required. Treat [security] as mixed: use the pages above for each subsection.

Examples (repository only)

Full config samples are not copied into this site: they would drift from the repo and are tedious to keep in sync. Use the checked-in files as the source of truth:

Smallest end-to-end file: the “Complete minimal example” in SETTINGS.md (TOML and YAML at the bottom of that document).
Full-featured reference (listen, TLS, routes, headers, fingerprinting, security, telemetry, etc.): examples/config/compose.yaml and compose.toml in the same folder.

How it works: request path through the proxy
Quick start: first request end-to-end