Config

JSON topology, native, and REALITY.

Describe inbounds, outbounds, and security in one strict config. Focus on native + raw + reality automatic carriers, resumable streams, and field reference.

Worked examples Generate pair Native guide

Config

JSON topology, native, and REALITY.

Describe inbounds, outbounds, and security in one config. Start with native, then REALITY and protocol choice.

native Reality auto Resumable reality-quic Reverse publish REALITY Generate Compare

v0.2.4 · native + raw + reality

`native + raw + reality + group mux`

This is the recommended automatic stack in v0.2.4: one listen address, dual Reality carriers, QUIC preferred, TCP fallback, and optional resumable TCP streams. Without mux, ordinary native / VLESS / VMess / Trojan REALITY remains TCP-only.

Default pathQUIC-first Reality auto

Force TCP with reality-tcp, or force QUIC with reality-quic + mux.mode=quic.

Protocolnative

Token auth, TCP/UDP tunnel semantics, reverse publish, and resumable logical streams.

Transportraw

Required base transport for automatic dual carriers. Do not stack ws / h2 / h3 in this mode.

Securityreality

Automatic mode: QUIC-first Reality with TCP fallback on one address (not the forced reality-quic stack).

Multiplexingmux (group)

Group mux enables the dual-carrier path. Optional mux.resume preserves eligible TCP flows across carrier replacement.

Automatic · v0.2.4

reality + group mux

Binds TCP and UDP on one address, prefers QUIC, falls back to Reality TCP with backoff, and probes to restore QUIC preference.

Forced TCP

reality-tcp

Uses only the Reality TCP carrier. Choose this when UDP is intentionally unavailable or deterministic TCP-only behavior is required.

Forced QUIC

reality-quic + quic mux

Uses the dedicated QUIC pool without TCP fallback. The server listen port must be reachable over UDP.

Required stack

Automatic dual carriers need all of: type=native, transport.type=raw, mux present (group mode), and security.type=reality. Missing mux keeps ordinary TCP-only Reality.

One address, two sockets

The inbound binds TCP and UDP to the same host:port. Clients race the same address over both carriers without a second listen entry.

QUIC first, TCP fallback

Outbounds prefer the Reality QUIC carrier. When UDP is blocked or unhealthy, they fall back to Reality TCP with jittered exponential backoff, then probe to restore QUIC preference.

Shared camouflage

Both carriers share the same REALITY keys, short IDs, SNI, and dest. The camouflage destination should support HTTPS over TCP and HTTP/3 over UDP.

Scope of selection

TCP streams, UDP relay, and reverse carriers follow the same automatic carrier policy when the stack is Reality-auto.

Escape hatches

security.type=reality-tcp forces TCP only. security.type=reality-quic with mux.mode=quic forces the dedicated QUIC pool and never falls back to TCP.

Generate the automatic pair

CLI and the browser generator emit this stack by default for native: security.type=reality plus group mux. Enable resumable streams with mux.resume=true on both ends.

tcptun config native --server proxy.example.com --port 9443 --server-name example.com --dest example.com:443

Structure

Top-level fields include log, resources, inbounds, outbounds, route, and dns. Unknown fields are rejected; resources.resumable_buffer_budget controls the shared replay-buffer budget.

Address

inbound.address and outbound.address are both host:port arrays. Multiple addresses race as candidate entry points; use balance for independent nodes.

References

Components link through tags; via chains and balance members are checked for missing refs and cycles.

Startup

Load → Validate → Compile → Start. Listening begins only after validation succeeds.

Native

Low-overhead private tunnel

Supports TCP / UDP and mux, with transport options raw / ws / h2 / h3. Server users[].id and client token must match.

Server inboundusers[].id

Client outboundtoken

Auth

Server users[].id and client token must match.

Address

address is a host:port array. Multiple addresses race as candidate entry points for the same service; they are not balance.

v0.2.4 Reality auto

native + raw + group mux + security.type=reality prefers QUIC, falls back to TCP, and shares one camouflage identity on both carriers.

Resumable TCP

mux.resume=true on both Reality-auto peers can preserve an eligible TCP logical stream across carrier replacement (v0.2.4+).

Throughput

Prefer native + raw + mux. Forced TLS / REALITY / ws / h2 / h3 add flexibility but cost more.

Reverse publish

Server publish + client expose can hang NAT-side TCP/UDP services on edge listeners (requires mux).

Native QUIC

`native + raw + reality-quic`

This is not three interchangeable modes, but one layered stack: native is the tunnel protocol, raw is the transport, and reality-quic is the QUIC-only security layer. You must also set mux.mode=quic to enable the native QUIC connection pool.

Best fortcptun on both ends

Carry TCP streams and UDP DATAGRAMs together without managing TLS certificates.

Protocolnative

Handles token auth, TCP / UDP tunnel semantics, and reverse publish.

Transportraw

Required base transport for QUIC mode; do not stack ws / h2 / h3.

Securityreality-quic

Protects the QUIC handshake with REALITY keys and site parameters; no cert deploy needed.

Multiplexingmux.mode: quic

Uses a QUIC connection pool for streams and UDP DATAGRAMs.

Both ends must match

token, REALITY key pair, server name, and short ID must correspond. Plain security.type=reality selects v0.2.4 automatic carriers only with group mux; this forced QUIC stack still requires reality-quic.

tcptun config native --quic --server proxy.example.com --port 9443

{
  "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": {}
}

Minimal topology

The server exposes a native inbound; the client forwards a local mixed inbound to a native outbound. Replace the sample credentials and addresses to run.

Fields

Common field overview.

Common fields

tagboth: Unique identifier referenced by routes.
typeboth: "native".
addressboth: host:port string array; outbounds may list multiple candidate entry points.
networkboth: tcp / udp, combinable.
transportboth: Only type / path (raw / ws / h2 / h3).
securityboth: tls, reality auto, forced reality-tcp, or forced reality-quic; all security parameters live here.
muxboth: Presence enables mux; {} uses defaults. Pool parameters are mainly on the client.

Server

addressserver: Listen address list, e.g. ["0.0.0.0:9443"].
users[].idserver: Auth credential matching the client token.
publishserver: Reverse publish: service + address, optional network=tcp|udp.
security.cert/keyserver: Required for TLS inbounds; reality-quic uses REALITY key fields instead.

Client

addressclient: Remote entry points; multiple candidate host:port values are allowed.
tokenclient: Required; matches server users[].id.
security.server_nameclient: SNI for TLS/QUIC.
exposeclient: Reverse publish: service + target, optional network=tcp|udp.
mux.max_sessionsclient: Connection pool cap, 1–32, default 4.
mux.max_streams_per_sessionclient: Per-connection stream cap, 1–4096.
mux.warm_sparesclient: Warm idle connections; must be less than max_sessions.
mux.udp_modeclient: QUIC only: reliable / auto / datagram.
mux.resumeboth: v0.2.4: preserve eligible native TCP logical streams across Reality auto carrier replacement.
mux.resume_timeoutboth: Recovery window: default 15s; explicit 100ms–5m.
mux.resume_buffer_sizeboth: Per-direction replay buffer: default 4 MiB; explicit 64 KiB–64 MiB.
mux.*_receive_windowboth: QUIC receive windows; stream max 16 MiB, connection max 64 MiB.

Mux / QUIC

Enable mux for short-connection workloads. Prefer native + raw + mux for peak throughput.

How to enable

Any mux object enables mux (commonly "mux": {}). Do not use enabled; omit the mux field to disable it.

TCP mux

Reuses physical connections. Unreachable targets are not reported as success to the local proxy early.

Reality auto carriers

native + raw + group mux + reality prefers QUIC, falls back to Reality TCP with bounded backoff, then probes to restore QUIC preference.

Resumable streams

mux.resume keeps eligible native TCP logical streams alive while an automatic Reality carrier is replaced. Enable matching settings on both peers.

QUIC

mux.mode: "quic" uses a UDP/QUIC connection pool and requires native + raw; security.type may be tls or reality-quic.

UDP

reliable uses streams; auto prefers DATAGRAM with fallback; datagram does not degrade. DATAGRAM supports fragmentation, recovery, and adaptive FEC.

mux snippet

"mux": {
  "max_sessions": 4,
  "max_streams_per_session": 16,
  "warm_spares": 1
}

v0.2.4 continuity

Resumable TCP logical streams

Add resume to matching Reality-auto mux blocks to preserve an eligible TCP logical stream while its physical QUIC or TCP attachment is replaced.

Exact scope

native + raw + security.type=reality + group mux only. UDP, reverse publish, reality-tcp, reality-quic, and mux.mode=quic are not resumable.

Both peers

Set mux.resume=true on both endpoints running v0.2.4+. There is no silent downgrade when only one peer enables it.

Bounded recovery

resume_timeout defaults to 15s (100ms–5m). resume_buffer_size defaults to 4 MiB (64 KiB–64 MiB).

One server process

The registry is process-local. Use one unique outbound address whose TCP and UDP paths reach the same server process.

matching endpoint mux block

"mux": {
  "mode": "group",
  "resume": true,
  "resume_timeout": "15s",
  "resume_buffer_size": 4194304
}

Reverse publish

Hang NAT-side TCP/UDP services on tunnel server listen ports. Configure publish on the server and expose on the client.

Protocol scope

Only native + raw, and group mux or QUIC mux must be enabled. VLESS / VMess / Trojan are rejected during validation.

Pairing rules

Server publish and client expose service names must match, and network must match as well (default tcp).

Security boundary

The client local target is not sent to the server; the server can only open allowlisted services.

QUIC requirements

QUIC reverse publish needs matching TLS or reality-quic on both ends; TLS servers need cert/key.

Workflow

Generate → validate → start.

generate01

Generate a pair

Writes server.json and client.json.

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

check02

Validate

Does not listen; useful after editing a config.

tcptun config check --config server.json

quic03

Generate a QUIC pair

Writes matching reality-quic + QUIC mux configs.

tcptun config native --quic --server proxy.example.com --port 9443

run04

Start

Start the server first, then the client.

tcptun --config server.json
tcptun --config client.json

uri05

Export URI

Exports URIs from tunnel outbounds; multiple addresses become multiple URIs.

tcptun uri export --config client.json --output client.uri

REALITY

REALITY and REALITY QUIC

Configured under security. All four tunnel protocols can use it; VLESS generated configs enable Vision by default.

rawX25519

raw only

transport must be raw and cannot be combined with ws / h2 / h3.

No stacked TLS

Plain reality cannot stack with security.type=tls; choose exactly one security type.

Supported endpoints

Works with native / vless / vmess / trojan. mixed and socks5 are unsupported.

Key pairing

Server private_key pairs with client public_key; short_id must match on both ends.

native auto (v0.2.4)

On native + raw + group mux, security.type=reality enables dual carriers: QUIC-first with TCP fallback. Without mux, Reality stays TCP-only.

Forced modes

reality-tcp forces TCP only. reality-quic with mux.mode=quic forces the dedicated QUIC pool (no TCP fallback) and does not use spider_x.

Server

type: "reality".
private_key: X25519 private key (base64url).
server_names: Allowed SNI list.
short_ids: Allowed short ids (hex).
dest: Camouflage target, e.g. example.com:443.
max_time_diff: Optional clock skew, default 30s.

Client

type: "reality".
public_key: Server public key.
server_name: SNI; must be in server_names.
short_id: A single short id.
fingerprint: uTLS fingerprint, commonly chrome.
spider_x: Optional path, default /.

{
  "log": { "level": "info" },
  "inbounds": [
    {
      "tag": "server",
      "type": "vless",
      "address": ["0.0.0.0:443"],
      "network": ["tcp", "udp"],
      "users": [
        {
          "id": "00000000-0000-4000-8000-000000000000",
          "flow": "xtls-rprx-vision"
        }
      ],
      "transport": { "type": "raw" },
      "security": {
        "type": "reality",
        "private_key": "REPLACE_WITH_SERVER_PRIVATE_KEY",
        "server_names": ["example.com"],
        "short_ids": ["00"],
        "dest": "example.com:443",
        "max_time_diff": "30s"
      }
    }
  ],
  "outbounds": [
    { "tag": "direct", "type": "direct" }
  ],
  "route": { "default_outbound": "direct", "rules": [] },
  "dns": {}
}

Generate a REALITY pair

Writes paired server.json and client.json; run tcptun uri export if you need URIs.

tcptun config vless --server proxy.example.com --port 443 --server-name example.com --dest example.com:443

native + REALITY

Generates matching REALITY configs for native on both ends.

tcptun config native --server proxy.example.com --port 9443 --server-name example.com --dest example.com:443

native + REALITY QUIC

Generates matching reality-quic + QUIC mux configs for native on both ends.

tcptun config native --quic --server proxy.example.com --port 9443 --server-name example.com --dest example.com:443

Validate and start

Validate keys and fields first, then start.

tcptun config check --config server.json && tcptun --config server.json

Note

Native + raw + group mux + reality is automatic QUIC-first with TCP fallback in v0.2.4. The separate forced mux.mode=quic stack requires certificate TLS or security.type=reality-quic; tcptun config native --quic generates the latter.

Compare

Four tunnel protocols

Xray compatibility is for wire protocols, not config files.

Protocol	Credential	Interop	Default security	Vision	Mux	Best for
`native`	token ↔ users[].id	tcptun only	raw + REALITY	—	Private mux, recommended	Throughput / reverse publish
`vless`	uuid ↔ users[].id	Xray VLESS	raw + REALITY + Vision	xtls-rprx-vision	Optional	Xray interop / camouflage
`vmess`	uuid ↔ users[].id	Xray VMess	raw + REALITY	—	Optional	VMess ecosystem
`trojan`	password ↔ users[].password	Xray Trojan	raw + REALITY	—	Optional	Password auth

{
  "tag": "proxy",
  "type": "native",
  "address": ["proxy.example.com:9443"],
  "token": "change-me",
  "transport": { "type": "raw" },
  "mux": {}
}

tcptun config native --server … --port …