tcptun
v0.2.4proxy runtime

One config,
orchestrate all proxy traffic.

tcptun is a config-driven multi-inbound, multi-outbound proxy runtime. Describe inbounds, outbounds, and routes in strict JSON, then start TCP/UDP services together.

Start wizardDownload v0.2.4Generate config
One-line install
curl -fsSL https://tcptun.com/install.sh | sh
6inbound types
9outbound types
7platform builds
tcptun · v0.2.4
$ curl -fsSL https://tcptun.com/install.sh | sh

$ npm install -g tcptun

$ tcptun --config config.json

$ tcptun config check --config config.json

$ tcptun config native \
    --server proxy.example.com \
    --port 9443

What's new · v0.2.4

Mux stability, QUIC recovery, and quieter Android diagnostics.

v0.2.4 hardens native and Xray mux carrier lifecycle, improves QUIC path recovery, keeps native + raw + reality automatic dual carriers, and refreshes Android bridge logging and VMess interop.

Explore native + raw + reality
native + raw + reality01

QUIC-first automatic carriers

With group mux, security.type=reality binds TCP and UDP on one address, dials Reality QUIC first, falls back to Reality TCP with backoff, and probes to restore QUIC preference after recovery.

Mux & QUIC stability02

Healthier carrier lifecycle

v0.2.4 hardens native and Xray mux carrier retirement, stream isolation, and QUIC path recovery so unhealthy carriers fail closed without stranding active streams.

Continuity03

Resumable TCP logical streams

Opt-in mux.resume keeps an eligible TCP logical stream alive while its physical QUIC/TCP attachment is replaced, with bounded replay buffers, recovery timeouts, and a runtime-wide buffer budget.

Interop & Android04

VMess and bridge improvements

VMess body security tracks current Xray behavior. The Android bridge exposes dynamic log levels and core build identity for quieter, clearer diagnostics.

Capabilities

Config defines the topology; the runtime validates and runs it.

From inbound to outbound, one model covers local proxies, tunnels, rule routing, load balancing, and outbound chains.

Runtime01

Multi-inbound, multi-outbound

One config describes the full topology. Inbounds can pin an outbound or let route decide.

Config02

Strict JSON

address uses host:port arrays; unknown fields are rejected; tags, refs, auth, TLS, REALITY, and mux are validated before start.

Network03

Adaptive carriers and resumable TCP

Reality auto prefers QUIC and falls back to TCP; opt-in logical streams can resume across carrier replacement.

Reverse04

Reverse publish

native mux / QUIC supports publish and expose to hang NAT-side TCP/UDP services on edge ports.

Architecture

Inbounds, routes, and outbounds are explicit.

Every component has a unique tag; references are compiled and checked before start.

  1. Load
  2. Validate
  3. Compile
  4. Start

Inbounds

mixedsocks5nativevlessvmesstrojan
Routerules + default_outbound

Outbounds

directbalanceblackholesocks5mixednativevlessvmesstrojan
config.json
strict schema
{
  "log": { "level": "info" },
  "inbounds": [
    {
      "tag": "local",
      "type": "mixed",
      "address": ["127.0.0.1:1080"],
      "network": ["tcp", "udp"]
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "type": "native",
      "address": ["proxy.example.com:9443"],
      "token": "change-me",
      "transport": { "type": "raw" },
      "mux": {}
    }
  ],
  "route": { "default_outbound": "proxy", "rules": [] },
  "dns": {}
}

Protocols

Four tunnel protocols, one topology.

Xray compatibility is for wire protocols, not config file format.

All protocols
01

native

Token

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 9443
Native guide →
02

vless

UUID

Supports TCP/UDP. Generated configs default to Vision + REALITY and can interoperate with Xray.

tcptun config vless --server proxy.example.com --port 9443
Use cases →
03

vmess

UUID

VMess AEAD with TCP/UDP support and Xray interop.

tcptun config vmess --server proxy.example.com --port 9443
Use cases →
04

trojan

Password

Password-authenticated Trojan tunnel with TCP/UDP support.

tcptun config trojan --server proxy.example.com --port 9443
Use cases →

Explore

Jump into tools and docs.

Wizard01

Guided first tunnel

Step-by-step setup for native + raw + reality: install, generate, validate, run, and test.

Examples02

Copy-ready topologies

Worked server/client pairs for native auto Reality, resumable streams, reverse publish, VLESS, VMess, and Trojan.

Native guide03

Deep native tutorial

Concepts, fields, and long-form notes for the private tunnel protocol.

Chat04

Nearby chat & file share

Discover users on the same network and exchange messages, configs, and files privately.

tcptun v0.2.4

Download and run.

Download Linux x64