# Supgang architecture > How your computers share changing addresses, verify each other, and find one another again. - **Project:** [Supgang](https://agenxy.org/projects/supgang/) - **Status:** Alpha, unreleased - **Revised:** 2026-10-22 --- A home internet provider can change your public IP address without warning. A laptop gets a different address on each new network. The saved address then no longer leads to the computer. Most solutions keep the new address on a company's server. Supgang keeps it among computers you control. There is no central copy, account, public directory, or vendor-operated relay. ## The idea Each computer has a permanent cryptographic identity, independent of its name or IP address. Periodically it makes a small signed note: who it is, and the addresses where it can be reached. Supgang calls this an **address record**. The signature lets another member verify which computer wrote the record and that nobody changed it in transit. Connected members compare what they know and pass along newer records. A computer that moves writes a new record; any member that receives it passes it on.
1The laptop movesIts old public address goes stale.
2One saved path still worksThe laptop reaches the home computer.
3Home verifies the updateThe signature proves which computer wrote it.
4Home carries it onwardOther peers learn the laptop's new address.
The laptop needs no direct path to every member. One surviving connection carries its new address through the group.
Governing limit: a new record travels only over a path that still exists. If every path disappears, Supgang keeps retrying; it cannot invent a route through the internet. Supgang does not carry application traffic. It finds and verifies a computer; SSH, file sharing, or another application makes the connection. ## What a computer shares An address record contains only what another member needs to identify the computer and try to reach it.

Address record

Computer
A permanent identifier derived from its public key
Name
A human-readable label, never used as proof of identity
Version
A number that increases, so every member can tell which record is newer
Valid until
When other members must stop trusting this copy
Addresses
Up to eight current places to try, each labelled by where it came from
Proof to expect
A short code for the credential the computer must show when reached; a substitute is rejected

Signed by this computerOther members can verify the record. They cannot alter or forge it.

Each computer publishes one current record and replaces it when its addresses change.
Addresses come from four sources: - **Local addresses**: read directly from the operating system. Useful when two computers share a network. - **Direct public addresses**: belong to the computer and are routable across the internet. Common with IPv6, uncommon with IPv4. - **Router-mapped addresses**: the local router is asked to send one public port to Supgang. Supgang uses UDP; some networks and firewalls block it entirely. The router may support PCP, NAT-PMP, or UPnP, three standard ways for software to request a temporary port mapping. The request stays on the local network. - **Peer-observed addresses**: the public source addresses an authenticated member sees when traffic arrives. Supgang calls no outside “what is my IP?” service. Every address is a place to try, not proof that it works. A mapping reported by the router stays unverified until another authorised computer connects through it. Old records are kept as bounded recovery hints, never shown as the computer's current address. ## How computers find one another again Recovery follows a fixed order. Inexpensive, likely paths come first; paths that need another computer come later.
  1. 1Use the open connectionA live session carries the new record immediately.
  2. 2Race the published addressesTry its newest addresses almost together, including any router-created mapping.
  3. 3Retry addresses that worked beforeAn older route may still lead to a fresh record.
  4. 4Have both sides try togetherCoordinated attempts can open a temporary path through both routers.
  5. 5Ask a mutual peerA member connected to both sides introduces them using the addresses it sees.
  6. 6Use your own anchorAn optional, reachable computer you control keeps more peer connections alive.
Supgang works down the list until a path succeeds. Every step requires at least one usable route.
Addresses are raced, not tried one at a time while a dead address times out. Supgang keeps a bounded history of addresses that worked before: sixteen per peer by default, so recovery has more than one old lead. Simultaneous attempts work because many routers reject unsolicited incoming traffic but briefly admit replies after a computer sends something out. Supgang gives both computers the same retry window, so each sends while the other's router may admit the reply. This is **NAT traversal**: establishing a direct path through routers that share one public address among several local devices. A mutual peer can help when it has authenticated connections to both computers. It tells each side the source address it directly observed for the other; both then try at once. The introduction is short-lived and single-use, and is never saved as a trusted current address. This path requires at least three members: the two being connected and their mutual peer. ## The optional anchor An anchor is an ordinary Supgang member on an always-on computer you own, such as a machine at another site or a small server in your own cloud account. It must already have an address the other members can reach.
Your anchorAddress updates and introductions only
Your laptop
your SSH or file transfer (not Supgang)
Your home computer
The anchor helps the laptop and home computer find each other. It never carries their application traffic; that travels directly or not at all.
The anchor runs the same protocol in a mode built to receive connections rather than chase them, and keeps more authenticated connections open. A new address then has more places to travel, and two peers are more likely to share an introducer. It does not accept public membership, publish a directory, or relay SSH, files, or other general traffic. An anchor is optional. It strengthens a fleet whose mobile members often lose every direct connection. An unreachable anchor helps nobody. ## How a connection becomes trusted Reaching an address proves only that something answered there. Supgang does not call a peer connected until both sides prove their identities on that specific connection. The connection uses **QUIC** over UDP with **TLS 1.3**. The answering computer presents a certificate. Its expected fingerprint is in the signed address record, so a substituted certificate is rejected. Both computers then sign a fresh, one-time challenge tied to this exact encrypted connection; a captured proof from an earlier connection cannot be replayed. Names and nicknames are conveniences for humans. Keys and signatures decide who is trusted. Signatures use **Ed25519**. Records use canonical **CBOR**, a compact binary format similar in purpose to JSON. Canonical means the same record has only one accepted encoding, so the bytes a signature covers are unambiguous. Malformed, oversized, contradictory, or unfamiliar records are rejected. ## What runs on each computer One unprivileged program owns the network connection and local state. `supgang run` operates in the foreground or as a per-user background service through launchd on macOS or systemd on Linux. The other commands reach it through a local socket that only the same user can open. The first member creates the group, called a **hive**, and holds the root key that approves new members and revocations. Each joining computer creates its own device key; the private half never leaves that computer. Joining is an offline exchange the user carries by a trusted method, such as a removable drive or local file transfer. The root key is held in an owner-only file on the founding computer. Hardware-backed storage, offline-root operation, and root recovery are not yet implemented. With automatic router mapping disabled, Supgang communicates only with your authorised computers. With it enabled, the only additional traffic is a mapping request to the attached local router. The founding computer can revoke a member; a revoked computer stops and refuses to start again with that identity. ## Where it stops Supgang improves the odds of reconnection. It guarantees no path through every network. - A carrier-grade NAT can put many customers behind infrastructure their home router cannot control. Common on mobile networks. - Some routers do not support automatic mapping, and some networks assign a different public port for every destination. Peer introduction may fail on those networks. - A firewall or network that blocks UDP blocks the connection. - Two isolated computers that both move to unknown addresses, with no third authorised member reachable, cannot learn each other's new address. ## Current status Published 0.1.0 is not a working wide-area release. Unreleased 0.2.0 alpha adds address racing, bounded history, simultaneous attempts, router mapping, peer introduction and the anchor role. Two Macs passed cross-network testing over IPv4 through an owner-configured port forward. Later tests showed roaming reconnection in about 7 seconds, transatlantic reconnection and an IPv6 path. Unproven: Linux runtime; routes without an owner-configured forward; recovery after the home's public address changes; NAT traversal without a forward; and field use beyond two devices. There is no relay or rendezvous. Source: https://agenxy.org/projects/supgang/architecture/