See It Run

Two minutes on your own Linux machine shows more than a replay in a browser could. The browser demos that used to live here replayed recordings from the old separate engines. When VPN Works became one core with plugins, they went, and this is what replaced them: a few commands you can run yourself.

VPN Works 0.4.0: WebAssembly plugins (Observer, Advisor, Guard) above one small core (sealed sandbox, policy, broker, record) with its paths

1. A program that ignores the rules

Get vpnw from the download page, then try to reach the internet without going through it:

vpnw run -- python3 -c "import socket; socket.create_connection(('1.1.1.1', 443), 3)"

It fails with Network is unreachable. The sealed sandbox has nothing in it but loopback, so a program that ignores proxy settings has no route out at all. The project’s tests try 17 ways around vpnw like this one, from raw sockets to io_uring and IPv6, and all 17 are blocked.

2. Watch, learn, enforce

vpnw trace -- curl -s https://example.com -o /dev/null
vpnw learn --name curl -o curl.toml
vpnw guard --policy curl.toml -- curl -s https://example.org -o /dev/null

The trace prints the connection as it happens. Learn turns it into a policy that allows example.com and nothing else. Guard enforces it: example.org is refused before a single byte goes out, and the console names the rule that refused it.

3. Through a WireGuard tunnel

If you have a WireGuard config from a VPN provider or your own server:

vpnw trace --wireguard wg0.conf -- curl -s https://ifconfig.me

curl prints the tunnel’s exit address, and the trace shows the lookup and the connection going through the tunnel. Nothing changed on your machine, and nothing needed root. Try it with a wrong key and the run stops before curl starts.

4. A plugin

vpnw plugin list
vpnw plugin info trace

The console you’ve been reading is a plugin: Trace, an Observer that runs in a WebAssembly sandbox inside vpnw. Learn is an Advisor plugin. The plugin guide shows how to write your own.

The Old Demos

The five browser demos replayed recorded runs of VPN Works 0.2.0: the Agent, Scope, Lab, Ledger and Exit. Their code is still in the repository’s history, at the v0.2.0 tag. What became of each engine is on its page: Scope, Lab, Ledger, Exit.