# Networking & subnets

Zero-config, no-central-server connectivity between your machines. Join two
nodes into a subnet once with a six-digit code; from then on, the same
`spt send sergey` works whether sergey is local or three networks away.

## The model

- **Node identity** — each machine holds an Ed25519 keypair; the public key
  *is* its network identity. Connections are mutually authenticated QUIC,
  end-to-end encrypted, peer-to-peer with NAT hole-punching and public-relay
  fallback (you can self-host the relay, or disable it for LAN/air-gapped
  use — the default relays carry only encrypted traffic they cannot read).
  Nodes also carry a human **label** (the hostname by default): views render
  `HFENDULEAM (bcead52b…)`, and `@node` qualifiers accept the label or a
  key prefix — several machines sharing a label are never guessed between.
- **Subnets** — machines join into named groups. A subnet shares: the
  endpoint registry (who exists, where, what state), context sync for its
  endpoints, notifications, and staged self-updates. Nothing is shared with
  nodes outside the subnet, ever.
- **Joining** — a one-time, code-authenticated ceremony. On a member
  machine, `spt subnet show-code` prints the current six digits (and an
  `otpauth://` URI — put the seed in your authenticator app); on the new
  machine, `spt subnet join <name>` finds a member over LAN + relay and
  runs the exchange. The code bootstraps a PAKE key exchange — the code is
  never the key, and a wrong guess learns nothing. Both sides pin each
  other's node keys on success (trust-on-first-use; key changes warn and
  never auto-apply). Every member machine answers join attempts
  automatically — no arming step on the existing fleet.
- **Elevation gates** — `subnet create` (reveals a fresh subnet's joining
  secret) and `subnet join` (enrolls the whole machine) require an elevated
  terminal; `subnet status` is read-only and ungated, and never prints
  secrets.
- **Visibility & sync scope** — per endpoint, per subnet: an endpoint can be
  hidden from a subnet (neither advertised nor routable) and its mind syncs
  only to subnets on its membership list. Both default conservative;
  unconfigured means *not shared*.
- **Resource registry** — endpoints may advertise a free-text service blurb
  (`spt endpoint description set` to author; `spt endpoint list --detail`
  to browse) — an agent yellow-pages over visible rows only.

## The walkthrough

```sh
# Machine 1 (elevated): mint the subnet — prints the code, an otpauth://
# URI, and a terminal QR.
spt subnet create home

# Machine 2 (elevated): join it — searches LAN + relay, prompts for the code.
spt subnet join home

# Either side: who's in, and who's online.
spt subnet status --nodes
```

The [quickstart's pairing section](../quickstart/messaging.md) runs this
same flow inside the two-agent demo.

## What rides it

Cross-machine `send`/`ring`, registry replication, two-tier mind sync,
remote attach, remote suspend/wake, file transfer, notification replication,
and peer-propagated self-update — all over the same subnet substrate.

## Commands

`spt subnet` (`status` · `create` · `join` · `show-code` · `notify` ·
`attach`/`detach` · `leave` · `prune`) · `spt endpoint list --detail` ·
`spt endpoint description` · the qualified addressing forms
(`[subnet:]id[@node]`, where `@node` is a label or key prefix) —
[CLI reference](../cli/reference.md).