Skip to content

docs: say what debug.allow_public costs (#64 item 3) #73

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jason-shen merged 1 commit into from
Sep 2, 2026
Merged

docs: say what debug.allow_public costs (#64 item 3) #73

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ port = "8080"

[debug]
bind = "" # Empty disables pprof; use 127.0.0.1:6060 and an SSH tunnel in production
allow_public = false # Must be true to bind pprof to a non-loopback address
allow_public = false # Required for a non-loopback bind; only for network-isolated deployments
block_profile_rate = 0 # 1 records every blocking event; 0 disables block profiling
mutex_profile_fraction = 0 # 1 records every mutex contention event; 0 disables mutex profiling

Expand Down Expand Up @@ -151,7 +151,8 @@ Notes:

- `server.public_ip` plus `server.turn_secret` enables the built-in Pion STUN/TURN server, replacing an external coturn container. TURN listens on UDP and TCP 3478 and relays media on UDP 50001–60000.
- `server.max_sessions` bounds the blast radius of distributed clients: the per-IP rate limit cannot, and every session burns CPU and provider spend. Past the cap, `POST /whip` returns 503 with `Retry-After`; session resumes are exempt, since they reattach to a session that is already counted. Size it to what one instance can actually serve.
- `debug.bind` enables Go's pprof handlers on a separate listener. Keep it on loopback and reach it through an SSH tunnel; a non-loopback address is rejected unless `debug.allow_public = true` explicitly acknowledges that profiles expose process data and CPU profiles consume resources. The public server never serves `/debug/pprof/`.
- `debug.bind` enables Go's pprof handlers on a separate listener. Keep it on loopback and reach it through an SSH tunnel. The public server never serves `/debug/pprof/`.
- `debug.allow_public` is only for network-isolated deployments. There is no authentication on the listener. With `debug.allow_public = true` on a reachable interface, `/debug/pprof/profile?seconds=3600` is an anonymous CPU-pinning DoS, and a heap dump from this server can contain provider API keys, caller audio buffers and transcripts. A non-loopback bind is rejected unless this flag is set.
- `debug.block_profile_rate` and `debug.mutex_profile_fraction` enable the corresponding runtime profiles while the debug listener is active. Both default to `0` (off); set either to `1` to record every event while diagnosing contention.
- `plugins.directory` is required for plugins and skills to load; omit it and discovery is skipped.
- `pipeline.barge_in` lets users interrupt the agent while it is speaking. Agent audio ducks as soon as the caller starts talking over it and recovers if the interruption turns out to be a backchannel.
Expand Down
Loading