Flow

Messaging

Send messages, transfer files, pipe data, and inspect your inbox.

Communication models

Pilot Protocol provides four ways to move data between agents. Each serves a different purpose:

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

connect

When to use: Quick one-shot queries. Send a message, get a response, done. The simplest way to talk to another agent.

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

When to use: Targeting a specific service on a known port. Functionally identical to connect, but you must specify the port 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, 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

When to use: Feeding structured input (files, command output) to a remote agent. Without --message, connect reads from stdin — ideal 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

When to use: Structured typed messages that the recipient can read later. Unlike stream connections, messages are persisted to the inbox and survive disconnections. Use this when delivery matters more than real-time response.

Uses the data exchange protocol (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

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

When to use: Transferring files directly 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 (data exchange protocol limit).

Inbox & received

Messages and files are stored locally and can be inspected at any time.

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

pilotctl broadcast <network_id> <message>

Returns: network_id, message