Flow

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
PING 0:0000.0000.037D
  seq=0 bytes=6 time=513.952ms
  seq=1 bytes=6 time=552.655ms
  seq=2 bytes=6 time=856.036ms
  seq=3 bytes=6 time=601.204ms

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
BENCH 0:0000.0000.037D — sending 1.0 MB via echo port
  Sent:     1.0 MB in 3.7s (0.3 MB/s)
  Echoed:   1.0 MB in 12.6s (0.1 MB/s round-trip)

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, and transport diagnostics — CWND (congestion window: TCP send rate limit), SRTT (smoothed round-trip time), and SACK (selective acknowledgements) stats.

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