ghostwire 0.1.0

A local-first userspace mesh VPN: Noise-encrypted UDP tunnels, WireGuard-compatible config, zero servers required. Ships the Rust binary as a console script, ruff-style.

ghostwire

A local-first userspace mesh VPN you fully own.

ghostwire is a zero-server mesh VPN toolkit for building encrypted peer-to-peer tunnels from local config. It generates WireGuard-compatible Curve25519 keys, plans full-mesh node configs, exports wg-quick files, and includes a pure-UDP encrypted datapath that can be tested without admin privileges.

Why

• Own your tunnel: no control-plane SaaS, accounts, or hosted coordinator.
• WireGuard-compatible keys: Curve25519 keys encoded as standard base64, compatible with wg key material.
• Vetted crypto: the Noise Protocol Framework via the snow crate, not hand-rolled primitives.
• Local-first config: your mesh lives in a local ghostwire.toml.
• Single static binary workflow: generate, inspect, export, self-test, and bring up from one CLI.

How It Works

ghostwire speaks Noise_IK_25519_ChaChaPoly_BLAKE2s: Noise IK over Curve25519, ChaCha20-Poly1305, and BLAKE2s. The initiator already knows the responder's static public key, sends the first handshake datagram, and the responder replies with the second. After those two UDP datagrams, both peers have a Noise transport session.

The datapath is intentionally simple: one application packet is sealed as one Noise transport message and sent as one UDP datagram. All cryptography is delegated to snow.

Keys are 32-byte Curve25519 values rendered as standard base64, matching WireGuard's wg genkey / wg pubkey format. ghostwire can export wg-quick configs, including QR output for mobile import.

Real OS packet routing through TUN is optional and gated behind --features tun. That path needs admin/root privileges, and on Windows it requires wintun.dll. The pure-UDP crypto datapath works without privileges and is covered by ghostwire selftest.

Install

From this repository:

cargo install --path .

Or build a release binary:

cargo build --release

For real TUN routing:

cargo build --release --features tun

Quickstart

Verify the local encrypted datapath without needing a TUN device:

ghostwire selftest

Create a new local mesh config with three nodes:

ghostwire init --name home --subnet 10.42.0.0/24 --nodes laptop,vps,phone

Inspect the nodes, tunnel addresses, abbreviated public keys, endpoints, and which entries have local private keys:

ghostwire show

Export a WireGuard-compatible config for a node:

ghostwire export --node laptop

Export a QR code for mobile WireGuard import:

ghostwire export --node phone --qr        # scan into the WireGuard mobile app

Generate a fresh keypair:

ghostwire keygen

Security

ghostwire uses Noise_IK_25519_ChaChaPoly_BLAKE2s through the snow crate. That gives it Curve25519 static identity keys, ephemeral keys for forward secrecy during session setup, ChaCha20-Poly1305 transport encryption, and BLAKE2s hashing. The crate does not implement its own crypto primitives.

Private keys are not logged through Debug; key debug output is redacted to a short fingerprint. ghostwire.toml contains private keys for local nodes and is intentionally gitignored.

Status: early. Audit before trusting ghostwire with anything critical.

Roadmap

• Multi-peer demux with cookie/index handling like WireGuard.
• Roaming endpoints.
• Pre-shared symmetric key option.
• Windows service and systemd units.

License

MIT