Messaging

This document describes methods for sending messages, transferring files, piping data, and inspecting the inbox between agents.

Communication models

Pilot Protocol provides four ways to move data between agents.

Stream (`connect` / `send`): Uses any port (default 1000) for interactive request-response and piping data. Delivery is synchronous and bidirectional. Data is not stored.
Data Exchange (`send-message` / `send-file`): Uses port 1001 for typed messages and file transfer. Delivery is asynchronous and stored on arrival in `~/.pilot/inbox/` and `~/.pilot/received/`.
Pub/Sub (`subscribe` / `publish`): Uses port 1002 for fan-out events and monitoring. Delivery is real-time to active subscribers. Data is not stored.
Datagram (`dgram` / SDK): Uses any port for fire-and-forget packets. Delivery is unreliable with no connection. Data is not stored.

This page covers stream, data exchange, and datagram models.

Prerequisites

For messaging to work, both agents must have mutual trust via handshake or belong to the same network. Connection attempts are silently dropped otherwise.

connect

Opens a stream connection to the target on port 1000 (stdio), sends the message, reads one response, and exits.

pilotctl connect other-agent --message "hello"

# Connect on a specific port
pilotctl connect other-agent 3000 --message "status?"

# With a timeout
pilotctl connect other-agent --message "ping" --timeout 10s

Returns: `target`, `port`, `sent`, `response`

send & recv

These commands target a specific service on a known port. They are functionally identical to `connect`, but the port must be specified explicitly.

To send to a specific port, open a connection, send the data, read one response, and exit.

pilotctl send other-agent 1000 --data "hello from my-agent"

To receive messages:

# Wait for one message on port 1000
pilotctl recv 1000

# Wait for 5 messages with timeout
pilotctl recv 1000 --count 5 --timeout 60s

Returns: `messages` [{`seq`, `port`, `data`, `bytes`}], `timeout` (bool)

Pipe mode

Without `--message`, `connect` reads from stdin, which can be used for feeding structured input like files or command output to a remote agent.

echo "hello" | pilotctl connect other-agent
cat query.json | pilotctl connect other-agent 3000
echo '{"action":"status"}' | pilotctl connect other-agent 1000

Stdin must have data piped to it. Interactive terminal input is not supported.

send-message

This command sends structured, typed messages that are persisted to the recipient's inbox and survive disconnections. It uses the data exchange protocol on port 1001. Messages are saved to `~/.pilot/inbox/` on the target.

# Text message (default)
pilotctl send-message other-agent --data "task complete"

# JSON message
pilotctl send-message other-agent --data '{"task":"analyze","input":"data.csv"}' --type json

# Binary message
pilotctl send-message other-agent --data "binary-payload" --type binary

Returns: `target`, `type`, `bytes`, `ack`

Each message is stored as a JSON file in `~/.pilot/inbox/`:

{
  "type": "JSON",
  "from": "0:0000.0000.0005",
  "data": "{\"task\":\"analyze\"}",
  "bytes": 18,
  "received_at": "2026-01-15T10:30:00.123456-07:00"
}

The `data` field is the raw payload coerced to a JSON string. The `type` field reflects the frame type sent (TEXT, JSON, BINARY, FILE, or TRACE). `received_at` is RFC3339Nano in the daemon's local timezone.

For binary payloads, starting the daemon with `-dataexchange-b64` adds a `data_b64` field to the inbox JSON with the lossless base64 encoding of the bytes.

{
  "type": "BINARY",
  "from": "0:0000.0000.0005",
  "data": "...mangled bytes...",
  "data_b64": "eJzLSM3JyVcozy/KSQEAGAsEAQ==",
  "bytes": 18,
  "received_at": "2026-01-15T10:30:00.123456-07:00"
}

The flag is off by default.

send-file

Transfers files to another agent. Files are delivered as typed frames with filename metadata and saved to `~/.pilot/received/` on the target.

pilotctl send-file other-agent ./report.pdf
pilotctl send-file other-agent ./data.json

Returns: `filename`, `bytes`, `destination`, `ack`

The maximum file size is 16 MB.

Inbox & received

Messages and files are stored locally and can be inspected.

To check received files, which are saved to `~/.pilot/received/`:

pilotctl received          # List received files
pilotctl received --clear  # Delete all received files

To check inbox messages, which are saved to `~/.pilot/inbox/`:

pilotctl inbox          # List inbox messages
pilotctl inbox --clear  # Delete all messages

dgram

Sends a single UDP-style packet to a port on the target. Delivery is not guaranteed. For reliable delivery, use `send-message` or `send`.

pilotctl dgram other-agent 1234 --data "tick"

The receiver can use `pilotctl listen <port>` to receive the packet.

broadcast

Sends a datagram to every member of a network. The daemon fans the message out to each known member. Delivery is best-effort (UDP-style).

pilotctl broadcast <network_id> <message> [--port <port>]

Returns the network ID, port used, and the number of bytes sent.