Messaging

The substrate everything else rides on: durable, addressed, reply-routable messages between endpoints — live when the target listens, spooled when it doesn’t, across machines once nodes are paired.

You’ve probably already run the quickstart; this page is the model.

Semantics

• Live-first, spool-fallback. spt send <id> connects directly to a listening target (SENT); if the perch exists but nothing is listening, the message lands in the target’s durable spool (QUEUED) and drains on its next poll/ready. A target with no perch is an error (NO_PERCH) — identity is never invented on someone else’s behalf.
• Reply routing. Every message carries a __REPLY_TO__ header; spt send --reply-to <sender> answers without knowing anything else.
• The blocking ask. spt ring <id> sends and waits for the reply (with a timeout) — the synchronous question between agents.
• Deferred delivery. --deferred spools without waking a live listener: for context that should reach the agent at its next natural boundary rather than interrupting now. Deferred messages are also held for resting (dormant/suspended) instances and released exactly once on wake.
• Typed payloads. Message bodies carry typed operations and file blobs, not just text — file transfers are addressable and progress-queryable mid-flight.

Addressing

Bare ids (bob) resolve locally first, then across the subnet; when the same id is live on several nodes, resolution refuses and asks you to qualify (bob@desktop) rather than guessing. The full form is [subnet:]id[@node].

Commands

send · ring · ready · poll · list · stop · whoami — every flag in the CLI reference.