This walkthrough takes you from a clean machine to a working SOCKS5 proxy routing through the Bitping peer network. It assumes you’ve already followed Install.

1. Get your Bitping API key

Sign up or log in at bitping.com and copy your API key from the dashboard.

Export it in your shell:

export BITPING_API_KEY=<your-key>

For long-running deployments, set this in your shell rc, systemd unit, or container environment instead.

2. Create a Config.yaml

The minimal config — one SOCKS5 listener, no peer filtering — looks like this:

bitping_api_key: <your-key>
servers:
  - protocol: Socks5
    port: 1080
    min_bandwidth: 50Mbps

What each field does:

• bitping_api_key — your Bitping API key. You can leave it out of the file and rely on the BITPING_API_KEY env var instead (it overrides the file value).
• servers[].port: 1080 — the local TCP port for your SOCKS5 listener. Point your client here.
• min_bandwidth: 50Mbps — only peers advertising ≥ 50 Mbps will be selected for this listener (50Mbps is also the default if you omit it).

p2proxy picks its own libp2p listen ports by default. To pin them, add listen_addrs (or the port shorthand). To change the logging level, set the log_level config key (default info) or the RUST_LOG env var, which overrides it. For the full reference, see Configuration.

3. Run the daemon

p2proxy --config Config.yaml

You should see the TUI come up. Within a second or two, the right-hand panel will start showing peer connections coming online.

If you’re running in Docker, systemd, or any environment without a TTY, pass --no-ui:

p2proxy --no-ui --config Config.yaml

4. Make your first proxied request

Open a second terminal and point curl at the SOCKS5 listener:

curl --socks5-hostname localhost:1080 https://ifconfig.me

The IP you get back should be the peer’s, not yours. That’s success.

5. Where to go next

• Integrations — wire p2proxy into Playwright, Puppeteer, Python requests, browsers, or a full tunnel.
• Configuration — country filtering, multi-endpoint setups, pinned and sticky peers.
• Operations — systemd, Docker, Prometheus scrape config.
• Troubleshooting — if anything above didn’t behave.