Noisemux/zeptun

A userspace network engine for TUN devices, written in Zig with no dependencies. It turns the packets an operating system routes into a tunnel interface back into TCP, UDP and ICMP flows, and forwards them through a SOCKS5 proxy, directly, or to the embedding application.

• IPv4 and IPv6, dual stack, fragment reassembly.
• TCP through a userspace terminator, through kernel NAT, or both at once.
• UDP with full-cone NAT by default, plus address and address-port modes.
• Segmentation offload in both directions: TSO, USO, UDP_SEGMENT and UDP_GRO, through SOCKS5 as well.
• Multi-queue TUN with elastic workers: queues are attached and detached under load, and live connections migrate between them without loss.
• SOCKS5 with a warm connection pool, pipelined handshakes, optimistic data, UDP ASSOCIATE and UDP over TCP.
• Fake-IP DNS, DNS hijacking, and DNS handover to systemd-resolved.
• Automatic routing: policy rules, prefix include and exclude lists, UID, interface and Android package rules, strict route, nftables auto-redirect.
• ICMP echo forwarding, ICMP time exceeded for expired packets, and upstream ICMP errors translated back to the client.
• The interface can live in its own network namespace while upstream sockets stay outside.
• io_uring or epoll on Linux, kqueue on BSD and macOS, IOCP on Windows.
• C ABI, TOML and JSON configuration, per-flow verdict callback.
• Linux, Android, Windows, macOS, iOS and FreeBSD.

Measured by the benchmark workflow on a GitHub-hosted runner, against four other engines over the same SOCKS5 server.

The second memory bar is read after the load stops: the packet pool hands idle pages back to the kernel instead of holding them for the life of the process.

Method, runner specification, latency, UDP, memory and the raw tables: docs/bench.

Zig 0.16.0 is the only requirement.

git clone https://github.com/Noisemux/zeptun
cd zeptun
make
sudo make install

make install places zeptun in /usr/local/bin, libzeptun.a and zeptun.h beside it, conf/zeptun.toml in /etc/zeptun if no configuration exists yet, and a systemd unit in /usr/local/lib/systemd/system.

ANDROID_NDK_HOME=/path/to/ndk sh scripts/build_android.sh

This builds libzeptun.so and libzeptun.a for armeabi-v7a, arm64-v8a, x86 and x86_64, then libzeptun-jni.so from src/jni/zeptun_jni.c. All load segments are aligned to 16 KB, as Android 15 and later require. Without the NDK the script stops after the Zig libraries.

sh scripts/make_xcframework.sh

This produces zig-out/Zeptun.xcframework with the iOS device, iOS simulator and macOS slices. Package.swift exposes it to SwiftPM.

zig build -Dtarget=x86_64-windows-gnu -Doptimize=ReleaseFast
make wintun

The tunnel uses Wintun, which is vendored in third-part/wintun with its licence and header, so no download is needed: make wintun copies the right wintun.dll next to the executable (WINTUN_ARCH=arm64 for arm64). The released Windows archives already contain it.

zig build -Doptimize=ReleaseFast

This writes zig-out/lib/libzeptun.a, the shared library and zig-out/include/zeptun.h. Other targets: make TARGET=aarch64-linux-musl, or zig build cross for the whole matrix.

preset = "desktop"
log_level = "warn"
stats_interval_s = 0

[tun]
name = "zeptun0"
mtu = 8500
queues = 0
address = ["172.19.0.1/30", "fdfe:dcba:9876::1/126"]

[stack]
mode = "userspace"
udp_nat = "endpoint_independent"
icmp = "auto"

[handler]
kind = "socks5"

[handler.socks5]
server = "127.0.0.1:1080"
udp_mode = "udp"
pool_size = 4

[route]
auto_route = true
exclude = ["192.168.0.0/16"]

[dns]
fake_ip = false
hijack = false
systemd_resolved = true

conf/zeptun.toml carries every key with its default. The same document is accepted as JSON. Unknown keys are rejected instead of ignored.

sudo zeptun run -c /etc/zeptun/zeptun.toml

Every key has a flag as well, so the file is optional:

sudo zeptun run --tun zeptun0 --mtu 8500 --socks5 127.0.0.1:1080 --auto-route

With --auto-route the engine installs the addresses, routes and policy rules itself and removes them when it stops, on Linux, macOS, FreeBSD and Windows. Upstream sockets carry a firewall mark, so proxy traffic never re-enters the tunnel. Without it nothing outside the interface is touched.

zeptun help lists every flag. The ones that matter most:

docker run --rm --device /dev/net/tun --cap-add NET_ADMIN --cap-add NET_RAW \
  -e SOCKS5_ADDR=172.17.0.1 -e SOCKS5_PORT=1080 ghcr.io/noisemux/zeptun

services:
  tun:
    image: ghcr.io/noisemux/zeptun
    cap_add:
      - NET_ADMIN
      - NET_RAW
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      TUN: zeptun0
      MTU: 8500
      IPV4: 172.19.0.1/30
      IPV6: fdfe:dcba:9876::1/126
      HANDLER: socks5
      SOCKS5_ADDR: a.b.c.d
      SOCKS5_PORT: 1080
      SOCKS5_USERNAME: user
      SOCKS5_PASSWORD: pass
      SOCKS5_UDP_MODE: udp
      AUTO_ROUTE: 1
      EXCLUDED_ROUTES: a.b.c.d/32
      LOG_LEVEL: warn

  client:
    image: alpine
    tty: true
    network_mode: "service:tun"
    depends_on:
      - tun

docker/entrypoint.sh turns the environment into /run/zeptun.toml. Set CONFIG to point at your own file instead, or pass arguments to run any subcommand.

#include <zeptun.h>

ZeptunConfig config;
zeptun_config_init(&config, ZEPTUN_PRESET_DESKTOP);
config.handler_kind = ZEPTUN_HANDLER_SOCKS5;
config.auto_route = 1;
snprintf(config.socks5_server, sizeof config.socks5_server, "127.0.0.1:1080");

Zeptun *tun = NULL;
if (zeptun_create(&config, &tun) != ZEPTUN_OK) return 1;
zeptun_start(tun);
...
zeptun_stop(tun);
zeptun_destroy(tun);

Callbacks run on worker threads and must not block. Every setter except zeptun_stop, zeptun_stats, zeptun_memory and the packet functions must be called before zeptun_start.

libzeptun-jni.so registers its methods on the class dev.zeptun.Zeptun:

package dev.zeptun

import android.net.VpnService

object Zeptun {
    external fun nativeStart(service: Any?, fd: Int, config: String?): Int
    external fun nativeStop()
    external fun nativeVersion(): String
    external fun nativeCounter(index: Int): Long

    init {
        System.loadLibrary("zeptun-jni")
    }
}

class ZeptunService : VpnService() {
    fun start(fd: Int, config: String) {
        val rc = Zeptun.nativeStart(this, fd, config)
        if (rc != 0) throw IllegalStateException("zeptun start failed: $rc")
    }

    override fun onDestroy() {
        Zeptun.nativeStop()
        super.onDestroy()
    }
}

nativeStart takes the descriptor from VpnService.Builder.establish() and an optional TOML document; null uses the mobile preset. The service object is held as a global reference and its protect(int) method is called for every upstream socket. Change ZEPTUN_JNI_CLASS in src/jni/zeptun_jni.c to register on another class.

import Zeptun

var config = ZeptunConfig()
zeptun_config_init(&config, UInt32(ZEPTUN_PRESET_MOBILE))
config.device_kind = UInt32(ZEPTUN_DEVICE_FD)
config.tun_fd = tunnelFileDescriptor

On iOS take the descriptor from NEPacketTunnelProvider, or use ZEPTUN_DEVICE_EXTERNAL with the packet callbacks to stay inside the NetworkExtension API.

Elastic queues start with a single worker and add a queue only while it raises throughput, then release it when the load drops. Connections and sessions move between workers without dropping a packet, so the idle footprint stays small on a busy machine.

Full documentation lives in the wiki: Building, Configuration, Command line, Routing, Stacks, C API, Android, Apple, Container, Benchmarks, Testing.

The integration suite covers every stack mode, both io backends, one and four queues, direct and SOCKS5, offloads on and off, UDP over TCP, fake-IP, strict routing, auto-redirect, elastic queue rotation under load, and the network namespace mode. The TCP simulation drives the real terminator against a model peer over lossy, reordering links and verifies every byte, leaving no buffers, timers or completions behind.

MIT