Diagnose an agent

A practical checklist for investigating an agent connection

Use this checklist when an agent does not appear in the client, repeatedly disconnects, or accepts control traffic but cannot open an SSH session.

1. Check that the server is reachable

Verify the listener used by the agent. For a direct SSH listener:

nc -vz SERVER_HOST 2222

Expected output:

TODO_PLACEHOLDER_HERE

For HTTP or HTTPS, request the server URL from the same network where the agent runs:

curl -I https://SERVER_HOST/

Expected output:

TODO_PLACEHOLDER_HERE

The server’s healthcheck guide contains transport-specific checks.

2. Check the agent process

Confirm that the agent is running and inspect its standard output or log file. The log should show the selected transport and a successful registration.

3. Check the client view

tealc list
tealc tui

Expected output from tealc list:

TODO_PLACEHOLDER_HERE

If the agent is listed but offline, compare its last update and last ping in the TUI. If it is missing entirely, check the server logs and the agent’s registration credentials.

4. Check the connection path

Confirm that:

  • the agent’s server address resolves correctly;
  • the configured server port is reachable;
  • the server’s age public/private key pair matches;
  • the access token is valid;
  • the selected transport is enabled on both sides; and
  • an egress proxy, TLS inspection device, or DNS filter is not rewriting the connection.

5. Check the SSH data path

If control registration works but SSH does not, test the server SSH listener and the agent SSH settings separately. Check the agent’s SSH mode, exposed port, and transport order. See SSH and tunneling.

Metrics to inspect

The server metrics show useful indicators for a degraded agent:

  • heartbeat RTT;
  • reconnect count;
  • transport failures;
  • active channels; and
  • bytes transferred.

See server metrics for the endpoint and the meaning of the counters.