FoxyVPN

A standalone Python client and local SOCKS5 proxy for the Mozilla VPN / Firefox VPN proxy service, distributed as a standard PyPI package.

This is an independent Python rewrite of firefox-vpn-client (originally written in Go). It reimplements the same Firefox Accounts authentication, Mozilla VPN "Guardian" control plane, Fastly anti-bot challenge solver, and local SOCKS5-over-HTTP/2 or HTTP/3 proxy, packaged as an installable pip package with a console entry point and an automated release workflow.

Disclaimer: This is an unofficial, community client. It is not affiliated with or endorsed by Mozilla. Use it only with an account and subscription you are authorized to use, and in accordance with Mozilla VPN's terms of service.

Features

• Firefox Accounts login (email + password, with email 2FA code verification, falling back to a confirmation-link prompt if FxA requires it) or reuse of pre-provisioned session tokens, with automatic rotation across a pool of tokens.
• Cached OAuth tokens (~/.foxyvpn-tokens.json, written with 0600 permissions) with automatic refresh.
• Automatic solving of Fastly's client-side anti-bot "Client Challenge" (proof-of-work, Private Access Token probing, and client-metrics beacons), including on Hawk-signed FxA requests, where the request signature is rebuilt fresh on every retry.
• Mozilla VPN "Guardian" proxy-pass issuance, renewal, quota monitoring, and account entitlement lookups, including clock-skew-tolerant JWT expiry parsing.
• VPN server list discovery via Firefox Remote Settings, with country/city selection (defaulting to Firefox's own recommended "REC" server when no country is given) and a persisted proxy-state file across restarts, including clearing a persistently failing proxy selection after repeated connection failures.
• A local SOCKS5 (RFC 1928, CONNECT-only) proxy that tunnels traffic to the upstream Mozilla VPN proxy node over HTTP/2 (default) or HTTP/3 (--http3), with connection pooling, client-IP affinity across multiple upstream connections, idle timeouts, and a maximum-connections limit.
• Non-fatal exit-IP/country verification after connecting.
• Optional JSON status file describing the current proxy-pass health, for supervisord/systemd-style monitoring.
• Structured logging (text or JSON) to stderr.

Installation

pip install foxyvpn

Or, from a source checkout:

pip install .

That's it — both HTTP/2 and HTTP/3 (--http3) upstream transports are included in the base install; there is no separate extra to opt into.

Usage

# First run: interactive Firefox Accounts login, auto-selects a proxy server.
foxyvpn --country us

# Force a fresh login instead of reusing cached tokens.
foxyvpn --login --country us

# Use a specific upstream proxy instead of country-based selection.
foxyvpn --proxy us1.example.com:443

# Authenticate with a pre-provisioned session token (or a file with one
# token per line for automatic rotation on quota exhaustion).
foxyvpn --session-token /path/to/tokens.txt --country de

# Use HTTP/3 (QUIC) for the upstream tunnel instead of HTTP/2.
foxyvpn --http3 --country us

# Print account entitlement info and exit.
foxyvpn --print-info

# Print the available server list and exit.
foxyvpn --list-servers

Once running, point any SOCKS5-aware client at the local listener (default 127.0.0.1:1080):

curl --socks5-hostname 127.0.0.1:1080 https://example.com

CLI flags

Development

There is no automated test suite: the login, 2FA, quota-exhaustion, and challenge-solving flows all require a real Firefox Account and live Mozilla VPN entitlement, which can't run unattended in CI. Local changes are verified by building and inspecting the package instead:

pip install -e ".[dev]"
python -m build
python -m twine check dist/*

License

MIT