Compiled topology
FileConfig is validated and compiled before any listener opens. Unknown fields fail closed.
tcptunv0.5.0networking runtime
Programmable networking runtime
for applications and devices
tcptun compiles routing, tunnels, transports, and platform networking into one strict, observable runtime. Run it as a CLI, embed it in Go, or integrate it into Android VPN clients.
Run as CLI runtime, Android VPN client, embedded Go library, or platform networking engine.
tcptun · v0.5.0
$ curl -fsSL https://tcptun.com/install.sh | sh
$ npm install -g tcptun
$ tcptun --config config.json
$ tcptun config check --config config.json
# Go module
import "pkg.tcptun.com/net"What is tcptun?
A compiled networking runtime — not a protocol catalog.
tcptun loads a strict JSON topology, compiles outbounds and routes, prepares every inbound, then serves them together. The same engine powers the CLI, Go embeddings, and Android integrations. Protocol count is secondary; the model is primary.
- Programmable networking runtime — not a single-purpose proxy app
- Embeddable Go engine with net.Conn / PacketConn / Listener contracts
- Deterministic compile-before-serve routing model
- Native protocol architecture for controlled tcptun-to-tcptun deployments
- Platform integration surface for CLI, Android, and gateways
Choose your path
Run, embed, or integrate.
Run
CLI runtime
Install the binary, generate a strict JSON topology, validate, and serve inbounds together.
Continue →EmbedGo SDK
Import pkg.tcptun.com/net and compose dialers, listeners, packet devices, and routing in process.
Continue →IntegrateAndroid & platforms
Android client v0.5.1 embeds tcptun-go v0.5.0, matching the CLI core. VPN profiles require TLS or REALITY.
Continue →Core capabilities
What the runtime actually does.
Capability list after positioning — so new readers already know tcptun is an engine, not a single-purpose tunnel utility.
Multi-inbound / multi-outbound
One process hosts mixed proxies, tunnels, reverse publish, balance groups, and rule routing.
Native TCP/QUIC path
tcptun-to-tcptun Native protocol with mux, carrier.mode selection, and optional resumable streams.
Resource-bounded runtime
Mux pools, resume buffers, and packet paths are budgeted so long-lived services stay predictable.
Platform networking
TUN, DNS interception / fake-IP, and Android bridge hooks for device-level integration.
Local proxy authentication
mixed and socks5 hops with users[] and SOCKS5 secure auth v2 (HKDF method 0x80). Tunnel endpoints are native only.
Architecture
Validate → compile → serve.
FileConfig is decoded with unknown-field rejection, compiled into RuntimeConfig, then bound. Fail closed before traffic is accepted.
01FileConfig
Strict JSON topology
02Validate
Tags, refs, auth, caps
03RuntimeConfig
Compiled graph
04Serve
TCP · UDP · TUN · routes
Protocols
Native tunnels. Local mixed hops.
v0.5.0 tunnel endpoints are native only. mixed and socks5 remain for authenticated local/LAN proxy hops.
Native
tcptun Native protocol
Optimized for TCP/QUIC carriers, mux, resumable streams, reverse publishing, resource control, and tcptun-to-tcptun deployments.
Native guide →Local proxy
mixed / SOCKS5
Authenticated local listeners and LAN hops with users[] and SOCKS5 secure auth v2.
Config reference →Latest · v0.5.0
What shipped in this runtime.
Release notes stay technical: native-only tunnels, carrier.prefer, SOCKS5 secure auth v2, idle power-save probes, and mux stall recovery. Version lives here — not in the document title for SEO.
Native-only tunnel endpoints
v0.4.0+ tunnel endpoints are native only. mixed and socks5 remain for local/LAN proxy hops.
Auto TCP+QUIC with outbound preference
native + raw + mux can set carrier.mode=auto with TLS or REALITY. Outbound carrier.prefer is adaptive (default), quic, or tcp: strict preferences use the healthy preferred carrier and fall back only while it is unavailable.
SOCKS5 secure auth v2 and mixed users
Credentialed SOCKS5/mixed outbounds default to auth_mode=secure (HKDF method 0x80, no RFC1929 downgrade). Authenticated inbounds use a bounded users[] array across mixed, socks5, and native.
Idle power profile and mux stall recovery
A low-wakeup power profile parks idle QUIC probes on platform inbounds. Mux retires silently stalled carriers, backpressures elephant streams, and bounds local accept recovery independently of outbound backoff.
Authenticated home-network access
v0.5.0 can route IPv4/IPv6 TCP/UDP to a Home Connector, with optional Edge-assisted direct QUIC and relay fallback. Android does not expose Reverse Subnet / P2P in the product UI.
Security & trust
Source, install, and fail-closed defaults.
Inspect installers, verify package provenance, and read how the runtime validates config before binding ports.
One-line install
curl -fsSL https://tcptun.com/install.sh | sh