Atlas Interconnect opt-in · default off
An Atlas network is sealed: its own keys, its own address space, its own control plane, and forwarding only among its own members. That is the right default, and it leaves two different jobs. When one operator owns every node, the answer is one network — fold everything into a single instance. When the networks belong to other people and the operator's job is only to join them, the answer is an interconnect: a seam between two networks that changes nothing on either side's members.
Layer 1 — one network where you can
A host may run several atlasd instances, one per config file, and nothing crosses between them. If the same operator runs both, that separation buys nothing and costs a lot: each instance keeps its own sessions on the same physical links, probes them separately, and draws its own topology, so two radios appear as four links. The fix is configuration, not a feature: keep one instance, give it every link and every peer, and park the other. The one-network guide is the procedure. This is how the product is meant to be used whenever every node is yours.
Layer 2 — a seam between networks you do not run
A partner runs a drone network; an agency runs a sensor mesh. The operator is admitted to each as an ordinary member, under that owner's rules, and wants hosts on one side to reach hosts on the other — without asking either owner to change a single device. The operator runs one daemon per network on one host, as it already would, and makes the two daemons peers of each other over a loopback link:
| Piece | What it is |
|---|---|
[[link]] type = "local" | An ordinary link that may only bind to loopback; config load refuses anything else, so a seam can never end up on the wire. It joins two daemons on the same host. |
[[peer]] with [peer.interconnect] | The other daemon, as a peer on that link, plus an address map: which of the other network's hosts should be visible here, and under which address of this network. |
export | This network's hosts that take part — the only ones the other side can reach, and the only ones that may send across. |
Address maps, not imported routes
Members of an Atlas network route nothing outside their own subnet: atlasd gives the tunnel interface its address and its /24 and installs no routes, and the mobile app's address space is fixed. So the seam does not ask members to learn the other network's prefix. Instead, each remote host the operator maps gets an address inside this network's own subnet, and the seam daemon advertises that address in its link-state flood as an address it serves. Every member reaches it with exactly what it already has — its own subnet route into the tunnel and the shortest-path tree it already computes — including members on older builds.
- Egress. A packet for a mapped address reaches the seam daemon like any packet for a node; the daemon rewrites the destination to the host's real address in the other network and sends it across the local link.
- Ingress. A packet arriving from the other daemon must come from a mapped host and go to an exported host. The daemon rewrites the source to the host's local address, then routes it into this network exactly as if its own host had sent it.
- Checksums. IPv4 header and TCP/UDP checksums are repaired incrementally, so applications see nothing but an ordinary peer at an ordinary address.
Each side describes how the other network looks to its own members. The operator of network A decides where B's hosts appear in A's address plan, and vice versa — nobody renumbers anybody.
What crosses the seam, and what never does
| Crosses | Never crosses |
|---|---|
| Data between mapped and exported hosts, in both directions | Link-state adverts, full topology exchanges, membership gossip |
| Probes on the local link, so each daemon knows the seam is up | Keys, admission decisions and configuration pushes |
| Traffic toward a mapped address arriving from the other side — seams do not chain |
Neither network learns the other's topology: the seam is not even listed as a link in either flood. Each daemon remains an ordinary member of its own network, so each owner can revoke the operator like any other member; revoking it on one side ends the interconnect at once.
Two seams, no loop
Nothing is redistributed between networks, and a packet that crossed a seam is never sent across another, so loops cannot form by construction. Two operator hosts bridging the same pair give two parallel seams that advertise the same mapped addresses: every member picks the same owner for each address, and when that host disappears its adverts expire and the other seam carries the traffic. Our verification rig confirmed it: fifty echoes through two seams, each answered exactly once.
What config check refuses
- A remote prefix that overlaps this network's own subnet — two networks on the same address space can be joined only by mapping hosts, never by their overlapping subnet.
- A local address outside this network's subnet, on this node's own address, or on another peer's address.
- A remote and local of different prefix lengths, a remote outside the peer's
allowed_ips, and two maps whose local addresses overlap. - A
type = "local"link bound to anything but loopback.
Seeing it
atlasd status lists each seam with its map, its export list, packets and bytes each way, and refusal counters. The snapshot carries the same as an interconnect section, the Mesh & Routes tab shows an Interconnect card, and Full Topology badges the operator's node as a seam between the two instances.
Current limits
- End-to-end payload encryption is hop-by-hop across the seam: the seam daemon owns the mapped address, so it opens a sealed payload and seals it again for the far side.
- IPv4 only. ICMP error messages generated inside one network carry the untranslated header of the packet that caused them.
- Failover between two operator hosts waits for the first host's adverts to expire — up to about 100 seconds.
Ready to build one? The interconnect guide walks the two-daemon setup end to end.