Quickstart: two agents exchange a message

End to end in under 10 minutes: install spt-core, bring two agents online, and pass real messages between them — including one delivered while the receiver was offline.

This is the developer path. Building an adapter or integrating a harness? Go to the adapter quickstart instead.

Everything below uses real values and runs as written. You need two terminals.

1. Install (one line)

# Linux
curl -fsSL https://sabermage.github.io/spt-releases/install.sh | sh

# Windows (PowerShell)
irm https://sabermage.github.io/spt-releases/install.ps1 | iex

Verify (on Windows, open a new terminal first — or use the absolute path the installer printed):

$ spt --version
spt 0.1.0

2. Bring an agent online

In terminal B, become reachable as bob:

$ spt poll bob
READY:bob

poll registers a perch for bob (his identity + address on this machine), drains any backlog, and blocks listening. Leave it running.

3. Send him a message

In terminal A:

$ echo "hello bob - alice here" | spt send bob --from alice
SENT:bob

(Windows PowerShell: "hello bob - alice here" | spt send bob --from alice.)

Terminal B prints it immediately:

__REPLY_TO__:alice
hello bob - alice here

SENT means live delivery — bob was listening, so the message went straight to his terminal over a local connection. The __REPLY_TO__:alice line is the routing header: whoever receives this knows where a reply goes.

4. Deliver to someone who’s offline

Stop bob (Ctrl-C in terminal B), then send again from terminal A:

$ echo "ping while you were away" | spt send bob --from alice
QUEUED:bob

QUEUED means bob has a perch but isn’t listening — the message went to his durable spool instead of being dropped. Bring him back in terminal B:

$ spt poll bob
READY:bob
__REPLY_TO__:alice
ping while you were away

The backlog drains the moment he’s back. Nothing is lost between sessions.

5. What just happened

• Perch — registering as bob created a perch: a durable identity with an address and a spool, under spt-core’s per-machine home. spt list shows every perch on the node, live or not.
• Live-first, spool-fallback — send tries a direct connection to the registered address first (SENT); if the perch exists but no listener is up, the message lands in the spool (QUEUED) and is drained by the next poll/ready.
• Reply routing — the __REPLY_TO__ header travels with every message; spt send --reply-to alice answers the sender without knowing anything else about them.
• No daemon ceremony — you never started a server. Anything that needs the per-machine daemon auto-starts it on demand.

Next

• How-to: block on an answer with spt ring bob — send + wait for the reply in one call (a synchronous ask between agents).
• Concept: the mental model — perches, endpoints, the daemon, and subnets.
• Reference: spt send / poll / ring / list — every flag, generated from the binary itself.
• Going cross-machine: Networking & pairing — pair a second machine with a TOTP code and the same send reaches bob on the other box.