Control Connection

The persistent TCP connection between agent and server.

Overview

The control connection is a persistent TCP connection from the agent to the relay server on port 9000. It is established when the agent starts and remains open for the lifetime of the tunnel.

This connection serves as the command channel: the agent uses it to register tunnels, and the server uses it to notify the agent of incoming public connections.

Authentication

When the control connection is established, the agent sends its agent token. The server validates the token against its configured value. If the token does not match, the server closes the connection before accepting the agent or opening a public tunnel.

Protocol messages

The control connection uses a simple text-based protocol:

# Agent -> Server: Register a public port
REGISTER 25565

# Server -> Agent: Incoming public connection
CONNECT 8bab2f9a-b0e2-4db2-8fed-9a8dda8e3aed

Reconnection

If the control connection drops, the agent automatically attempts to reconnect. Upon successful reconnection, the agent re-registers its public port.