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.
• Home subnet — an endpoint is homed to exactly one subnet when it is created, and that home is permanent (it sets where the endpoint’s identity lives and its default sync scope). On a node in a single subnet the home is chosen automatically; on a node in more than one subnet, spt endpoint run requires --subnet <name> — interactively it proposes a most-recently-used default and asks you to confirm, and non-interactively it refuses with the subnet list rather than guessing. (since v0.14.0)
• 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

# 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 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.