tcptunNative protocol
Private, low-overhead tunneling for tcptun-to-tcptun setups with mux, QUIC-first REALITY auto carriers, resumable TCP, and reverse publish.
Native protocol
native is tcptun’s private tunnel protocol for tcptun-to-tcptun deployments. One JSON topology describes server and client; the runtime validates auth, transport, security, mux, and reverse publish before listening.
Private low-overhead protocol. raw + group mux + reality automatically prefers QUIC and falls back to TCP; resumable streams can preserve eligible TCP flows across carrier replacement.
tcptun config native --server proxy.example.com --port 9443A token-authenticated tunnel that carries TCP and UDP. The server exposes a native inbound; the client usually listens as mixed/socks5 locally and forwards through a native outbound.
Use native when both ends run tcptun and you want low overhead, mux, automatic QUIC/TCP REALITY, resumable TCP streams, forced QUIC, or reverse publish of services behind NAT.
Match users[].id with token, set address as host:port arrays, choose transport (prefer raw), optional security, and optional mux. Everything else is ordinary tcptun route / inbound / outbound wiring.
Keep these rules in mind when reading or writing native configs.
Typical path: app → local mixed :1080 → native outbound → internet → native :9443 → direct. Server and client are two configs that share credentials and security parameters.
Server inbound users[].id must equal client outbound token. Generate long random tokens; never reuse example values like change-me in production.
address is always a string array of host:port. Multiple outbound addresses race as candidate entry points for the same logical service; they are not load balancing (use balance for that).
raw is the default and best for throughput. ws / h2 / h3 are available when you need path-based fronting; QUIC mode requires raw.
With native + raw + group mux, security.type=reality is the automatic dual-carrier mode: QUIC first, Reality TCP fallback, shared keys/SNI/dest. reality-tcp forces TCP; reality-quic + mux.mode=quic forces QUIC without fallback. TLS still needs cert/key on the server.
Presence of mux enables multiplexing. Group mode unlocks automatic Reality carriers and optional mux.resume for TCP continuity; mux.mode=quic is the separate forced QUIC pool (not the auto path).
Follow these steps for a first working native tunnel. The browser generator and URI tools on this page can replace the CLI generate / export steps if you prefer.
Install a binary for your platform, or use the one-line installer / npm package.
curl -fsSL https://tcptun.com/install.sh | sh
tcptun --versionCreate matching server.json and client.json with REALITY keys and a shared token. Prefer the CLI on the server host, or use the browser generator on this site.
tcptun config native --server proxy.example.com --port 9443 --server-name example.com --dest example.com:443
# writes server.json and client.json in the current directory (CLI defaults may vary by version flags)On the server config, set the native inbound listen address (for example 0.0.0.0:9443). On the client, set the outbound address to the public host:port, and keep token identical to users[].id.
# server inbound address → where this machine listens
# client outbound address → public host:port clients dial
# users[].id === tokenconfig check compiles the topology without opening ports. Fix any missing keys, bad tags, or REALITY mismatches here.
tcptun config check --config server.json
tcptun config check --config client.jsonBring the edge up first. Then start the client so the local mixed proxy can dial the tunnel.
tcptun --config server.json
tcptun --config client.jsonWith the client running, apps should use the local mixed inbound (default 127.0.0.1:1080). Verify with a tool that supports SOCKS5 or HTTP depending on your mixed settings.
curl -x socks5h://127.0.0.1:1080 https://example.com -I
# or point your system / app proxy to 127.0.0.1:1080Use cases
Complete server / client pairs for native, VLESS, VMess, and Trojan. Copy a pair, replace placeholders, validate, then start the server before the client.
native
tcptun-to-tcptun tunnel with raw + mux for throughput.
When: Both ends run tcptun and you want low overhead.
tcptun config native --server proxy.example.com --port 9443
tcptun config check --config server.json
tcptun --config server.json
tcptun --config client.json{
"log": { "level": "info" },
"inbounds": [
{
"tag": "server",
"type": "native",
"address": ["0.0.0.0:9443"],
"network": ["tcp", "udp"],
"users": [{ "id": "change-me" }],
"transport": { "type": "raw" },
"mux": {}
}
],
"outbounds": [
{ "tag": "direct", "type": "direct" }
],
"route": { "default_outbound": "direct", "rules": [] },
"dns": {}
}