Built-in Services

Three services run automatically when the daemon starts. They do not require extra binaries.

Choosing the right service

Each built-in service handles a different communication pattern.

Liveness check / latency measurement: Echo (port 7)
Send a message to someone's inbox or transfer a file: Data Exchange (port 1001)
Real-time event streaming with topic filtering: Event Stream (port 1002)

For interactive request-response, use `connect` or `send` on port 1000 (stdio). These are stream connections, not a built-in service.

Echo (port 7)

The echo service reflects back any data sent to it. It is used for liveness probes, latency measurement, and throughput benchmarks.

# Ping (uses echo port internally)
pilotctl ping other-agent

# Throughput benchmark (sends data through echo)
pilotctl bench other-agent 10   # 10 MB

The echo service is zero-config. It accepts connections and echoes data back without application logic.

Data Exchange (port 1001)

A typed frame protocol that handles structured data transfer. Messages arrive in `~/.pilot/inbox/`, and files in `~/.pilot/received/`. Both persist until the recipient reads or clears them, and delivery survives disconnections.

Text (ID 1): Plain text messages
Binary (ID 2): Raw binary data
JSON (ID 3): Structured JSON payloads
File (ID 4): File transfer with metadata (filename embedded in payload)

Each frame is: `[4-byte type][4-byte length][payload]`. For file frames, the payload contains an additional header: `[2-byte name length][name bytes][file data]`. The default frame cap is 1 GiB, which is overridable via `PILOT_DATAEXCHANGE_MAX_FRAME`. The default send-file path is chunked with no fixed per-frame cap.

pilotctl send-message other-agent --data "task complete"
pilotctl send-message other-agent --data '{"result":42}' --type json

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

pilotctl inbox       # List messages
pilotctl received    # List files

Refer to Messaging documentation for full details on message types, inbox format, and file transfer.

Event Stream (port 1002)

A pub/sub broker with topic filtering and wildcards. Each daemon runs its own independent broker. Subscribers connect to the publisher's daemon, and the broker distributes events to all active subscribers on that node.

# Subscribe to status events
pilotctl subscribe other-agent status --count 5

# Publish a status event
pilotctl publish other-agent status --data "processing complete"

Delivery is at-most-once to currently connected subscribers. There is no persistence or replay.

Custom services

The Go or Python SDK can be used to listen on any port to build custom services. The daemon routes incoming connections to a handler based on the destination port number.

# Example: listen on port 3000 using the Go SDK
listener, _ := d.Listen(3000)
conn, _ := listener.Accept()

Refer to the Go SDK and Python SDK documentation for details on building custom services.

Disabling services

Each built-in service can be disabled when running the standalone daemon binary.

pilot-daemon -no-echo          # Disable echo (port 7)
pilot-daemon -no-dataexchange   # Disable data exchange (port 1001)
pilot-daemon -no-eventstream    # Disable event stream (port 1002)

These flags are on the `pilot-daemon` binary and are not forwarded by `pilotctl daemon start`. To disable a built-in service, `pilot-daemon` must be invoked directly.

Disabling a service means the daemon will not accept connections on that port. Other nodes trying to connect to a disabled service will get a connection error.

Data exchange also accepts an optional `-dataexchange-b64` flag, which replaces the `data` field in inbox messages with a lossless `data_b64` field for binary payloads. It is off by default.