Metadata-Version: 2.5
Name: anyhop
Version: 0.1.18
Summary: A universal VPN client that manages multiple VPN connections with rule-based routing.
Project-URL: Homepage, https://github.com/anyhop/anyhop
Project-URL: Issues, https://github.com/anyhop/anyhop/issues
Author: zydo
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Keywords: gateway,nordvpn,proxy,sing-box,vpn,wireguard
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Requires-Dist: packaging>=23.2
Requires-Dist: pycountry>=23.12
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/wordmark-dark.svg">
    <img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/wordmark.svg" alt="anyhop" width="320">
  </picture>
</p>

<p align="center">
  <a href="https://github.com/anyhop/anyhop/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/anyhop/anyhop/ci.yml?branch=main&amp;label=CI" alt="CI"></a>
  <a href="https://pypi.org/project/anyhop/"><img src="https://img.shields.io/pypi/v/anyhop.svg?label=PyPI" alt="PyPI"></a>
  <a href="https://github.com/anyhop/homebrew-tap"><img src="https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2Fanyhop%2Fhomebrew-tap%2Fmain%2FFormula%2Fanyhop.rb&amp;search=anyhop-(%5B0-9.%5D%2B)%5C.tar&amp;replace=v%241&amp;label=Homebrew" alt="Homebrew"></a>
  <a href="https://github.com/anyhop/anyhop/pkgs/container/anyhop"><img src="https://img.shields.io/badge/ghcr.io-anyhop%2Fanyhop-2496ED?logo=docker&amp;logoColor=white" alt="Container image"></a>
</p>

# anyhop

A universal VPN client that manages multiple VPN connections with rule-based routing, with interfaces for human (Web UI and CLI) and programs (REST API and Docker image).

## Platforms

### Supported

<table>
  <tr>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/platforms/docker.svg" alt="" height="56"><br>Docker</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/platforms/terminal.svg" alt="" height="56"><br>CLI</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/platforms/browser.svg" alt="" height="56"><br>Web UI</td>
  </tr>
</table>

### Planned

<table>
  <tr>
    <td align="center" width="150">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/platforms/apple-dark.svg">
        <img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/platforms/apple.svg" alt="" height="56">
      </picture>
      <br>macOS
    </td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/platforms/tux.svg" alt="" height="56"><br>Linux</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/platforms/windows.svg" alt="" height="56"><br>Windows</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/platforms/openwrt.svg" alt="" height="56"><br>OpenWrt&nbsp;(LuCI)</td>
  </tr>
</table>

## VPN Providers

### Supported

<table>
  <tr>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/nordvpn.png" alt="" height="56"><br>NordVPN</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/protonvpn.png" alt="" height="56"><br>Proton VPN</td>
  </tr>
</table>

### Planned

<table>
  <tr>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/expressvpn.png" alt="" height="56"><br>ExpressVPN</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/surfshark.png" alt="" height="56"><br>Surfshark</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/cyberghost.png" alt="" height="56"><br>CyberGhost</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/pia.png" alt="" height="56"><br>PIA</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/windscribe.png" alt="" height="56"><br>Windscribe</td>
  </tr>
  <tr>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/ipvanish.png" alt="" height="56"><br>IPVanish</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/mullvad.png" alt="" height="56"><br>Mullvad</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/purevpn.png" alt="" height="56"><br>PureVPN</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/vyprvpn.png" alt="" height="56"><br>VyprVPN</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/hidemyass.png" alt="" height="56"><br>HideMyAss</td>
  </tr>
  <tr>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/vpnunlimited.png" alt="" height="56"><br>VPN&nbsp;Unlimited</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/privadovpn.png" alt="" height="56"><br>PrivadoVPN</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/torguard.png" alt="" height="56"><br>TorGuard</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/privatevpn.png" alt="" height="56"><br>PrivateVPN</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/fastestvpn.png" alt="" height="56"><br>FastestVPN</td>
  </tr>
  <tr>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/ivpn.png" alt="" height="56"><br>IVPN</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/airvpn.png" alt="" height="56"><br>AirVPN</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/vpnac.png" alt="" height="56"><br>VPN.ac</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/vpnsecure.png" alt="" height="56"><br>VPNSecure.me</td>
    <td align="center" width="150"><img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/providers/slickvpn.png" alt="" height="56"><br>SlickVPN</td>
  </tr>
</table>

See [VPN provider research](docs/vpn-provider-research.md) for setup archetypes,
provider-specific constraints, and excluded providers.

<p align="center">
  <img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/webui.png" alt="anyhop Web UI dashboard" width="900">
  <br>
  <em>Web UI</em>
</p>

## Why anyhop

### For people

You already pay for a commercial VPN — but its official client connects to one
location at a time. Switching countries means disconnecting, reconnecting, and
breaking whatever was using the old exit. Two locations at once is not on offer.

`anyhop` keeps several exits live simultaneously, from one provider or mixed across
providers. Different traffic leaves through different VPN servers, decided by
anyhop's routing rules:

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/why-anyhop-dark.svg">
    <img src="https://raw.githubusercontent.com/anyhop/anyhop/main/src/anyhop/assets/readme/why-anyhop.svg" alt="Three apps routed through anyhop to three different VPN exits at the same time" width="700">
  </picture>
</p>

### For programs

Every action the CLI performs is also a REST call, and each exit is a stable
`127.0.0.1:<port>` proxy. So another program can drive the whole lifecycle of
many VPN connections — create, probe, rotate, retire — on its own schedule,
with no human clicking a client. That is what makes proxy rotation across
regions, and reaching geofenced resources from wherever they are served,
something you can script.

It also ships as a container image ([`ghcr.io/anyhop/anyhop`](https://github.com/anyhop/anyhop/pkgs/container/anyhop))
so a compose stack can add it as one service and let sibling containers reach
the internet through whichever exit the rules pick.

You may also have heard of [gluetun](https://github.com/qdm12/gluetun) or
[vopono](https://github.com/jamesmcm/vopono) — [anyhop and
gluetun](docs/gluetun-comparison.md) and [anyhop and
vopono](docs/vopono-comparison.md) compare anyhop to each.

## What anyhop does

`anyhop` runs multiple VPN exits side by side, each its own local HTTP+SOCKS
proxy. One router entrypoint sends traffic by rule to an exit, straight out, or
nowhere at all — see [Rule-based routing](docs/routing.md). For a whole-machine
VPN through those same rules there is an optional **TUN mode** (`anyhop tun on`,
one-time privilege grant): [CLI reference](docs/cli-reference.md#anyhop-tun-onoff),
[runbook](docs/tun-runbook.md).

The runtime model — one `sing-box` process, state, ports, probes — is in
[How it works](docs/how-it-works.md). What is supported today is in
[Current status](docs/status.md).

## For AI Coding Agents

**[anyhop for agents](docs/for-agents.md)** — copy-paste to your coding agent to
teach them how to use anyhop. It carries the model, the facts that change how the
code is written, and links it can fetch on demand.

## Quick Start

For macOS + Linux: installs anyhop and its user-level login service

```bash
curl -LsSf https://github.com/anyhop/anyhop/releases/latest/download/install.sh | sh
```

Then add a VPN provider (use NordVPN as example) and create a connection ("channel").

```bash
anyhop providers add nordvpn      # will ask you for NordVPN token
anyhop channels add nordvpn --country "United States"
anyhop start
anyhop channels ls                # prints each channel's local proxy port
```

Homebrew, `uv`, `pipx`, Docker, the checksum-verified manual install, and the
uninstaller are all in **[Getting started](docs/getting-started.md)**; container
deployments are in **[Docker](docs/docker.md)**.

## Documentation

### Using anyhop

- **[Getting started](docs/getting-started.md)** — install, quick start,
  provider setup, everyday commands, channel enable/disable.
- **[Rule-based routing](docs/routing.md)** — the router entrypoint: rulesets,
  first-match priority, kill-switch, built-in LAN bypass.
- **[Web UI](docs/web-ui.md)** — the browser dashboard (`anyhop ui`): pages,
  sign-in, remote access over SSH.
- **[CLI reference](docs/cli-reference.md)** — every command, flag, and
  environment variable.

### Automating anyhop

- **[anyhop for agents](docs/for-agents.md)** — the entry point to hand a coding
  agent: model, minimal call set, failure modes, progressive links.
- **[REST API](docs/api.md)** — the `/api/v1` contract: everything the CLI can
  do, over HTTP with Bearer auth. Loopback by default; opt-in network exposure
  for compose siblings. Machine-readable spec:
  [openapi.yaml](docs/openapi.yaml).
- **[Declarative setup](docs/declarative-config.md)** and the
  **[bundle format](docs/bundle.md)** — the whole setup (providers, channels,
  rules) as one YAML file: backup/restore, startup config, secret indirection.

### Deploying anyhop

- **[Docker](docs/docker.md)** — image design, proxy hub, VPN gateway
  container (tun), trust boundaries.
- **[Docker Compose walkthrough](docs/docker-compose.md)** — bundle authoring,
  secrets, managing anyhop from a sibling container, day-2 operations,
  troubleshooting.
- **[TUN runbook](docs/tun-runbook.md)** — whole-machine capture: privilege
  models per platform, verification, rollback.

### Understanding anyhop

- **[How it works](docs/how-it-works.md)** — the runtime model: one sing-box,
  state, ports, probes.
- **[Current status](docs/status.md)** — supported providers and platforms,
  feature matrix, what is planned, and the non-goals.
- **[Security model](docs/security.md)** — trust boundaries, credential
  handling, Web UI/API hardening, fail-closed routing.
- **[VPN provider research](docs/vpn-provider-research.md)** — which providers
  can be supported next, and why some can't.
- **[anyhop and gluetun](docs/gluetun-comparison.md)** — how the two differ, and
  how to choose between them.
- **[anyhop and vopono](docs/vopono-comparison.md)** — request-level routing vs.
  per-process network-namespace isolation.

## Security and privacy

See the **[Security model](docs/security.md)**.

## License

MIT
