Diagnostics

Tools for measuring latency, throughput, and inspecting network state.

ping

Send echo probes to measure round-trip time:

pilotctl ping other-agent
pilotctl ping other-agent --count 10
pilotctl ping 0:0000.0000.0005 --timeout 30s

Uses the built-in echo service (port 7). Default: 4 pings.

Returns: target, results [{seq, bytes, rtt_ms, error}], timeout (bool)

# Example output (human-readable)
PING 0:0000.0000.0004 (agent-alpha):
  seq=0 bytes=32 rtt=12.4ms
  seq=1 bytes=32 rtt=11.8ms
  seq=2 bytes=32 rtt=13.1ms
  seq=3 bytes=32 rtt=12.0ms

traceroute

Measure connection setup time and RTT samples:

pilotctl traceroute 0:0000.0000.0005

Returns: target, setup_ms, rtt_samples [{rtt_ms, bytes}]

bench

Measure throughput by sending data through the echo service:

pilotctl bench other-agent          # 1 MB (default)
pilotctl bench other-agent 10       # 10 MB
pilotctl bench other-agent 50 --timeout 120s

Returns: target, sent_bytes, recv_bytes, send_duration_ms, total_duration_ms, send_mbps, total_mbps

# Example output
benchmark 0:0000.0000.0004: sent 1048576 bytes, recv 1048576 bytes
  send: 850ms (9.87 Mbps)
  total: 1.2s (6.99 Mbps)

peers

List connected peers:

pilotctl peers
pilotctl peers --search "web-server"  # Filter by tag or query

Returns: peers [{node_id, endpoint, encrypted, authenticated}], total

connections

List active connections with transport stats:

pilotctl connections

Returns detailed per-connection information: connection ID, local/remote port, state, bytes sent/received, segments, retransmissions, SACK stats, congestion window (CWND), and smoothed RTT (SRTT).

info

Full daemon status — everything at a glance:

pilotctl info

Returns: node_id, address, hostname, uptime_secs, connections, ports, peers, encrypt, bytes_sent, bytes_recv, per-connection stats, peer list with encryption status.

disconnect

Close a specific connection by ID:

# Find the connection ID first
pilotctl connections

# Close it
pilotctl disconnect 42

Returns: conn_id