Inside ColituGecko

How Gecko establishes an encrypted session, moves streams between network paths, and recovers from a lost path.

ColituGecko

One 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.

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.

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 sequence

Two 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.
See path recovery in motion
ProtocolTraffic and transportPath change and deliveryProtection
ColituGeckoSession tunnelReliable streams and UDP datagrams in a tunnel sessionMultiple outer transports, including TLS and QUICMoves 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 2ProxyTCP and UDP proxyQUIC streams for TCP and QUIC datagrams for UDPProxy 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 VisionVLESS 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 + REALITYProxyVLESS 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.
TrojanProxyTCP 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 2022ProxyEncrypted 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.
TUICProxyTCP and UDP relayQUIC streams and datagramsUses QUIC connection migration where supportedUDP relay can use datagrams or reliable streams.QUIC protects the transport. TUIC authenticates at the proxy layer.
VMessProxyEncrypted 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 tunnelIP packets between peersWireGuard packets over UDPLearns 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 tunnelIP 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 tunnelIPsec 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.
Try path switching in the demo