VPN locations

Pick a VPN type and a country, and a machine's browser and apps go online from there. Use it to see sites the way local users do, reach geo-restricted services, or get past bot checks.

• Just pick a type and a location. Burrowbox runs the network: no proxy accounts, zones or credentials on your side.
• Everything goes through it. That includes the built-in browser, curl, apt, pip, and any app that honors the system proxy settings.
• Live switching. Changing the country or type on a running machine takes effect at once, with no machine restart.
• Stable IP. Each machine keeps the same exit IP for as long as the network allows (the session is pinned per machine).

#Pricing

Both types are an add-on to the machine's normal rate:

Live values are in GET /api/vpn/locations (types[].pricing) and GET /api/pricing (vpn). Usage shows in your billing history as "running + VPN proxy/unlock" and "VPN … data".

#List types and locations

GET /api/vpn/locations needs no authentication.

{
  "available": true,
  "types": [
    { "type": "proxy", "name": "Proxy", "available": true, "description": "…", "pricing": { "centsPerHour": 3, "centsPerGb": 1000, "centsPer1kConnections": 0 } },
    { "type": "unlock", "name": "Unlock", "available": true, "description": "…", "pricing": { "centsPerHour": 6, "centsPerGb": 1500, "centsPer1kConnections": 300 } }
  ],
  "locations": [ { "country": "us", "name": "United States" }, { "country": "gb", "name": "United Kingdom" } ],
  "note": "Any two-letter country code works; these are the common ones. City targeting (e.g. newyork) is best effort."
}

#Turn it on

When creating a machine:

curl -X POST https://burrowbox.dev/api/machines \
  -H "Authorization: Bearer $BURROWBOX_KEY" -H "Content-Type: application/json" \
  -d '{"name": "acme", "vpn": {"type": "proxy", "country": "de"}}'

On an existing machine (live if it's running):

curl -X PUT https://burrowbox.dev/api/machines/2f6aeedcd3/vpn \
  -H "Authorization: Bearer $BURROWBOX_KEY" -H "Content-Type: application/json" \
  -d '{"vpn": {"type": "unlock", "country": "gb"}}'

• Off: {"vpn": null} turns it off.
• Defaults: type defaults to proxy.
• Partial changes: fields you leave out keep their current value, so {"vpn": {"country": "fr"}} changes only the country and {"vpn": {"type": "unlock"}} only the type.
• City: city is optional and lowercase, without spaces. It only works on networks that support city targeting: types[].cityTargeting in GET /api/vpn/locations. Elsewhere the API rejects a city with 400, because the network would refuse every connection. Changing the country clears the city, and "city": null removes it.
• Response: the machine, with "applied": true when the change took effect on the running machine.

Claiming from a warm pool takes the same vpn field, and it's applied to the ready machine instantly.

#Check where a machine browses from

GET /api/machines/{id}/vpn

{ "vpn": { "type": "proxy", "country": "de" }, "egress": { "ok": true, "ip": "91.108.196.68", "country": "DE", "city": "Berlin", "org": "AS209372 WS Telecom Inc" } }

Agents on the machine can ask the same with the machine MCP tool network_info.

#From an agent

Platform MCP tools: vpn_locations, machine_set_vpn, machine_vpn_status, plus a vpn argument on machine_create and pool_claim.

#HTTPS and privacy

unlock works by opening HTTPS traffic and re-encrypting it with the provider's (Bright Data's) certificate. While a machine uses unlock:

• Certificate: the machine trusts Bright Data's root certificate (official, CN "Bright Data Root CA", SHA-256 DB:85:48:F8:…:7B:60). It's added when unlock is turned on and removed when you switch to proxy or off.
• Who can see traffic: the provider can read the machine's web traffic, including pages you sign in to. Use proxy (or no VPN) for sessions you wouldn't route through a third party.
• Browser restart: switching to or from unlock restarts the browser once so it picks up the certificate change. Open tabs reopen automatically.

proxy leaves HTTPS end-to-end encrypted between the machine and the site.

#Notes

• Apps that ignore the system proxy (rare, e.g. some games or raw-socket tools) connect directly.
• Machines created before the VPN launched need to be recreated to use it.