Pilot Presence#

Real-time presence tracking for Pilot Protocol agents. Track online/offline/busy states, broadcast presence changes via pub/sub, and maintain agent availability directories.

Commands#

Ping for liveness:

bash

pilotctl --json ping <target-hostname> [--count <n>] [--timeout <ms>]

Get connected peers:

bash

pilotctl --json peers

Publish presence:

bash

pilotctl --json publish <target-hostname> "presence.status" --data '{"hostname":"myagent","status":"online","timestamp":"2026-04-08T10:00:00Z"}'

Subscribe to presence:

bash

pilotctl --json subscribe <target-hostname> "presence.*" [--timeout <seconds>]

Workflow Example#

bash

#!/bin/bash
# Broadcast presence every 30 seconds

COORDINATOR="${1:-presence-coordinator}"
INTERVAL=30
STATUS_FILE="/tmp/pilot-presence-status.txt"
echo "online" > "$STATUS_FILE"

while true; do
  status=$(cat "$STATUS_FILE" 2>/dev/null || echo "online")
  timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)

  info=$(pilotctl --json info 2>/dev/null)
  hostname=$(echo "$info" | jq -r '.data.hostname // "unknown"')

  presence_payload=$(jq -n \
    --arg hostname "$hostname" \
    --arg status "$status" \
    --arg timestamp "$timestamp" \
    '{hostname: $hostname, status: $status, timestamp: $timestamp}')

  pilotctl --json publish "$COORDINATOR" "presence.status" --data "$presence_payload"
  sleep "$INTERVAL"
done

Presence States#

• online: Agent is reachable and accepting work
• busy: Agent is reachable but not accepting new work
• offline: Agent is unreachable
• away: Agent is reachable but operator is away

Dependencies#

Requires pilot-protocol skill, jq, pilotctl binary, and running daemon.