Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quickstart: two agents exchange a message

End to end in under 10 minutes. The roles matter here: you install (and optionally pair machines); your agents exchange the messages. You hand each agent a short prompt; the binary itself teaches them the rest.

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.

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

Everything below also works on a single box — skip ahead freely. But the product’s hallmark is that the same commands work across machines once they share a subnet.

Pair a second machine into a subnet (one-time, ~2 minutes)

On your first machine, create the subnet. This reveals its joining secret, so it needs elevation — just run it directly and spt requests elevation for you (a sudo password prompt on Linux/macOS; run the terminal as Administrator on Windows):

spt subnet create home

It prints the current 6-digit code, an otpauth:// URI (scan the QR into an authenticator app for codes anytime), and the next step.

Running non-interactively (no TTY to prompt on)? spt instead prints the exact elevated command to copy-paste — it uses the binary’s absolute path so a user-local install (~/.local/bin) still resolves under sudo.

On the second machine, join it (this enrolls the machine, so it elevates the same way):

spt subnet join home

It searches LAN + relay for your first machine, prompts for the current code, and confirms: JOINED:home. Check from either side:

spt subnet status --nodes

Both machines show up, labeled by hostname. That’s it — the same prompts below now work across machines: a spt send sergey on machine 1 reaches a sergey listening on machine 2, live or spooled.

3. Hand your receiver agent its prompt

Paste this into an agent session (your “receiver” — we call it sergey):

Run `spt how-to ready`, then follow it to become reachable as "sergey"
and stay listening.

The binary’s own guidance (spt how-to ready) tells the agent exactly what to run and what it will see. Under the hood, the agent starts:

$ spt ready sergey
READY:sergey

ready registers a perch for sergey (identity + address on this machine), drains any backlog, and blocks listening.

4. Hand your sender agent its prompt

Paste this into a second agent session (the “sender” — lea):

Run `spt how-to send`, then follow it to send the agent "sergey" a
greeting from "lea".

What the agent runs:

$ echo "hello sergey - lea here" | spt send sergey --from lea
SENT:sergey

(Windows PowerShell: "hello sergey - lea here" | spt send sergey --from lea.)

Sergey’s session prints it immediately:

<EVENT type="msg" from="lea">hello sergey - lea here</EVENT>

SENT means live delivery — sergey was listening. Each delivery is one <EVENT> envelope line; the from="lea" attribute is the routing handle: whoever receives this knows where a reply goes (spt send lea). Bodies are HTML-escaped with newlines as <br>; oversized deliveries split into <EVENT-PART> lines the receiver concatenates back.

5. Deliver to someone who’s offline

Stop sergey’s listener (Ctrl-C in his session), then send again from lea:

$ echo "ping while you were away" | spt send sergey --from lea
QUEUED:sergey

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

$ spt ready sergey --once
READY:sergey
<EVENT type="msg" from="lea">ping while you were away</EVENT>

The backlog drains the moment he’s back (--once drains and exits — the one-shot form spt how-to ready teaches agents whose harness can’t host a long-running listener). Nothing is lost between sessions.

6. What just happened

  • Perch — registering as sergey 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 ready.
  • Reply routing — the sender id travels with every message structurally, surfaced as the arriving <EVENT from="…"> envelope’s from attribute; spt send lea answers the sender without knowing anything else about them.
  • Agents teach themselves — the prompt blocks point agents at spt how-to <topic>: task guidance shipped in the binary, so what an agent reads can never disagree with the binary it runs.
  • No daemon ceremony — you never started a server. Anything that needs the per-machine daemon auto-starts it on demand.
  • Subnets carry it across machines — if you did step 2, these same flows ride the paired P2P fabric: same commands, same outputs, machine boundaries invisible.

Next

  • How-to: block on an answer with spt ring sergey — 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 / ready / ring / subnet — every flag, generated from the binary itself.
  • Going cross-machine: Networking & subnets — the model behind spt subnet create / join / status.