Skip to content
bytetourist

Quickstart

This guide gets a request flowing through the proxy. You’ll need an API key (create one in the dashboard). A key is a single secret, shown once at creation.

1. Point your client at the proxy

Section titled “1. Point your client at the proxy”

bytetourist speaks the standard HTTP proxy protocol, so any HTTP client works. The proxy listens on :8080 by default.

curl -k -x http://dev.bytetourist.com:8080 \
  -U "YOUR_API_KEY:" \
  https://api.ipify.org?format=json

-x sets the proxy; -U sends the API key as the Proxy-Authorization username, with no password. -k is there because the proxy re-signs HTTPS to route each request. See HTTPS targets below. The response comes back from one of the fleet’s edges.

2. Target a country

Section titled “2. Target a country”

Encode targeting directly in the proxy username as - separated param-value pairs after your API key:

curl -k -x http://dev.bytetourist.com:8080 \
  -U "YOUR_API_KEY-cc-de:" \
  https://api.ipify.org?format=json

That asks for an edge in Germany (cc-de). See all params in the reference.

3. Choose a routing strategy

Section titled “3. Choose a routing strategy”

Add strategy-<name> to control how the edge is picked. freshest_ip always uses the least-recently-used edge for this (org, host) pair:

curl -k -x http://dev.bytetourist.com:8080 \
  -U "YOUR_API_KEY-cc-de-strategy-freshest_ip:" \
  https://api.ipify.org?format=json

Leave it out and requests use the default, goodput_per_second, which favours the edges delivering the most pages per second.

Prefer headers?

Section titled “Prefer headers?”

The username encoding works the same for HTTP and HTTPS, so it’s the one to reach for. The routing options also exist as X-Proxy-* headers, which take precedence over username-encoded values, but where they go depends on the target:

  • Plain HTTP: send them as ordinary request headers.

    curl -x http://dev.bytetourist.com:8080 \
      -U "YOUR_API_KEY:" \
      -H "X-Proxy-Country: de" \
      -H "X-Proxy-Strategy: freshest_ip" \
      http://api.ipify.org?format=json

  • HTTPS: the routing headers must go on the CONNECT request that opens the tunnel (in curl, --proxy-header). Headers sent with -H travel inside the tunnel, where the routing headers are not read.

    curl -k -x http://dev.bytetourist.com:8080 \
      -U "YOUR_API_KEY:" \
      --proxy-header "X-Proxy-Country: de" \
      --proxy-header "X-Proxy-Strategy: freshest_ip" \
      https://api.ipify.org?format=json

Routing headers read this way are stripped before the request leaves the edge.

HTTPS targets

Section titled “HTTPS targets”

HTTPS goes through the proxy’s own certificate authority: the proxy re-signs each site’s certificate so it can route the request. Your client has to accept that certificate. For a first test, use -k (or your client’s equivalent) as above; for real use, configure your client to trust the bytetourist CA.

curl -k -x http://dev.bytetourist.com:8080 \
  -U "YOUR_API_KEY-cc-de:" \
  https://example.com

Next steps

Section titled “Next steps”