Connect a client

Point a browser, phone, or backend at the proxy — manually or via the per-device PAC URL.

To capture a client's traffic, route it through the proxy — either by setting a manual proxy in the client's network config, or by pointing it at a per-device PAC URL that does it for you.

The two ways

  • Manual — set the proxy host and port directly in the client's network settings. Simple, works everywhere, but all clients behind one network share an identity.
  • PAC URL — point the client at a per-device auto-config URL. The proxy hands the client a tiny script that sends traffic to a port dedicated to that one device, so each shows up as its own feed even behind the same NAT. This is the recommended path when you have more than one client.

Manual proxy config

Use the proxy host with port 8888 as an HTTP/HTTPS proxy. The same listener handles both plain HTTP and HTTPS (CONNECT) traffic.

  • curl
    bash
    curl -x http://proxy.busymate.net:8888 https://example.com/
# local instance:
curl -x http://localhost:8888 https://example.com/
  • macOS — System Settings → Network → your connection → Details → Proxies. Turn on both "Web Proxy (HTTP)" and "Secure Web Proxy (HTTPS)", set each to the proxy host and port 8888.
  • Firefox — Settings → Network Settings → Manual proxy configuration. Set HTTP Proxy to the host, port 8888, and tick "Also use this proxy for HTTPS".
  • Android — Wi-Fi network → Modify → Proxy → Manual. Set the hostname and port 8888. (Behind one NAT, prefer the PAC URL below so each device is told apart.)
  • Your backend — most HTTP clients honour HTTP_PROXY / HTTPS_PROXY:
    bash
    export HTTP_PROXY=http://proxy.busymate.net:8888
export HTTPS_PROXY=http://proxy.busymate.net:8888

A direct (non-CONNECT) plain-HTTP request is forwarded too; the proxy's own management URLs are handled locally and never forwarded upstream.

Heads up: On the hosted proxy the :8888 listener has no per-request password — egress is gated by a source-IP allowlist instead, so only known devices can relay through it. For your own clients, the PAC URL path handles this for you. Background on the gate is in Proxy server architecture.

Per-device PAC URL

When several clients sit behind one network, a plain host:8888 config can't tell them apart — they all look like the same source. The per-device port pool fixes that: each device claims a dedicated port and uses a PAC URL anchored to it, so its traffic always lands on that one port and is tagged as that one device.

1. Allocate a port

Ask the proxy for a port for a device UUID:

bash
curl -X POST https://proxy.busymate.net/allocate \
  -u "<cert-bundle-user>:<cert-bundle-pass>" \
  -H "content-type: application/json" \
  -d '{ "uuid": "<device-uuid>", "deviceName": "My Pixel", "country": "US" }'
json
{ "port": 9042, "baseDomain": "busymate.net", "uuid": "<device-uuid>", "deviceName": "My Pixel" }

The port is stable per UUID — calling /allocate again for the same device returns the same port, across proxy restarts. Allocation also spins up the listener immediately and records the device into your dashboard.

Note: iOS does this automatically, and devices you add from the dashboard get a port allocated for them. You only call /allocate by hand for a client you're wiring up yourself.

2. Point the client at its PAC URL

Set the client's automatic proxy configuration (Wi-Fi → Proxy → Auto) to:

http://<port>.busymate.net/

The same body is also served at /proxy.pac and /wpad.dat on that host, so any of these work:

http://9042.busymate.net/
http://9042.busymate.net/proxy.pac
http://9042.busymate.net/wpad.dat

Wildcard DNS resolves every *.busymate.net name to the proxy, so the per-device subdomain only routes the PAC fetch — the proxy hop itself rides the stable apex.

3. What the PAC returns

For a numeric (port) subdomain the PAC body is just:

function FindProxyForURL(url, host) {
    return "PROXY busymate.net:9042; DIRECT";
}

Every connection now lands on port 9042, which the proxy owns for that one device — so each device gets its own feed. The DIRECT fallback keeps the client online if the proxy is briefly unreachable. Renaming a device does not change its port or PAC URL.

The full attribution chain (port pool → SNI → IP → proxy identity) is described in Per-device attribution.

Next

Install & runTrust the CA