Quick Start

Five minutes from download to a program running 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 WebAssembly modules in a sandbox. Observers watch a run, Advisors read traces, Guards can refuse what the policy allowed. The plugin guide shows how to write one.

Next

  • Every command, option, rule and event: Reference
  • What the core and plugins do, and what was measured: The Platform
  • What comes next: Roadmap