Built-in Services

Three services run automatically when the daemon starts. No extra binaries are needed.

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). Those 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. It has no application logic.

Data Exchange (port 1001)

A typed frame protocol that handles structured data transfer. Messages arrive in the recipient's `~/.pilot/inbox/`, and files in `~/.pilot/received/`. Both persist until the recipient reads or clears them. 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]`. Maximum payload size is 16 MB.

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

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. Events go only to currently connected subscribers. There is no persistence and no 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 := daemon.Listen(3000)
conn, _ := listener.Accept()

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. They are not forwarded by `pilotctl daemon start`. To disable a built-in service, invoke `pilot-daemon` 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 adds a lossless `data_b64` field to inbox messages for binary payloads. It is off by default.