nospoon

"There is no spoon." — The Matrix (1999)

A peer-to-peer VPN that eliminates the need for a publicly reachable server. Built on HyperDHT for NAT hole-punching and Noise-encrypted tunnels. No public IP, no port forwarding, no central infrastructure — just a key.

Install

sudo npm install -g nospoon

Requires Node.js 18+. Root/admin needed for TUN device creation.

Docker (Linux only)

docker build -t nospoon .
docker run --network=host --cap-add=NET_ADMIN --device /dev/net/tun \
  -v /path/to/config.jsonc:/etc/nospoon/config.jsonc \
  nospoon up

--network=host shares the host's network stack — the TUN device and routes are created on the host. Works on any Linux distro. Not supported on macOS (Docker runs in a VM).

Use Cases

1. Expose any service through NAT

Like HoleSail but at Layer 3 — instead of forwarding a single port, nospoon creates a full network interface. Every service on the server is reachable by IP, as if you were on the same LAN.

# Generate a client identity
nospoon genkey
# Output: Seed (keep secret): abc123...
#         Public key (share): def456...

Server config (/etc/nospoon/config.jsonc):

{
  "mode": "server",
  "peers": {
    "<client-public-key>": "10.0.0.2"
  }
}

Client config:

{
  "mode": "client",
  "server": "<server-public-key>",
  "seed": "<client-seed>",
  "ip": "10.0.0.2/24"
}

# Server (behind NAT, no port forwarding needed)
sudo nospoon up /etc/nospoon/config.jsonc

# Client (anywhere in the world)
sudo nospoon up client.jsonc

# Access anything on the server
curl http://10.0.0.1:8080       # web app
ssh user@10.0.0.1               # SSH
ping 10.0.0.1                   # ICMP

Using peers is recommended — it authenticates clients and assigns fixed IPs. Open mode (omitting peers) is available for quick testing but has no authentication and only supports a single client.

2. Full tunnel — access the internet from home

Route all your internet traffic through your home connection. When you're abroad, your traffic exits from your home IP — access geo-restricted content, use your home network's DNS, or just browse as if you were home.

Server config:

{
  "mode": "server",
  "fullTunnel": true,
  "peers": { "<client-key>": "10.0.0.2" }
}

Client config:

{
  "mode": "client",
  "server": "<server-key>",
  "seed": "<client-seed>",
  "fullTunnel": true
}

Kill switch included: if the tunnel drops, traffic fails instead of leaking.

Config Reference

nospoon uses JSONC config files (JSON with // comments). See config.example.jsonc for all options.

sudo nospoon up [config]     # default: /etc/nospoon/config.jsonc
nospoon genkey               # generate a key pair (no root needed)

Server config fields

Field	Default	Description
mode	—	"server" (required)
ip	10.0.0.1/24	TUN interface IP
ipv6	none	TUN IPv6 address
seed	random	64-char hex seed for deterministic key
seedFile	none	Read seed from file (mutually exclusive with seed)
mtu	1400	TUN MTU (576–65535)
fullTunnel	false	Enable NAT for client internet access
outInterface	auto	Outgoing interface for NAT
peers	none	Map of "<pubkey>": "<ip>" for auth mode

Client config fields

Field	Default	Description
mode	—	"client" (required)
server	—	Server public key, 64 hex chars (required)
ip	10.0.0.2/24	TUN interface IP
ipv6	none	TUN IPv6 address
seed	none	64-char hex client seed (for auth mode)
seedFile	none	Read seed from file (mutually exclusive with seed)
mtu	1400	TUN MTU (576–65535)
fullTunnel	false	Route all traffic through VPN

How It Works

1. Server announces its public key on the HyperDHT distributed hash table
2. Client looks up the key, HyperDHT performs UDP hole-punching through both NATs
3. A Noise-encrypted stream is established (X25519 + ChaCha20-Poly1305 + BLAKE2b)
4. IP packets flow through TUN devices on both sides, length-framed over the encrypted stream

All traffic is end-to-end encrypted. No data passes through the DHT — it's only used for peer discovery and hole-punching. In authenticated mode, unauthorized peers are rejected during the Noise handshake before a connection is established.

Platforms

Platform	Status
Linux	Stable (x86_64, aarch64)
macOS	Stable (Apple Silicon, Intel)
Windows	Stable (x64, arm64) — via Wintun
Android	Stable (Kotlin VpnService + Bare worklet)
Docker	Stable (any Linux distro, --network=host)
NixOS	Module: services.nospoon

Windows

Requires an Administrator terminal. nospoon uses Wintun v0.14.1 (bundled) to create the TUN adapter — no separate driver install needed.

# Run as Administrator
nospoon up config.jsonc

Default config path: %PROGRAMDATA%\nospoon\config.jsonc

Full-tunnel mode works (IPv4 + IPv6 leak prevention). The Wintun prebuilt DLLs are distributed under a permissive license by WireGuard LLC.

Limitations

• Symmetric NAT — both peers behind symmetric NAT may fail to connect
• DNS in full-tunnel mode — DNS is automatically switched to 1.1.1.1 / 8.8.8.8 when full-tunnel is active. Custom DNS servers are not yet configurable.

License

GPL-3.0 — See LICENSE

Credits

• HyperDHT — DHT and hole-punching
• koffi — FFI for TUN device creation
• Wintun — Windows TUN driver by WireGuard LLC
• Noise Protocol — Encryption framework
• HoleSail — The original Layer 4 project