elide tun

elide tun puts a full WireGuard mesh network inside your runtime binary. It implements the Tailscale control protocol (TS2021 with Noise IK over ChaCha20-Poly1305), WireGuard encryption via boringtun, MagicDNS, STUN endpoint discovery, DISCO peer-to-peer NAT traversal, and a DERP relay server. No external tailscaled daemon required. No sidecar. One binary, one process.

Requires an Elide Pro license. See elide.pro for details.

Subcommands

SubcommandWhat it does
tun upAuthenticate with Tailscale, create a WireGuard tunnel, route traffic
tun downTear down the tunnel and remove routes
tun statusShow tunnel state, connected peers, and installed routes
tun derpRun a standalone DERP relay server for NAT traversal

Quick start

Bring up a tunnel

Authenticate with your tailnet and create a WireGuard tunnel in one command:

bash
 elide tun up --auth-key tskey-auth-k1234567890abcdef

Elide connects to the Tailscale coordination server via an encrypted Noise IK channel, fetches your network map, creates a TUN device (elide0), installs routes for all peers, and starts the WireGuard data plane. The process runs in the foreground until you press Ctrl+C or send SIGTERM.

Check tunnel status

bash
 elide tun status
 elide tun status --peers --routes

Tear down

Press Ctrl+C in the foreground process. The shutdown sequence stops the control thread, stops the data plane, and removes the TUN device (including the kernel interface and routes).

tun down is a convenience for stopping a daemonized tunnel. In the current release, tun up runs in the foreground and is stopped with Ctrl+C directly.

Run a DERP relay

Start a standalone relay for NAT traversal when direct peer-to-peer connections fail:

bash
 elide tun derp

This binds to 0.0.0.0:3340 and relays encrypted packets between Tailscale peers. The server generates a random X25519 keypair at startup and supports up to 65,536 concurrent connections by default. See the DERP reference for TLS, STUN, and mesh configuration.

---

How it works

When you run elide tun up, Elide performs this sequence:

1. Authenticate -- Connects to the Tailscale coordination server using TS2021. This involves fetching the server's Noise public key via GET /key, performing a Noise IK handshake (Noise_IK_25519_ChaChaPoly_BLAKE2s), and authenticating with your pre-auth key via a RegisterRequest. 2. Fetch network map -- Streams a MapRequest / MapResponse exchange to retrieve the full network map: peer list, DERP map, DNS configuration, and allowed IP ranges. 3. Install MagicDNS -- Populates the in-process DNS resolver with peer hostname-to-IP mappings extracted from the network map. Both FQDNs (e.g., my-server.tail1234.ts.net) and short names are registered. 4. Create TUN device -- Creates a kernel TUN device (elide0 by default on Linux), assigns your Tailscale IP addresses, and configures it for non-blocking I/O. 5. Install routes -- Runs ip route add dev (Linux) or route add -net -interface (macOS) for every peer's allowed IP ranges. 6. Start data plane -- Spawns the WireGuard data plane on a dedicated thread. In TUN mode, the data plane reads/writes raw IP packets from/to the TUN device and handles WireGuard encapsulation/decapsulation. 7. Background control -- Spawns a background thread that continuously polls the coordination server for map updates. MagicDNS entries refresh, WireGuard peer configurations recalculate, DISCO peer info is pushed to the data plane, and STUN endpoint discovery runs every 30 seconds. 8. Block -- Blocks until SIGINT or SIGTERM. On signal, the data plane is stopped, the TUN device is removed (along with the kernel interface), and the process exits cleanly.

Creating a TUN device requires root or the CAP_NET_ADMIN capability. On Linux, you can grant the capability without running as root: sudo setcap cap_net_admin+ep $(which elide).

---

Architecture

The data plane has two modes:

  • TUN mode -- Used by elide tun up. Raw IP packets flow through a kernel TUN device. The kernel handles TCP/IP, routing, and DNS. The data plane only does WireGuard encapsulation/decapsulation.
  • Netstack mode -- Used by elide orb --tailscale-direct. A userspace TCP/IP stack terminates connections inside the process, bridging them to the HTTP server via socketpairs.

Both modes share the same data plane implementation, the same WireGuard engine, and the same DISCO manager.

---

Platform support

PlatformTUN deviceDERP relayData planeStatus
Linux (x86_64, aarch64)elide0 (kernel TUN)Native async I/ONative async I/OFull support
macOS (aarch64)utun (auto-assigned)Native async I/ONative async I/OFull support
Cosmopolitan (portable)N/APoll-based I/OPoll-based I/ONetstack only (no kernel TUN)
WindowsNot yet implementedNot yet implementedPlannedPlanned
On Cosmopolitan builds, TUN device creation is not supported. Use the userspace netstack mode instead (e.g., elide orb —tailscale-direct).

---

Using with Headscale

Elide's tunnel is fully compatible with Headscale, the open-source Tailscale coordination server. Point --control-url at your Headscale instance:

bash
 elide tun up \
 --auth-key your-headscale-preauth-key \
 --control-url https://headscale.example.com

MagicDNS, DERP relay, peer discovery, and WireGuard encryption all work the same way. You will need to run your own DERP relay (elide tun derp) since Tailscale's public DERP servers require a Tailscale coordination server.

---

See also

  • tun up -- Full CLI reference for bringing up a WireGuard tunnel
  • tun derp -- Run a standalone DERP relay for NAT traversal
  • Tailscale integration -- Tailscale support in elide orb (--tailscale, --funnel, --tailscale-direct)