Quick Start

Five minutes from download to a program running on VPN Works under its own policy. This uses Linux, where vpnw can seal a program in. On a Mac the same commands work for programs that honor proxy settings.

1. Install

curl -LO https://github.com/VPNWorks/vpnw/releases/latest/download/vpnw_linux_amd64.tar.gz
tar -xzf vpnw_linux_amd64.tar.gz ./vpnw
sudo mv vpnw /usr/local/bin/
vpnw doctor

vpnw doctor says whether this machine can run sealed programs. Most distributions can. On Ubuntu 23.10 and later, AppArmor stops unprivileged user namespaces; doctor says so, and you can run vpnw with sudo or allow them. Other systems and checksums are on the download page.

2. Watch what a program does

vpnw trace -- ./my-agent

Every connection prints as it happens: what the program asked for, what it resolved to, whether it opened, how much went each way. Nothing is blocked yet. The trace is saved, so the next step can read it.

3. Draft a policy from that run

vpnw learn --name my-agent -o my-agent.toml

Learn turns the trace into a policy that allows exactly what the program reached and denies everything else. Read it before you use it. It allows whatever the program did, including anything it shouldn’t have, and it flags raw IP addresses, uploads much bigger than the downloads, and destinations on the private network.

A policy is a short file:

version = 1
name = "my-agent"

[policy]
default = "deny"
deny_private = true
allow = ["api.github.com", "*.githubusercontent.com", "pypi.org:443"]

4. Enforce it

vpnw guard --policy my-agent.toml -- ./my-agent

Now anything off the list is refused, and the console says which rule refused it. If a connection was denied and the program still exits with 0, vpnw exits with 120, so a CI job notices.

5. Choose the way out

Straight out is the default. To send this program, and only this program, through a WireGuard tunnel, give vpnw the config file your VPN provider or wg hands out:

vpnw guard --policy my-agent.toml --wireguard office.conf -- ./my-agent

vpnw runs the tunnel itself: no root, no network interface, nothing changes for the rest of the machine. Names are looked up through the tunnel. If the tunnel doesn’t come up, the program never starts.

A proxy works the same way:

vpnw run --proxy socks5h://127.0.0.1:1080 -- ./scraper

6. Add a plugin

vpnw plugin list
vpnw plugin add ./geo-fence
vpnw guard --policy my-agent.toml --plugin geo-fence -- ./my-agent

Plugins are the apps of VPN Works: WebAssembly modules in a sandbox. Observers watch a run, Advisors read traces, Guards can refuse what the policy allowed, and Tunnels hand the kernel WireGuard configs. Plugins lists them and shows how to write one.

7. Keep a record nobody can quietly edit

vpnw guard --policy my-agent.toml --plugin ledger -- ./my-agent
vpnw verify ~/.local/state/vpnw/ledger/r-3f9a1c.ledger

The built-in Ledger plugin seals every event of the run as it happens and prints where the ledger is, with its last hash. Keep that hash somewhere else. vpnw verify says intact, or names the line someone changed. Ledger

8. Leave from a fixed address

On a server with fixed addresses, make a certificate and a token for each client, and list the clients in the exit’s file, each with its token’s hash, its address and its policy:

vpnw exit cert --host 198.51.100.2 --name exit-de
vpnw exit token --out agent-1.token
vpnw exit serve --config exit-de.toml

On your machine, with the exit’s ca.pem and the token copied over:

vpnw guard --policy my-agent.toml --proxy https://198.51.100.2:8443 \
  --ca ca.pem --token-file agent-1.token -- ./my-agent

The exit decides every request again with that client’s own policy, and connects from the client’s address. Exit

9. Rotate through WireGuard configs

Put the .conf files your VPN provider hands out in a folder, and let the built-in rotate plugin hand them to vpnw:

mkdir -p ~/.config/vpnw/rotate && cp se-*.conf ~/.config/vpnw/rotate/
vpnw guard --policy my-agent.toml --tunnel rotate --set rotate.every=10m -- ./my-agent

Every 10 minutes vpnw brings the next config’s tunnel up, then moves new connections to it; open ones finish where they started. When a tunnel stops answering for 20 seconds, vpnw moves on to the next config, and nothing ever goes around the tunnels. Rotate in 0.8.0

Every command, option, rule and event: Reference
How VPN Works is built, layer by layer, and what was measured: The Platform
The plugins, and how to write one: Plugins
What comes next: Roadmap