# 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](adapter.md) instead.
Everything below uses real values and runs as written.
## 1. Install (one line)
```sh
# Linux
curl -fsSL https://sabermage.github.io/spt-releases/install.sh | sh
```
```powershell
# 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):
```console
$ spt --version
spt 0.1.0
```
## 2. Optional: link two machines
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):
```sh
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):
```sh
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:
```sh
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`):
```text
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:
```console
$ 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`):
```text
Run `spt how-to send`, then follow it to send the agent "sergey" a
greeting from "lea".
```
What the agent runs:
```console
$ 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:
```text
hello sergey - lea here
```
`SENT` means live delivery — sergey was listening. Each delivery is one
`` envelope line; the `from="lea"` attribute is the routing handle:
whoever receives this knows where a reply goes (`spt send --reply-to lea`).
Bodies are HTML-escaped with newlines as `
`; oversized deliveries split
into `` 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:
```console
$ 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:
```console
$ spt ready sergey --once
READY:sergey
ping while you were away
```
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 `` envelope's
`from` attribute; `spt send --reply-to lea` answers the sender without
knowing anything else about them.
- **Agents teach themselves** — the prompt blocks point agents at
`spt how-to `: 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](../concepts/overview.md) — perches,
endpoints, the daemon, and subnets.
- **Reference:** [`spt send` / `ready` / `ring` / `subnet`](../cli/reference.md)
— every flag, generated from the binary itself.
- **Going cross-machine:** [Networking & subnets](../networking/overview.md)
— the model behind `spt subnet create` / `join` / `status`.