Using the residential proxy

Your ProxyBox exposes an HTTP proxy that any HTTP-speaking client can use to route traffic through your home IP. This page covers setup on the devices we see most often.

Getting your credentials

Open the ProxyBox app → Proxy tab. You'll see four pieces of data:

• Host, the relay hostname (e.g., proxy.proxybox.us).
• Port, your device's assigned port (e.g., 16100).
• Username, auto-generated, looks like pb_0c0b3f20abc1.
• Password, 16-char random.

Tap "Copy URL" for the combined form: http://user:pass@host:port.

Why there's a relay

Your ProxyBox is behind your home NAT, it doesn't have a public IP. The relay sits in the cloud, keeps a persistent tunnel open from your Pi, and forwards proxy connections back through that tunnel. To your client, it looks like connecting to the relay. To websites you visit, your traffic appears from your home's residential IP.

macOS system proxy

System Settings → Network → your connection → Details → Proxies. Enable "Web Proxy (HTTP)" and "Secure Web Proxy (HTTPS)." Enter your ProxyBox host, port, username, password. OK.

Heads up: this only affects apps that respect system proxy settings. Many apps don't. For guaranteed coverage, use WireGuard mode instead (below).

Browser-only

Both Chrome and Firefox have extensions (FoxyProxy, Proxy SwitchyOmega) that route browser traffic through a specified proxy. Set them to your ProxyBox URL; all browser requests go through home.

curl / scripts

curl --proxy http://user:pass@host:port https://api.ipify.org

Or set env vars: export https_proxy=http://user:pass@host:port. Most HTTP tools (curl, wget, requests, httpx) respect this.

Python requests

proxies = {"https": "http://user:pass@host:port"}
requests.get("https://api.ipify.org", proxies=proxies)

Node fetch

const {HttpsProxyAgent} = require('https-proxy-agent');
const agent = new HttpsProxyAgent('http://user:pass@host:port');
fetch('https://api.ipify.org', {agent});

Testing it works

Easiest: open the app's Proxy tab and tap "Test It." The app makes a real request through the proxy and tells you which IP it came from. If it's your home IP, you're good.

Manual test: curl with the proxy, check the returned IP matches what your home router shows.

Common problems

407 Proxy Authentication Required: username/password wrong. Copy fresh from the app.

Connection refused: the ProxyBox may be offline, or your device might be configured to use an old relay host/port. Check the app for current values.

Works on laptop, not in a Docker container: Docker has its own proxy config. Pass --env https_proxy=... or add to Dockerfile.