Configuration

p2proxy reads a YAML config file passed via --config. The bundled example in the repo is a good starting point; this page covers every field.

Top-level keys

Key	Type	Default	Description
`port`	u16	`45445`	UDP port libp2p listens on. Forwarding it isn’t required, but improves direct (non-relayed) peer connectivity.
`log_level`	string	`info`	One of `trace`, `debug`, `info`, `warn`, `error`.
`servers`	list	—	One or more proxy listeners (below).

Per-server keys

Each entry under servers defines a SOCKS5 listener and its peer selection rules.

Key	Type	Default	Description
`protocol`	enum	—	`Socks5`. Currently the only supported protocol.
`port`	u16	—	Local TCP port to listen on for incoming SOCKS5 connections.
`min_bandwidth`	string	`0Mbps`	Minimum advertised bandwidth a peer must have. Format: `<N>{Kbps,Mbps,Gbps}`.
`country`	string	—	Optional ISO-3166 alpha-2 country code (e.g. `US`, `DE`, `JP`). Omit to allow any country.
`destination_peer`	string	—	Optional explicit libp2p multiaddr to pin traffic to a known peer.
`pool`	object	—	Optional connection-pool tuning (below).

Connection-pool keys

Connection pooling keeps warm libp2p streams open between requests so SOCKS5 handshakes don’t pay the dial cost on every connection. Tune per-server.

Key	Type	Default	Description
`enabled`	bool	`true`	Toggle pooling. Disabling means every SOCKS5 connection dials a fresh stream.
`min_idle`	u32	`5`	Always keep at least this many warm streams open.
`max_total`	u32	`30`	Hard ceiling on concurrent streams.
`idle_timeout_secs`	u64	`60`	Drop streams idle longer than this.
`open_timeout_secs`	u64	`20`	Give up dialing a new stream after this long.
`max_retries`	u32	`3`	Retries before giving up on a failed request.
`max_error_rate`	float	`0.15`	Failover threshold; rotate peer when its observed error rate exceeds this fraction.

Environment variables

Variable	Description
`BITPING_API_KEY`	Required. Authenticates the daemon to the Bitping network. Usage is attributed to your account.
`NO_UI`	If `true`, disables the TUI (equivalent to `--no-ui`). Defaults to `true` in the official Docker image.
`RUST_LOG`	Standard Rust tracing filter (`trace`, `debug`, `info`, `module=trace`, …). Overrides `log_level` from `Config.yaml`.

Recipes

Country-pinned pool

A single SOCKS5 listener that only routes through nodes in the US, with high bandwidth required:

port: 45445
servers:
  - protocol: Socks5
    port: 1080
    country: US
    min_bandwidth: 100Mbps

Multi-region setup

Three listeners on different local ports, each pinned to a region:

port: 45445
servers:
  - protocol: Socks5
    port: 1080
    country: US
  - protocol: Socks5
    port: 1081
    country: DE
  - protocol: Socks5
    port: 1082
    country: JP

Point your client at localhost:1080 for US traffic, localhost:1081 for DE, etc.

Tight pool for low-latency workloads

Keep more streams permanently warm to absorb request bursts:

servers:
  - protocol: Socks5
    port: 1080
    min_bandwidth: 100Mbps
    pool:
      min_idle: 20
      max_total: 60
      idle_timeout_secs: 120
      max_error_rate: 0.05

Pinned single peer

For repeatable tests, route exclusively through a known peer:

servers:
  - protocol: Socks5
    port: 1080
    destination_peer: /ip4/.../tcp/.../p2p/<peer-id>

When to tune the pool

Bumping min_idle — if first requests after idle periods are noticeably slower, raise this so streams are always pre-warmed.
Bumping max_total — if you’re throwing concurrent requests and see them queueing.
Lowering max_error_rate — if you want faster failover off flaky peers; expect more rotation churn.
Disabling pooling (enabled: false) — only useful for debugging or for very low-volume traffic where peer rotation per request is acceptable.

Integrations — wire your client at the SOCKS5 listener.
Operations — systemd, Docker, metrics.

Customers

Nodes