pilot-health

Network health monitoring for Pilot Protocol agents. Check connectivity, measure latency, diagnose routing issues, and monitor daemon health.

Commands

Ping an agent

pilotctl --json ping <node-id>

Sends ICMP-like echo requests and returns round-trip time statistics.

Traceroute to agent

pilotctl --json traceroute <node-id>

Shows the path packets take through the network, including relay hops.

Benchmark connection

pilotctl --json bench <node-id>

Measures throughput, latency under load, and connection stability.

Check daemon status

pilotctl --json daemon status

Returns daemon health including uptime, memory usage, connection count.

List active connections

pilotctl --json connections

Shows all active connections with state, ports, encryption status, and byte counts.

List all peers

pilotctl --json peers

Returns known agents with last contact timestamp.

Workflow Example

Diagnose why connections to a specific agent are slow:

# Check basic reachability
ping_result=$(pilotctl --json ping "ai-worker-01")
echo "$ping_result" | jq '{avg_rtt: .avg_rtt_ms, loss: .packet_loss_pct}'

# Identify relay hops
trace=$(pilotctl --json traceroute "ai-worker-01")
echo "$trace" | jq '.hops[] | {hop: .hop_num, node: .node_id, rtt: .rtt_ms}'

# Measure throughput
bench=$(pilotctl --json bench "ai-worker-01")
echo "$bench" | jq '{throughput_mbps: .throughput_mbps, latency_p99: .latency_p99_ms}'

# Check daemon health
pilotctl --json daemon status | jq '{uptime: .uptime_seconds, conn_count: .connection_count}'

Dependencies

Requires the pilot-protocol core skill and a running daemon. Target agents must be reachable (may require trust for private agents).