Make difficult long-haul links feel local.
An open-source, self-hosted transport for TCP and UDP across a known WAN bottleneck.
Deploy · How it works · Project status · Contribute
During my internship at Microsoft Research Asia in 2013, I used Microsoft's dedicated link from China and saw, for the first time, how fast access to Google and YouTube could be.
Later, I built a detour gateway in Hong Kong to improve the China-US route when I'm back home. It worked, but it added infrastructure, doubled the network bandwidth cost, and increased latency. Is it possible to directly connect China to US while enjoying the same latency and bandwidth with dedicated links?
Although I did networking research for 10 years, I did not have the time to build it. It is finally possible with help from Kimi K3, Claude Opus 5 and GPT-5.6 Sol. Today, Queqiao is a ready-to-use, self-hosted protocol for supported client-to-gateway deployments. It carries TCP and UDP through a local proxy over an authenticated transport, and keeps evolving as we measure more paths, improve the transport, and learn from users.
Many transports make each connection learn and react on its own. That is a reasonable default for the general Internet, but it leaves performance on the table when many application flows share the same difficult client-to-gateway segment.
The path that motivated Queqiao made the problem concrete: we measured roughly 42–45% downstream packet erasure even below the path's capacity knee, followed by clustered loss when aggregate traffic exceeded that knee. Those two regimes need different responses. Backing off does not remove independent erasure; ignoring overload only makes it worse. See the full path characterization.
Queqiao is built around a few practical observations:
- Flows sharing one bottleneck should share one model. Flows to different final destinations can still share one client-to-gateway path, so Queqiao shares delivery, loss, RTT, pacing, and latency-reserve state across them.
- Not all packet loss means congestion. The controller distinguishes a measured erasure floor from loss caused by an overloaded bottleneck instead of treating every missing packet as congestion.
- Choose recovery for the path. On a long-RTT path, forward-error correction can recover a gap sooner than another round trip; as a flow grows, retransmission can become the more efficient choice.
- Protect interactive traffic from bulk transfers. Control and new interactive work must not wait behind a bulk transfer, so aggregate pacing, priority, and reactive isolation protect latency while the pipe is used.
- Upstream and downstream are different. Upstream and downstream can have very different capacity and loss behavior, so they are measured and controlled independently.
These are operating principles, not universal performance claims. Queqiao is a good fit when the client and gateway are known, trusted endpoints and their shared WAN segment is the dominant bottleneck. If the real bottleneck is somewhere else, measure again before relying on the optimization.
flowchart LR
A[Applications<br/>Web · SSH · video · transfers] --> B[Local SOCKS5<br/>Queqiao client]
B ==>|one coordinated long-haul path| C[Provider gateway]
C --> D[Internet destinations]
Queqiao presents an ordinary local SOCKS5 proxy, including UDP ASSOCIATE. The client and provider gateway form one authenticated transport session. Inside that session, every flow uses the same logical framing, byte-offset recovery, acknowledgement ranges, and scheduling machinery. QUIC streams and datagrams are used when available, with authenticated TLS/TCP fallback for restrictive networks.
The application does not have to choose a “short-flow,” “interactive,” or “bulk” protocol. Queqiao observes how a flow behaves and adjusts policy inside the same architecture. HTTPS remains end-to-end; the gateway sees the destination and traffic shape, but Queqiao does not inspect application content.
| System | Shared path model | Recovery strategy | Bulk median | SSH p99 under bulk load |
|---|---|---|---|---|
| Queqiao | Shared endpoint pair | Erasure-aware FEC + retransmission | 143.1 Mbit/s | 940 ms |
| TUIC v5 | Usually per connection | QUIC recovery | 76.8 Mbit/s | 662 ms |
| Hysteria 2 | Usually per connection | Protocol-specific UDP/QUIC recovery | 90.2 Mbit/s | 526 ms |
These are representative results from a six-round real-path campaign. They show why Queqiao's shared path model is promising, while the interactive tail shows why we do not claim a universal win. Results depend on the path and workload; see the full comparison and methodology.
- A desktop/server client and provider gateway for TCP CONNECT and UDP ASSOCIATE.
- Pooled QUIC streams and datagrams, with automatic authenticated TLS/TCP fallback.
- Shared endpoint-pair path measurement, erasure-aware control, sliding-window coding, aggregate pacing, priority scheduling, and reactive bulk isolation.
- One-time invitations, provider-pinned identity, per-device mutual TLS, renewal, revocation, and per-user session limits.
- A starter Clash/mihomo profile.
- One client process serving several providers, each on its own loopback SOCKS5 listener, for Clash/mihomo routing and failover.
- Bounded JSON logs, metrics, a local visualizer, deterministic benchmarks, release packaging, SBOMs, and rollback procedures.
- macOS and Linux: desktop and provider-gateway builds are available to use from source today.
- Windows: native release targets are built, but the Windows client is currently under testing and is not presented as production-ready.
- Android and iOS: clients use the same protocol-1 core and are currently under testing. They are not yet presented as production-ready mobile apps.
Build from source with the Go version declared in go.mod:
go test ./...
go build -o ./queqiaod ./cmd/queqiaodOn the provider gateway, initialize a provider, add a user, and create a single-use invitation:
sudo ./queqiaod provider init \
--state /var/lib/queqiao/provider \
--name "Example Network" \
--endpoint gateway.example.net:443
sudo ./queqiaod provider add-user \
--state /var/lib/queqiao/provider \
--name alice \
--max-sessions 8
sudo ./queqiaod provider invite \
--state /var/lib/queqiao/provider \
--user alice
sudo ./queqiaod server \
--state /var/lib/queqiao/provider \
--listen :443Send the printed queqiao:// URI to the user over a private channel. On the
client:
./queqiaod enroll 'queqiao://enroll/…'
./queqiaod client --profile ~/.config/queqiao/PROVIDER_ID.jsonThe client listens on 127.0.0.1:1080 by default. Point an application or
Clash/mihomo at that SOCKS5 endpoint. The deployment guide
covers service installation, firewall and socket tuning, multiple users,
source-interface selection, verification, upgrades, and rollback.
To use several providers from one desktop client process, follow the multi-provider deployment guide.
Queqiao is designed for a known difficult link between a client and a trusted gateway. Typical deployments include:
| Use case | Optimized segment |
|---|---|
| Intercontinental proxy or tunnel | user or branch to a gateway on another continent |
| Remote corporate access | employee or remote site to the corporate VPN gateway |
| Weak access network | hotel, residential, mobile, or rural link to a stable relay |
| Overlay network | one long-haul leg between two overlay endpoints |
The repository provides this paired data plane. Discovery, global routing, and a full mesh control plane belong to a larger overlay product built around it.
Queqiao is ready to build and use from source for the supported paired-gateway topology. It is a public preview, not a production-ready claim for every network. Protocol 1 is the only supported wire version; broader independent field qualification, transport and security review, and mobile review remain open. See current status for the evidence boundary and known limitations for operational constraints.
Performance is path-dependent. Historical measurements are design evidence, not a promise of throughput or latency on another ISP, carrier, hotel, campus, or country route. A same-window baseline and a reproducible report are more useful than a single headline number.
The same transport should serve short-lived requests, interactive sessions, and bulk transfers. The benchmark harness measures setup and completion time, latency and jitter under contention, useful goodput, recovery overhead, CPU, memory, and bounded resource use. Start with Measuring this transport and share field results using the network-evidence guide.
Normal traffic uses TLS 1.3 with a provider-pinned gateway identity and provider-issued per-device mutual authentication. There is no plaintext mode, shared tunnel password, or DNS/WebPKI identity requirement. The provider can observe destinations and traffic shape; Queqiao is not an anonymity network.
Read the security model, privacy statement, and protocol specification. Report vulnerabilities privately as described in SECURITY.md.
Queqiao is an open-source project, and useful contributions are not limited to code. You can:
- run the client on a different residential, mobile, hotel, campus, or intercontinental path and report what changed;
- submit a reproducible benchmark, a counterexample, or a workload regression;
- improve documentation, deployment examples, mobile clients, tooling, and tests; or
- propose a protocol or congestion-control change with measurements and a clear compatibility story.
Please remove credentials, private addresses, and user traffic before sharing. Read the contribution guide and the network-evidence guide before opening a change. Wire changes are versioned explicitly and fail closed.
The documentation index links the current design, architecture, protocol, deployment, mobile, benchmarking, release, and qualification guides. Start with the design if you want the technical details behind the principles above.
Queqiao is available under the MIT License.