0Abstract
Adaptive Connect 2.0 taught the apps to notice a path that breaks while connected and to move traffic to a warm spare. Field data showed three weak points: diagnosing an outage took tens of seconds, the app tried blindly on a network it did not know, and because the same logic was written separately on four platforms, the decisions had drifted apart. Adaptive Connect 3.0 addresses these three points: network hints derived from anonymous aggregate data to start with the right connection mode on the first try, a recovery set that finds a working server even when the API cannot be reached, a watcher that diagnoses an outage in about 11 seconds, and a shared set of rules with 46 vectors that all four apps obey. This report describes the architecture of 3.0, its staged rollout and its measurements, and keeps apart the parts that are still alpha or only planned.
1Why 3.0?
In the first week after 2.0 was released we collected data from two sources: laboratory runs with injected faults, and the anonymous connection telemetry the apps send (its structure is in the privacy section). In the laboratory baseline measurement of 2.0 against 29 servers, 85.2 % of probes succeeded; the problems were concentrated in particular fault types (laboratory report).
| Finding | Source | Result |
|---|---|---|
| Slow outage diagnosis | Field telemetry | Average time between detection and recovery: 54 s on Android, 34 s on Windows |
| Long connection tail on Windows | Field telemetry + test computer | Successful first-attempt connections averaged 14.9 s; root cause: while the kill switch is held, the API addresses existed only in memory |
| The warm spare sometimes never took over | Laboratory | Because background traffic exceeded a threshold, the switch to the warm spare was postponed indefinitely |
| Blind start on a new network | Field telemetry | On a network with no memory, the app tried the modes in a fixed order |
| Platforms had drifted apart | Code review | The same rule had been written separately in four languages; Windows and Linux differed in ranking and in hint parsing |
So the goal of 3.0 is not a new protocol but decision quality: fewer attempts, a shorter blind period, the same decision on every platform. No additional data is collected from the user, and a manually chosen location is never changed.
2Architecture: seven components
3.0 was designed from the start as a framework of seven components. They are not all at the same maturity; the table below states the current status of each one plainly.
| Component | What it does | Status |
|---|---|---|
| Collective network hints | Derives from anonymous aggregate data which connection mode works on a network | Live |
| Predictive start | On a network it does not know, the app starts with the mode named in the hint; it relies on rules, there is no machine learning | Live |
| Autonomous recovery | Connects with a recovery set stored on the device and with saved addresses, even when the API cannot be reached | Live |
| Fast outage detection | Diagnoses an outage while connected in ~11 s and decides when to leave the server | Live |
| Network laboratory | Fault-injection packages and test vectors shared across platforms | Live (internal tool) |
| Continuity engine (CSL) | A session layer that keeps the session alive even when the tunnel changes; several carrier lanes | Alpha (Windows, test accounts) |
| Adaptive camouflage | Choosing traffic shape and transport settings according to the network | Planned |
Network hints v2
The apps anonymously report the outcome of each connection attempt (mode, success or failure, duration). The panel turns these into daily totals per network, that is, at the level of country + autonomous system (ASN). If a network has enough data, the server list is returned together with a `preferred` order: the modes that worked on that network in the last 24 hours, highest success rate first. When the network changes, the app fetches the list again and uses the new network's hint.
In the measurement on 16 October, 89 distinct networks were seen in the last seven days; 44 of them had enough data to decide, and a preference order was produced for 40. On some networks the success rate of the UDP-based Hysteria2 was 92 % while the TCP modes were in the range 44–54 %; a fixed order wasted time on every connection on those networks.
Recovery set
In 2.0, if the server list could not be fetched from the API, the app had nowhere to connect. In 3.0, while the API is responding, the app downloads a small recovery set about once a day and stores it on the device: full profiles for a few servers in different countries, valid for much longer than a normal configuration. First the servers this device has reached in recent days are chosen, then one server from each country; so even if access to the servers in one country is cut, the others remain. The set is used only when none of the API addresses respond and the normal cache cannot connect either; once connected, the app reaches the API from inside the tunnel and refreshes everything.
In addition, the Windows and Linux apps now store the API addresses on disk and refresh them in parallel. When the kill switch was held over from the previous run (automatic connection after a crash or a restart), system DNS was closed, so 2.0 tried to resolve the addresses one after another, and it took 21–25 seconds from startup to connection.
Fast outage detection
The watcher probes the main path once a second with a three-second timeout. A single loss is not yet a decision; once consecutive losses are confirmed, an outage decision is made within about 11 seconds. What happens after the decision depends on the scope of the outage:
| Situation | Decision |
|---|---|
| Only the main path went down, the warm spare works | Traffic stays on the warm spare; the other modes on the same server are tried first |
| The main path and the warm spare went down together, the device is online | In automatic mode the server is put in the background for this network for 30 minutes and the next server is tried |
| The device's own internet went away | No mode or server is blamed; the app reconnects when the network returns |
| Manually chosen location | The server is not changed; the app switches only between modes at the same location |
A bug in 2.0 was also closed: when there was constant small background traffic, the switch to the warm spare was postponed indefinitely on the grounds that the connection was "busy". In 3.0 the postponement is limited to at most two minutes or 32 KB.
Instant device identity
Every device has its own identity on every server. In 2.0 a new identity reached the server only at the regular 15-second sync, so a new user's first connection could fail for 15–30 seconds. Now an identity change is passed to the servers immediately; the configuration request waits briefly, and if the identity is still not ready the app knows this and retries at two-second intervals.
3Shared decision rules and the Go engine
The rules of Adaptive Connect live in four apps in four different languages: Kotlin (Android), C# (Windows and Linux), Dart and Swift (iOS). With 3.0 these rules are tied to a single source: shared test vectors. Each vector contains an input (servers, measurements, memory, hints) and the expected decision; the test suites of the four apps run the same files.
| Vector file | Scope |
|---|---|
| ranking | Server ranking in automatic mode: last working, ping, penalties, own-country rule (19 cases) |
| transport | Base order of connection modes, hint-driven start, ignored flags |
| hints | Parsing of the hint response |
| recovery | Recovery decision, refresh time, reading the set, next server |
There are 46 cases in total across the four files. If a rule changes in one app and one of the vectors gives a different result, that app's test suite fails.
The first run of the vectors found real differences: Windows and Linux applied the rule of pushing back one's own country to every country; in these two apps a hint value that was not a number could break the reading of the whole server list; Linux ordered TCP modes by latency alone. All of them were merged into a single set of rules.
The same rules were also implemented in an open-source Go package, and it passes the same 46 vectors. The engine is built into the Android, Windows and Linux apps in shadow mode: while connecting, the app's own decision is compared with the engine's decision and any difference is logged, but the decision is the app's. If the engine returns an error it is disabled for ten minutes. When the differences in shadow mode drop to zero, the decision will be handed to the engine; the engine is not yet built into iOS.
4Staged rollout
The app side of 3.0 was added to the releases in such a way that the rollout decision can be made remotely: Android 2.9.2, Windows 2.9.7, Linux 1.5.3 and the iOS 5.9 series. The panel returns the `features.adaptive_connect_3` flag in the server list response. Which device falls into the rollout group is determined by a stable bucket derived from the SHA-256 digest of the device identity; the same device stays in the same group as long as the percentage does not change. The app stores the last flag and uses it for as long as it cannot reach the API.
| Date | Share | Platforms |
|---|---|---|
| 16 October 2026 | 10 % | Android, Windows, iOS |
| 17 October 2026 | 15 % | Android, Windows, iOS |
| 20 October 2026 | 100 % | Android, Windows, iOS |
The parts enabled remotely are the hint-driven start and the recovery set. Fast outage detection, the rule for leaving a server, the saved API addresses and the shared rules came to every user with the release. Linux was deliberately left out of the remote rollout: the number of users is too small to compare, and release 1.5.3 had a rise in connection errors unrelated to 3.0. Rollback is done with a single setting and needs no app update.
5Measurements
| Measurement | 2.0 | 3.0 | How it was measured |
|---|---|---|---|
| Diagnosing an outage | 54 s (Android), 34 s (Windows), field average | ~11 s | Watcher cadence; unit tests and the test computer |
| Total outage when traffic to the server is cut for 45 s | 50 s | 22.4 s | Windows test computer, with a firewall rule on the device |
| From startup to connection while the kill switch is held | 21–25 s | 5.1–5.2 s | Windows test computer, repeated restarts |
| First connection on a network with no memory | Fixed mode order | 1.6 s (with the mode from the hint) | Android test device |
| Connecting while the API cannot be reached | Nowhere to connect | Connected 12 s after the tap | Android test device, API blocked, cache ignored |
In the field, in the days after 16 October, connection success on Android was measured in the range 98.3–98.6 % (in earlier weeks it varied from day to day between 80 % and 98 %); on Windows 2.9.8 it was 97.4 %. We do not attribute this difference to 3.0 alone: because the telemetry is anonymous by design, devices in the 3.0 group cannot be separated from the others, and other fixes were released in the same versions. During the rollout no complaint or drop in success attributable to 3.0 was seen; the rollout decisions were based on this criterion.
6Privacy
The learning parts of 3.0 require no new user data. Connection telemetry is anonymous by design: events are written only as daily totals, to two separate tables that have no common row.
- Network table: country + ASN (from the signed network token), mode, result counts. No server.
- Server table: server × client country, result counts. No ASN.
- No table contains an account, a device identity or an IP address; the two tables cannot be joined to reach a single user.
- The memory of the last working server, stall marks and penalties is kept on the device and is not shared with the panel.
- The rollout bucket is computed from a one-way digest of the device identity; which device is in which group is not stored.
Details are in the security report and the privacy policy.
7Continuity engine: CSL alpha
The Colitu Session Layer (CSL) is the session layer mentioned as future work in the 2.0 report. Its purpose is that open connections do not break even when the tunnel underneath changes: the session runs over several carrier lanes, and if one lane dies the session continues on another. The source code is open under the Apache-2.0 licence: github.com/colitu/csl.
CSL is in the alpha stage today: it is available only to test accounts and a separate test server, through the "Seamless session (alpha)" option in Advanced mode of the Windows app. A separate session identity is generated for each device; the server side listens only locally. When CSL is off or fails, the app falls back to the normal connection. We are not giving a date for general availability.
8Limitations
- Rules, not a model. "Predictive" start means rules derived from anonymous aggregates, not a statistical model. Networks with little data have no hint, and 2.0 behaviour applies.
- Scope of the measurements. The laboratory results were obtained with a single test computer and a single test phone, with faults produced on the device; no fault tests were run on servers that have real users. They cannot be generalised to every network.
- The Go engine is in shadow mode. The decision is still in each app's own code; there is no engine on iOS.
- On Linux network hints and the recovery set are not yet enabled.
- Open TCP flows can break on a path change until CSL is generally available; browsers and apps usually reconnect by themselves.
9Next steps
- Handing the decisions to the Go engine once the shadow-mode differences are closed; adding the engine to iOS.
- Moving CSL to beta: Android, UDP datagram support, and a "call mode" that sends critical traffic over two lanes at once for voice and video calls.
- Adaptive camouflage: choosing among the existing transport settings for each network.
- Bringing Linux into the rollout after further verification.
These items are a roadmap, not a promise of dates or results. This report will be updated as each of them goes live.
10Conclusion
2.0 established the principle "notice the path that breaks and recover". 3.0 extends it in three directions: fewer blind attempts through anonymous network hints, connecting independently of the API through the recovery set and saved addresses, and outages diagnosed in about 11 seconds. The shared test vectors ensure that the four apps make the same decision in the same situation. The continuity and camouflage side is still at the beginning of the road; we will report on it with measured results. The design of the previous version and a one-hour fault test are in the Adaptive Connect 2.0 report.
·References
- RFC 8305, Happy Eyeballs Version 2: Better Connectivity Using Concurrency.
- RFC 9000, QUIC: A UDP-Based Multiplexed and Secure Transport.
- RFC 5482, TCP User Timeout Option.
- Colitu Adaptive Connect 2.0 technical report, 10 October 2026.
- Colitu Lab, Adaptive Connect fault regression test (faultlab).
- Colitu Session Layer (CSL) source code, github.com/colitu/csl.