Frequently asked questions

No. tcptun uses its own JSON topology. Tunnel endpoints are native; mixed and socks5 are for local/LAN proxy hops.

native is tcptun’s private tunnel protocol for tcptun-to-tcptun setups. A typical path is local mixed → native outbound → native inbound → direct, with matching users[].id and token. See the Native guide for a full tutorial and examples.

Install tcptun, run tcptun config native --server <host> --port <port>, edit the generated server/client endpoints and token, validate with tcptun config check, start the server then the client, and point apps at 127.0.0.1:1080.

Use native for throughput, mux, QUIC, reverse publish, and Reality/TLS carriers. mixed and socks5 remain for local/LAN proxy hops.

Run tcptun config check --config config.json. It validates and compiles without listening on ports.

It installs to /usr/local/bin by default. Use TCPTUN_INSTALL_DIR to change the directory and TCPTUN_VERSION to pin a version. The installer downloads platform binaries from the published npm package (cdn.jsdelivr.net/npm/tcptun).

macOS, Linux, and Windows on amd64 / arm64 (Linux also includes armv7). Prefer npm install -g tcptun or the one-line installer for CLI builds.

Server users[].id and client token must match. Use tcptun config native to generate a paired config.

It is the automatic dual-carrier stack: type=native, transport raw, mux enabled, security.type=reality, and carrier.mode=auto. The server binds TCP and UDP on one address; the client prefers Reality QUIC, falls back to Reality TCP with backoff, and probes to restore QUIC. Camouflage keys/SNI/dest are shared by both carriers. Without mux, Reality stays TCP-only.

carrier.mode=auto (default generators) binds TCP and UDP on one address 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. mode=tcp or mode=quic is a single carrier. Mux must be enabled for auto and quic.

For many short connections, prefer mux.enabled. In v0.3.0, native + raw + mux + reality with carrier.mode=auto prefers QUIC and falls back to Reality TCP. Use carrier.mode=tcp to force TCP, or carrier.mode=quic to force QUIC without fallback.

Set mux.resume=true on both native endpoints using raw + mux + security.type=reality + carrier.mode=auto. A TCP logical stream can reattach after its physical QUIC/TCP carrier fails. It does not cover UDP, reverse publish, forced tcp/quic-only modes, or cross-process failover; keep it off during rolling upgrades until both peers run v0.3.0 or newer.

A native raw TCP inbound with security.type=none can set fallback.type=tls_passthrough to forward ordinary HTTPS probes (matching SNI) to a fixed dest while authenticating native mux traffic. It is inbound-only camouflage, not REALITY, and does not encrypt the native payload.

With security.type=none and client_hello.type=ech, the tunnel can hide only the SNI of a carried TLS 1.3 ClientHello (tcptun config native --ech). Later application bytes stay on the security-none path; this is not full application ECH to the destination site.

No. REALITY works only with raw and cannot be combined with security.type=tls.

Both inbound and outbound address values are host:port string arrays. Multiple addresses are candidate entry points for the same logical service and race on first handshake; they are not balance load balancing.

native + raw + mux (group or QUIC) can publish NAT-side TCP/UDP services to the server: configure publish on the server and expose on the client, with matching service names.

Keys and credentials are generated locally with Web Crypto and never uploaded. You can also use the CLI: tcptun config <protocol> --server ….

Rebuild the path as native (or keep mixed/socks5 for local hops). tcptun does not load Xray JSON or other vendors’ share links as tunnel endpoints.

tcptun never searches the current directory for server.json, client.json, or config.json. Without --config it reserves 127.0.0.1:1080, scans private IPv4 LAN peers for SOCKS5:1080, then starts a mixed proxy after the first successful handshake. --retry keeps the listener and retries discovery; it cannot be combined with --config.

Use a balance outbound to group members with weights and affinity_ttl. Multiple addresses on one outbound only race as candidate entry points; they are not load balancing. The embeddable Runtime and Android bridge also support start/stop, probing, and atomic switches of declared outbounds.

The Android client v0.5.1 embeds tcptun-go v0.5.0 (Bridge API 3), matching the CLI core. Pair tunnel peers on v0.5.0. Android VPN profiles require TLS or REALITY and use Full Tunnel only; Reverse Subnet / P2P is a CLI/server capability and is not exposed in the app.