Inside ColituGecko
How Gecko establishes an encrypted session, moves streams between network paths, and recovers from a lost path.
ColituGeckoOne session, multiple paths
A Gecko session holds the state of application traffic. A grip is one network path attached to that session. Multiple grips can reach the same anchor and carry the same session.
Protocol layers
The session tracks stream IDs, received byte offsets and flow control. That state is independent of the lifetime of any individual grip.
Gecko carries frames in authenticated encryption records. The protection between the client and anchor is independent of the outer transport.
A grip is a path established through an entry and an outer transport. An active grip carries traffic. A standby grip is attached and can take over when needed.
The anchor terminates the Gecko session and owns the connections to destinations. An entry can reach that anchor directly or through a relay.
A skin is the grip’s outer transport. Options such as TLS and QUIC belong to this layer. A relay can forward traffic along the path. The client and anchor authenticate and decrypt the inner Gecko records.
Session topology
Inspect a path
Traffic goes through the first entry to the anchor. The same encrypted session is available on the second path.
The session and path lifecycle
The first path establishes the session. Later paths can attach to it. When an existing path becomes unusable, Gecko knows which stream bytes the peer has received.
A path loss scenario
The client authenticates the anchor. A successful handshake establishes the session keys and its first grip.
The client attaches a second grip to the existing session. It can remain on standby or carry traffic, depending on the active policy.
If traffic on the first path stops receiving acknowledgements, the scheduler can mark it as suspect. Outstanding bytes are eligible to be sent through another grip.
The second path carries traffic. The receiver reassembles bytes by stream offset and drops duplicates. The destination connection can stay in place because the anchor stays the same.
If every grip becomes unavailable, traffic pauses. Gecko can retain session state for a limited time. The session can resume if a path to the same anchor returns before that state expires.
Available paths during recovery
Simulated sequenceTwo paths are attached to the same anchor. Traffic uses the active path.
Records and cryptography
Gecko establishes inner encryption between the client and anchor. The handshake creates a session secret. Key derivation produces separate keys for individual paths, directions and purposes.
- Hybrid key agreement
X25519 + ML-KEM-768Handshake combining classical and post-quantum key establishment.- Record protection
ChaCha20-Poly1305Encrypts record contents and authenticates their integrity.- Key derivation
HKDF-SHA-256Derives purpose-separated keys from session key material.- Admission
Ed25519Verifies short-lived admission tickets signed by the control plane.
Gecko carries records differently on ordered lanes and in datagram mode. The datagram receiver tracks record numbers with a replay window so that previously accepted records are discarded. An ongoing session can also advance to a new key epoch.
Streams and scheduling
Gecko carries reliable byte streams and UDP datagrams in the same session. Path selection depends on the type of traffic and the current state of each path.
- Interactive traffic
- The scheduler considers latency and queued work. A small request can prefer a path where it is less likely to wait behind a backlog.
- Bulk transfers
- Useful throughput is the priority. A stream normally stays assigned to one path and moves when conditions change materially.
- Realtime datagrams
- Late datagrams are not retransmitted. Some low-rate flows can use two active paths, with duplicate packets discarded at the receiver.
For reliable streams, acknowledgements report received byte offsets and the window the sender can use. This lets the receiver preserve stream order while missing data is sent through another grip.
How the protocols differ
Compare Gecko with the five modes documented by Colitu and other common proxy and VPN designs. The table compares what each one carries, how it protects traffic and what can continue across a path change.
Where Gecko stands out
- An existing stream can change transport
- With a TLS grip and a QUIC grip attached to the same anchor, Gecko can send outstanding stream bytes over the other grip. The original stream offsets and destination connection can stay in place.
- The encryption sits inside the session
- Gecko authenticates its anchor and protects its own records. A change of entry or outer transport can leave the client-to-anchor cryptographic session in place.
- Continuity depends on the anchor
- A route failure and an anchor failure have different outcomes. Gecko can recover its paths to the same anchor. An abrupt anchor failure ends the open destination connections.
| Protocol | Traffic and transport | Path change and delivery | Protection |
|---|---|---|---|
| ColituGeckoSession tunnel | Reliable streams and UDP datagrams in a tunnel sessionMultiple outer transports, including TLS and QUIC | Moves stream traffic between attached grips to the same anchorResends unacknowledged stream bytes on another path. Datagram delivery is best effort. | Hybrid X25519 + ML-KEM-768 exchange. Gecko records use ChaCha20-Poly1305. |
| Hysteria 2Proxy | TCP and UDP proxyQUIC streams for TCP and QUIC datagrams for UDP | Proxy streams and datagrams are associated with a QUIC connectionReliable QUIC streams for TCP. UDP uses best-effort datagrams. | TLS 1.3 in QUIC. Hysteria authenticates the proxy connection. |
| VLESS + REALITYRAW · XTLS Vision | VLESS proxy over a RAW TCP transportThis variant uses XTLS Vision for TCP flow handling. | The proxied flow follows the TCP transportTCP retransmits lost bytes. After the transport closes, new proxy connections use a new transport. | REALITY secures the outer transport. VLESS authenticates the client separately. |
| VLESS XHTTP + REALITYProxy | VLESS traffic in HTTP requests and responsesXHTTP can carry upload and download in separate requests depending on mode. | XHTTP controls how HTTP requests form the streamContinuity depends on the XHTTP mode, active HTTP transport and implementation. | REALITY protects this variant’s outer connection. XHTTP is the transport. |
| TrojanProxy | TCP proxy and UDP relay over TLSThe original protocol frames UDP traffic inside the TLS connection. | Traffic follows the TLS connectionWhen the TLS connection closes, the proxy needs a new connection. | TLS provides encryption. Trojan authenticates proxy requests. |
| Shadowsocks 2022Proxy | Encrypted TCP and UDP proxyTCP uses encrypted chunks. UDP has its own relay sessions. | UDP sessions can follow the client’s new addressTCP proxy streams remain tied to their TCP connection. | AEAD with a pre-shared key, BLAKE3 subkey derivation and replay protection. |
| TUICProxy | TCP and UDP relayQUIC streams and datagrams | Uses QUIC connection migration where supportedUDP relay can use datagrams or reliable streams. | QUIC protects the transport. TUIC authenticates at the proxy layer. |
| VMessProxy | Encrypted application proxyXray can carry VMess over multiple configured transports. | Relies on its configured transportVMess does not define cross-transport recovery for an open stream. | VMess authenticates requests and supports payload encryption. An outer TLS layer is optional. |
| WireGuardIP tunnel | IP packets between peersWireGuard packets over UDP | Learns a peer’s new endpoint from authenticated packetsThe tunnel passes packets. Upper-layer protocols handle retransmission. | Noise-based handshake using Curve25519. ChaCha20-Poly1305 protects tunnel packets. |
| OpenVPNIP tunnel | IP tunnel or Ethernet bridgeTUN or TAP over a selected UDP or TCP transport. | UDP mode can accept an authenticated address changeTCP mode depends on its TCP connection. Reconnection behavior depends on configuration. | TLS control channel and separately encrypted data channel in TLS mode. |
| IKEv2 / IPsecIP tunnel | IPsec ESP carries IP packetsIKEv2 negotiates the security associations used by IPsec. | MOBIKE can change outer addresses while keeping security associationsThe inner addressing can stay the same when both peers support MOBIKE. | IKEv2 authenticates peers and negotiates keys. IPsec ESP protects tunnel traffic. |
This matrix compares protocol design. Compare latency, recovery time and throughput in controlled tests using the same hosts, versions, workloads and network conditions.
Design boundaries and tests
- Path loss
- Continuity depends on a working path to the same anchor, or one returning before expiry. Traffic waits while every path is unavailable.
- Anchor loss
- If the anchor fails abruptly, its open connections end. The client establishes a new session with another anchor.
- Trust boundary
- The tunnel protects traffic between the client and anchor. Application-layer encryption to the destination depends on its own protocol, such as HTTPS.
- Verification scope
- The project includes shared test vectors and automated coverage for handshakes, path loss, UDP and relays. The animations on this page illustrate the design. They do not measure field performance or overall availability.