Connection flow
The agent separates orchestration from operational traffic by maintaining two outbound connections to the server.
Connection summary
| Path | Protocol | Supported transports | Purpose |
|---|---|---|---|
| Control | Socket.IO | HTTP long polling, WebSocket over HTTP(S), or WebSocket encapsulated over DNS | Registration, metadata, heartbeats, and control instructions |
| Data | SSH | Direct SSH, TLS, WebSocket, HTTP, DNS, or QUIC | Shells, SFTP, transfers, proxies, forwards, and WireGuard |
Neither path requires an inbound connection to the target machine.
Control connection
The control connection is a Socket.IO client/server exchange. It can use:
- HTTP long polling.
- WebSocket through an HTTP Upgrade, over HTTP or HTTPS.
- A WebSocket connection encapsulated in DNS queries and responses when DNS is the only permitted egress path.
Control messages are encrypted. The agent identifier is sent in cleartext so the server can associate the connection with the correct agent instance. The initial message is encrypted with the server’s age public key embedded in the agent. During that exchange, the agent supplies a symmetric session key used to encrypt subsequent control messages.
SSH data connection
The data path is an outbound SSH connection initiated by the agent. It can reach the server directly or use any supported SSH transport: TLS, WebSocket, HTTP, DNS, or QUIC. See Tunneling and Listening services.
Through SSH channels and remote forwarding, the agent exposes:
- interactive and persistent shell sessions;
- SFTP, SCP, rsync, and rclone transfers;
- SOCKS and HTTP proxy services;
- local and remote forwards; and
- the virtual WireGuard endpoint.
SSH authentication uses an ephemeral public key generated by the server for each agent connection.
Keepalive and reconnection
The agent sends keepalives on both paths and reconnects with exponential backoff after a connection is lost.
keepalive: 20
timeout: 60
keepalive controls the interval in seconds; 0 disables keepalive messages. timeout controls how long connection attempts, configuration exchange, and keepalive responses may take; 0 removes that limit. Increase the timeout for high-latency transports such as DNS.
If the Socket.IO pong does not arrive before the timeout, the agent treats the control path as unhealthy and restarts even when the underlying socket still appears open.
Failure isolation
An online control connection does not prove that the SSH data path works. If the agent appears in tealc list but a shell fails, follow Control works, but SSH fails. Repeated failures on either path are covered by Reconnect troubleshooting.
