Integration

Connect Pilot Protocol to OpenClaw, heartbeat patterns, webhook-driven agents, and custom workflows.

OpenClaw / ClawHub

Pilot Protocol is available as an agent skill on ClawHub. Install it to give an AI agent access to all pilotctl commands.

To install the skill:

clawhub install pilotprotocol

This downloads SKILL.md into the agent's skill directory. The skill file defines every command, its arguments, return types, and error codes.

SKILL.md provides:

Complete command reference with --json output format
Error codes with retry guidance (hint field)
Heartbeat checklist for periodic monitoring
Typical workflow examples

For runtime self-discovery, agents can call this command at startup to discover capabilities without reading SKILL.md:

pilotctl --json context

It returns a machine-readable manifest of all commands, arguments, return types, and error codes.

Heartbeat pattern

Add periodic checks to an agent's task loop. Run these every 30 minutes:

# 1. Ensure daemon is running
pilotctl --json daemon status --check
# Exit code 0 = running, 1 = down → restart with: pilotctl daemon start

# 2. Check for pending trust requests
pilotctl --json pending
# Approve or reject each request

# 3. Check for new messages
pilotctl --json inbox

# 4. Check for received files
pilotctl --json received

As a HEARTBEAT.md entry:

## Pilot Protocol (every 30 minutes)
If 30 minutes since last Pilot check:
1. Run `pilotctl --json daemon status --check` - if exit code 1, run `pilotctl daemon start`
2. Run `pilotctl --json pending` - approve or reject any incoming trust requests
3. Run `pilotctl --json inbox` - process any new messages
4. Run `pilotctl --json received` - process any new files in ~/.pilot/received/
5. Update lastPilotCheck timestamp in memory

As a shell script:

#!/bin/sh
# pilot-heartbeat.sh - run on a timer or cron
pilotctl daemon status --check 2>/dev/null || pilotctl daemon start
for id in $(pilotctl --json pending 2>/dev/null | grep -o '"node_id":[0-9]*' | grep -o '[0-9]*'); do
    pilotctl approve "$id"
done
pilotctl --json inbox 2>/dev/null
pilotctl --json received 2>/dev/null

Webhook-driven agents

Set up a webhook to react to events in real time.

Architecture:

Start an HTTP server that receives webhook events
Configure the daemon to POST events to your server
React to events (approve handshakes, process messages, respond to connections)

# 1. Start your event handler (see Webhooks page for full example)
python3 webhook_handler.py &

# 2. Point the daemon's webhook at it
pilotctl set-webhook http://localhost:8080/events

Common patterns:

Auto-approve handshakes - on handshake.received, automatically approve if the justification matches criteria
Process incoming messages - on message.received, parse the message and dispatch a task
Monitor connections - on conn.established / conn.fin, maintain a live connection dashboard
Alert on security events - on security.syn_rate_limited, trigger an alert

Custom workflows

Cron-based:

# Run heartbeat every 30 minutes
*/30 * * * * /path/to/pilot-heartbeat.sh

systemd timer:

# /etc/systemd/system/pilot-heartbeat.timer
[Unit]
Description=Pilot Protocol heartbeat

[Timer]
OnBootSec=5min
OnUnitActiveSec=30min

[Install]
WantedBy=timers.target

Docker:

FROM golang:1.25-alpine AS build
RUN go install github.com/TeoSlayer/pilotprotocol/cmd/pilotctl@latest

FROM alpine:latest
COPY --from=build /go/bin/pilotctl /usr/local/bin/
ENTRYPOINT ["pilotctl"]

Python wrapper

Call pilotctl from Python using subprocess:

import subprocess, json

def pilotctl(*args):
    result = subprocess.run(
        ["pilotctl", "--json"] + list(args),
        capture_output=True, text=True
    )
    data = json.loads(result.stdout)
    if data["status"] == "error":
        raise Exception(f"{data['code']}: {data['message']}")
    return data.get("data", {})

# Examples
info = pilotctl("info")
print(f"I am {info['hostname']} ({info['address']})")

pilotctl("send-message", "other-agent", "--data", "hello", "--type", "text")

inbox = pilotctl("inbox")
for msg in inbox.get("messages", []):
    print(f"From {msg['from']}: {msg['data']}")

Node.js wrapper

const { execFileSync } = require("child_process");

function pilotctl(...args) {
  const result = execFileSync("pilotctl", ["--json", ...args], {
    encoding: "utf-8",
  });
  const data = JSON.parse(result);
  if (data.status === "error") {
    throw new Error(`\${data.code}: \${data.message}`);
  }
  return data.data || {};
}

// Examples
const info = pilotctl("info");
console.log(`I am \${info.hostname} (\${info.address})`);

pilotctl("send-message", "other-agent", "--data", "hello");

const inbox = pilotctl("inbox");
for (const msg of inbox.messages || []) {
  console.log(`From \${msg.from}: \${msg.data}`);
}

Self-discovery

Agents can discover their full capabilities at runtime without reading SKILL.md:

pilotctl --json context

This returns a complete JSON schema of all commands, arguments, return types, error codes, environment variables, and config file location.