alle-proxy 0.1.0

The unofficial, universal VPN client: manage multiple VPN providers and locations in one place through a single sing-box process, with rule-based routing planned. CLI today; web UI and menu-bar GUI planned.

alle

An unofficial but more powerful VPN client for multiple VPN providers.

Why alle

Most VPN clients are built around one global idea: connect this device to a single VPN server, then send everything through it until you disconnect or switch.

That is not enough when different resources need to appear from different regions — a geo-fenced stream, a bank that blocks foreign IPs, a region-locked test environment. Switching origins means disconnecting from one server and reconnecting to another, and the official client on one machine usually cannot keep several locations active at once anyway.

alle keeps multiple VPN exits live at the same time, from one provider or mixed across several. Say you want a US exit, a UK exit, and a Japan exit at once — NordVPN for the US and Japan, ProtonVPN for the UK:

   streaming + admin   ──►  `alle`  ──►  United States   (NordVPN)
   test runner         ──►  `alle`  ──►  Japan           (NordVPN)
   bank login          ──►  `alle`  ──►  United Kingdom  (Proton VPN)

Each app points at the exit it needs; they run concurrently and independently, so opening the bank never disturbs the stream.

In short: not one global location you keep switching, but several exits alive at once, each used where it is needed.

What alle does

alle runs multiple VPN exits side by side. Each exit is exposed as its own local HTTP+SOCKS proxy on 127.0.0.1:<port>. A planned single HTTP+SOCKS entry point will route traffic by rule to a VPN exit or to direct outbound with no proxy. Instead of changing your whole machine's VPN location, you point each app, browser profile, script, or test job at the path it needs.

Under the hood, alle manages one sing-box process. Each channel becomes one local proxy inbound routed through one WireGuard VPN peer. Channels can come from different providers, so a NordVPN exit and a Proton VPN .conf import can run at the same time.

Current status

alle is usable today as a CLI-first client for per-app/per-workflow VPN exits.

Providers

Provider	Support
NordVPN	Token/API setup, location selection, automatic WireGuard channel creation
Proton VPN	WireGuard .conf import

Platforms

Platform	Support
macOS	Supported
Linux	Supported
Windows	Planned

Features

Phase	Status
Core CLI	Providers, channels, per-channel proxies, status, tests, logs, metrics
Routing	Planned
Web UI	Planned
Desktop companion	Planned
Distribution	PyPI CLI package; native installers planned

Install

alle requires Python 3.10 or newer.

With pip:

python -m pip install alle-proxy

With pipx:

pipx install alle-proxy

With uv as an installed tool:

uv tool install alle-proxy

Or run it directly with uvx:

uvx --from alle-proxy alle --help

After installation:

alle version
alle --help

Quick start

Add a provider, create a channel, start the runtime, then use the channel's local proxy port.

alle providers add nordvpn
alle channels add nordvpn --country "United States"
alle start
alle channels ls

alle channels ls prints the local proxy port for each channel:

PROVIDER  NAME             PORT    COUNTRY        CITY
--------  ---------------  ------  -------------  ----------
NordVPN   united_states_1  :53124  United States  (Any City)

Use that port from any tool or app that supports an HTTP or SOCKS proxy:

curl -x http://127.0.0.1:53124 https://api.ipify.org

Check health and traffic:

alle status
alle test
alle metrics

Provider setup

alle supports two provider setup styles today:

NordVPN uses an access token:

alle providers add nordvpn
alle locations nordvpn
alle locations nordvpn --country "United States"
alle channels add nordvpn --country "United States" --city "Seattle"

Proton VPN uses WireGuard config files downloaded from Proton:

alle providers add protonvpn
alle channels add protonvpn --config ~/Downloads/wg-US-CA-842.conf

Re-importing the same .conf file updates that channel in place, keeping the same channel id and local port.

Common commands

Useful commands after setup:

alle providers ls
alle channels ls
alle status
alle test
alle metrics
alle logs
alle stop

Most read commands support --json for scripts:

alle status --json
alle channels ls --json
alle metrics --json

For the complete command reference, see the CLI Reference.

Rule-based routing

To be implemented.

How it works

• alle keeps its local state under ~/.alle/, or under $ALLE_HOME when that environment variable is set. This includes providers, channels, credentials, metrics, generated config, logs, and runtime files.

• alle manages one sing-box process instead of starting one VPN process per channel. The generated config contains one local HTTP+SOCKS inbound per channel.

• Each channel routes to one WireGuard peer. NordVPN channels are created from the provider API; Proton VPN channels are created by importing a WireGuard .conf file. After creation, both behave the same way.

• WireGuard is connectionless, so alle does not model channels as connected or disconnected. A channel exists in config; its health comes from the latest probe.

• Local proxy ports are assigned by the OS and stored in state. Use alle channels ls to see the current ports.

• The background runtime applies state changes, keeps the sing-box process in sync, probes channel health, and records per-channel traffic totals.

• alle uses a pinned upstream sing-box release and verifies its checksum before running it.

Security and privacy

• Provider credentials and WireGuard private keys are stored locally under ~/.alle/ or $ALLE_HOME.
• Credential and state files are written with private file permissions where supported by the OS.
• alle does not read provider tokens from environment variables; credentials are added explicitly with alle providers add.
• alle downloads a pinned upstream sing-box release and verifies its checksum before running it.
• Local proxy ports bind to loopback. Traffic only uses a VPN exit when an app is pointed at one of those proxies.

Roadmap and non-goals

Planned next steps:

• Rule-based routing through a single local HTTP+SOCKS entry point.
• More WireGuard-capable VPN providers. See VPN Provider Research.
• Web UI for managing channels and routing rules.
• Desktop companion with OS-level VPN integration.
• Windows support and broader distribution.

Non-goals:

• OpenVPN or IKEv2/IPsec support.
• VPN providers without usable WireGuard support, such as ExpressVPN, HideMyAss, Perfect Privacy, Privado, SlickVPN, VPN.ac/VPNSecure, and Giganews.
• SOCKS5-only or unencrypted proxy providers.
• Bundling sing-box inside the Python package.

License

MIT