8.6 KiB
Network & Proxy Configuration
This document covers network and proxy configuration options for bypassing geofencing and managing connections.
proxy_providers (dict)
Enable external proxy provider services. These proxies will be used automatically where needed as defined by the
Service's GEOFENCE class property, but can also be explicitly used with --proxy. You can specify which provider
to use by prefixing it with the provider key name, e.g., --proxy basic:de or --proxy nordvpn:de. Some providers
support specific query formats for selecting a country/server.
basic (dict[str, str|list])
Define a mapping of country to proxy to use where required.
The keys are region Alpha 2 Country Codes. Alpha 2 Country Codes are [a-z]{2} codes, e.g., us, gb, and jp.
Don't get this mixed up with language codes like en vs. gb, or ja vs. jp.
Do note that each key's value can be a list of strings, or a string. For example,
us:
- "http://john%40email.tld:password123@proxy-us.domain.tld:8080"
- "http://jane%40email.tld:password456@proxy-us.domain2.tld:8080"
de: "https://127.0.0.1:8080"
Note that if multiple proxies are defined for a region, then by default one will be randomly chosen.
You can choose a specific one by specifying it's number, e.g., --proxy basic:us2 will choose the
second proxy of the US list.
nordvpn (dict)
Set your NordVPN Service credentials with username and password keys to automate the use of NordVPN as a Proxy
system where required.
You can also specify specific servers to use per-region with the server_map key.
Sometimes a specific server works best for a service than others, so hard-coding one for a day or two helps.
You can also select servers by city using the format --proxy nordvpn:us:seattle or --proxy nordvpn:ca:calgary.
For example,
username: zxqsR7C5CyGwmGb6KSvk8qsZ # example of the login format
password: wXVHmht22hhRKUEQ32PQVjCZ
server_map:
us: 12 # force US server #12 for US proxies
The username and password should NOT be your normal NordVPN Account Credentials.
They should be the Service credentials which can be found on your Nord Account Dashboard.
Once set, you can also specifically opt in to use a NordVPN proxy by specifying --proxy nordvpn:gb or such.
You can even set a specific server number this way, e.g., --proxy nordvpn:gb2366.
Note that gb is used instead of uk to be more consistent across regional systems.
protonvpn (dict)
Enable Proton VPN as a proxy provider. Proton mints short-lived HTTPS proxy credentials per session, so
authentication reuses an exported account.proton.me browser session rather than static credentials.
Export the cookies for account.proton.me (Netscape cookies.txt or a JSON cookie list) — they must include
the AUTH-<UID> and REFRESH-<UID> cookies — and save them at <cookies>/vpn/protonvpn.txt. No yaml is
required: the provider auto-loads when that file exists. Exporting straight from the logged-in web page is
fine; cookies for other Proton apps (e.g. mail.proton.me) are ignored automatically. The session refreshes on
its own when the access token expires, so you only re-export if it is fully revoked. Free Proton accounts
work, limited to the free-tier exit countries.
Configuration is optional — only add a block to override defaults:
proxy_providers:
protonvpn:
cookie_path: /path/to/protonvpn.txt # optional; defaults to <cookies>/vpn/protonvpn.txt
server_map:
stream-us: us:ny # optional alias -> country / country:city / countryNN
Query formats (after the provider prefix). City uses the NordVPN-style colon, like nordvpn:us:seattle:
--proxy protonvpn:us— random server in the country (the chosen server name is logged)--proxy protonvpn:us:ny/protonvpn:ca:vancouver— by city (name or initials)--proxy protonvpn:de203— pin Proton server #203 (the number shown in the log, e.g.DE#203)
Use uk (Proton's code for the United Kingdom); gb is accepted and mapped to uk automatically. Proton's
server numbers are not sequential (a country may have #203, #813, …), so pick the number from a previous
run's log line rather than guessing.
Selection only offers servers your plan can use (paid accounts are detected automatically) and prefers paid
servers over the free pool, falling back to free only when no paid server is available — a pinned #NN always
wins. Tor and Secure Core servers are excluded (both are slow for a plain proxy). Secure Core servers use
port 443, all others 4443 — handled automatically.
surfsharkvpn (dict)
Enable Surfshark VPN proxy service using Surfshark Service credentials (not your login password).
You may pin specific server IDs per region using server_map.
You can also select servers by city using the format --proxy surfsharkvpn:us:seattle.
username: your_surfshark_service_username # https://my.surfshark.com/vpn/manual-setup/main/openvpn
password: your_surfshark_service_password # service credentials, not account password
server_map:
us: 3844 # force US server #3844
gb: 2697 # force GB server #2697
au: 4621 # force AU server #4621
hola
Enable Hola VPN proxy service. Requires the hola-proxy binary to be installed and available in your PATH.
No configuration is needed under proxy_providers. Hola is loaded automatically when the hola-proxy binary
is detected.
Once available, use --proxy hola:us or similar to connect through Hola.
windscribevpn (dict)
Enable Windscribe VPN proxy service using static OpenVPN service credentials.
Use the service credentials from https://windscribe.com/getconfig/openvpn (not your account login credentials).
proxy_providers:
windscribevpn:
username: openvpn_username # From https://windscribe.com/getconfig/openvpn
password: openvpn_password # Service credentials, NOT your account password
Server Mapping
You can optionally pin specific servers using server_map:
proxy_providers:
windscribevpn:
username: openvpn_username
password: openvpn_password
server_map:
us: us-central-096.totallyacdn.com # Force specific US server
gb: uk-london-001.totallyacdn.com # Force specific UK server
Once configured, use --proxy windscribevpn:us or --proxy windscribevpn:gb etc. to connect through Windscribe.
You can also select specific servers by number (e.g., --proxy windscribevpn:sg007) or filter by city
(e.g., --proxy windscribevpn:ca:toronto).
gluetun (dict)
Docker-managed VPN proxy supporting 50+ VPN providers via Gluetun. See GLUETUN.md for full configuration and usage details.
proxy_providers:
gluetun:
providers:
windscribe:
vpn_type: openvpn
credentials:
username: "YOUR_OPENVPN_USERNAME"
password: "YOUR_OPENVPN_PASSWORD"
Usage: --proxy gluetun:windscribe:us
headers (dict)
Case-Insensitive dictionary of headers that all Services begin their Request Session state with. All requests will use these unless changed explicitly or implicitly via a Server response. These should be sane defaults and anything that would only be useful for some Services should not be put here.
Avoid headers like 'Accept-Encoding' as that would be a compatibility header that the underlying HTTP backend (rnet) will set for you as part of its browser impersonation profile.
I recommend using,
Accept-Language: "en-US,en;q=0.8"
User-Agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
HTTP Session Backend
unshackle uses rnet (Rust + BoringSSL) for HTTP with TLS
fingerprinting. RnetSession is a drop-in requests.Session replacement and is what
self.session exposes to services. It supports:
- Browser/app impersonation via named
rnet.Impersonatepresets (Chrome, Edge, Firefox, Safari, OkHttp, etc.) — picks JA3, ALPN, HTTP/2 SETTINGS and header order to match the chosen client. - Native rnet proxy support (HTTP, HTTPS, SOCKS5) — used by all proxy providers below.
- Cookie-jar and
requests-styledata=/json=/headers=kwargs for compatibility.
The legacy curl_cffi backend has been removed. The config key is still spelled
curl_impersonate for backward compatibility, but its value now selects an rnet preset.
curl_impersonate (dict)
curl_impersonate:
browser: Chrome131 # exact rnet.Impersonate preset name
browser must be an exact rnet.Impersonate preset name (e.g. Chrome131, Chrome124,
Edge101, Firefox133, Safari18, OkHttp4_12). See the rnet README for the full list.
Default when unset: Chrome131.