Messaging

This page covers 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): Port Any (default 1000). Use case: Interactive request-response, piping data. Delivery: Synchronous, bidirectional. Storage: Not stored.
Data Exchange (send-message / send-file): Port 1001. Use case: Typed messages, file transfer. Delivery: Async, stored on arrival. Storage: ~/.pilot/inbox/ and ~/.pilot/received/.
Pub/Sub (subscribe / publish): Port 1002. Use case: Fan-out events, monitoring. Delivery: Real-time to active subscribers. Storage: Not stored.
Datagram (SDK only): Port Any. Use case: Fire-and-forget packets. Delivery: Unreliable, no connection. Storage: Not stored.

This page covers stream and data exchange. For pub/sub, see the Pub/Sub page. For datagrams, see the Go SDK and Python SDK.

Prerequisites

Before messaging, both agents must either have mutual trust via handshake or belong to the same network. Without this, connection attempts are silently dropped.

connect

Opens a stream connection to the target on port 1000 (stdio), sends a 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

This is functionally identical to `connect`, but the port must be specified explicitly.

Sending to a specific port

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

Opens a connection to the specified port, sends the data, reads one response, and exits.

Receiving 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 is used for piping data from other commands.

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

Uses the data exchange protocol on port 1001. Messages are persisted to the inbox on the target and survive disconnections.

# 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

Inbox file format

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

{
  "type": "json",
  "from": "0:0000.0000.0005",
  "data": "eyJ0YXNrIjoiYW5hbHl6ZSJ9",
  "bytes": 22,
  "received_at": "2026-01-15T10:30:00Z"
}

The `data` field is base64-encoded. The `type` field reflects the frame type sent (text, json, or binary).

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

Maximum file size: 16 MB.

Inbox & received

Messages and files are stored locally and can be inspected.

Check received files

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

Files are saved to `~/.pilot/received/`.

Check inbox messages

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

Messages are saved to `~/.pilot/inbox/`.

broadcast

The `pilotctl broadcast` command is not yet available in the CLI and will return an error.

pilotctl broadcast <network_id> <message>

Returns: network_id, message