> Source: https://nexusatlas.dev/docs/3.0.0/concepts/interconnect — Nexus Atlas developer documentation (Concepts). Converted from the HTML page; the page is canonical.

# 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](https://nexusatlas.dev/guides/one-network) 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 its entries in either or both modes: an address map ([[peer.interconnect.map]], which of the other network's hosts appear here and under which address of this network) and routed prefixes ([[peer.interconnect.route]], prefixes of the other network reached by their real addresses). |
| export | This network's hosts that take part — the only ones the other side can reach, and the only ones that may send across. |

## Mapped mode — the far host inside your own subnet

Mapped mode asks nothing of members, the mobile app included, whose address space is fixed. 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. Members need no seam configuration of their own.

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

## Prefix mode — the other network's members, by real address

When many of the other network's members must be reachable by the addresses they already use, the seam imports a prefix of that network instead of mapping hosts one by one. Nothing is rewritten in either direction, and far members see the caller's real address.

- **Both sides list it.** A prefix crosses only when one side has it as a `route` and the other side has it in its `export`, for each direction: egress needs the destination in this side's routes and the source in its export; ingress needs the source in this side's routes and the destination in its export. The far seam daemon imports this network's prefix with its own route entry, which is the reply path.

- **Advertised, then installed.** The seam daemon carries each imported prefix in its signed link-state adverts. Every member's daemon publishes the learned prefixes and, with `[routing] install_learned_routes` (on by default), installs `<prefix> dev <tun>` on a Linux tunnel interface it created — over netlink, with no helper process and no firewall rules — and removes it when no seam host advertises it any more. A prefix that overlaps a route already in the member's main table (other than the default route) is skipped and logged once with the conflicting route.

- **Members, not LANs.** What is routed is the other Atlas network's own members. There is no subnet-router role: a LAN of hosts that do not run Atlas, behind a node, is not routed. Phones, whose address space is fixed, reach the other network through mapped mode.

Both modes can share one `[peer.interconnect]` block; the export list, the isolation of the control planes and the no-chaining rule apply to every entry alike.

## What the seam host's record allows

In a network that runs a fleet list, a seam host's adverts are signed against its node record. The record also bounds what those adverts may carry: its `interconnect` extension lists `may_import` — the routes, and the mapped `local` addresses, the node may announce from another network — and `may_export` — this network's hosts it may expose. The network's owner writes and signs it like every other permission in the record.

- **Deny by default.** A record without the section imports and exports nothing, and an empty list means nothing. Anything is written `0.0.0.0/0`.

- **Whole entries, inside one listed prefix.** An announced prefix is allowed when it lies entirely inside one listed prefix. A wider announcement is refused whole, not narrowed: `10.0.9.0/24` against `may_import = ["10.0.9.0/25"]` is not routed at all.

- **Checked on every member.** Each member filters a seam host's advert by that host's record. Its own addresses, inside its `allowed_ips`, are routed as before; routes and other served prefixes only inside `may_import`. The rest are not routed, logged once and counted.

- **Applied on the seam host.** The seam host holds itself to its own record in the data path: a route or map outside `may_import` is not carried either way, and an `export` entry outside `may_export` is not exported.

- **Live.** A newer list that shrinks the record takes effect on the seam host and on every member within one advert pass, without a restart.

- **The seam peer needs no record here.** The other network's daemon is admitted by the seam host because it is configured as that host's interconnect peer; members never peer with it.

Networks without a fleet list are not limited — there are no records to check against. The record format and its rollout rule are on [Identity and authorisation](https://nexusatlas.dev/docs/3.0.0/concepts/identity#extensions); the [interconnect guide](https://nexusatlas.dev/guides/interconnect#records) sets one up.

## What crosses the seam, and what never does

| Crosses | Never crosses |
|---------|---------------|
| Data between exported hosts and mapped or routed 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 or imported 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 or imported prefixes: every member picks the same owner for each, preferring a reachable one, so when that host disappears the other seam carries the traffic within seconds, in either mode. Imported routes leave the members about two minutes after the last seam host goes. A seam host never learns a prefix it imports itself. Fifty echoes sent through two seams come back exactly once each.

## What config check refuses

- A remote or a routed prefix that overlaps this network's own subnet — two networks that share an address space cannot be interconnected, in either mode.

- A route that overlaps a mapped address or another route, an IPv6 route, a route outside the peer's `allowed_ips`, a route without an `export`, and a block with neither map nor route.

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

- In a record fleet, a route, map or export outside this node's own [record](https://nexusatlas.dev/docs/3.0.0/concepts/interconnect#record), naming the record and its lists.

## Seeing it

`atlasd status` lists each seam with its map, its imported routes, its export list, packets and bytes each way (routed packets counted separately), and refusal counters; on every member it lists the learned routes with the seam host, next hop, how long each has been held, how many seam hosts advertise it, and the kernel route's state. The dashboard's Mesh & Routes tab shows them in a Learned routes table. A daemon with a seam configured advertises `interconnect` in its handshake, and nothing crosses a seam whose far daemon does not: that refusal is counted `interconnect[].dropped_no_cap`. 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.

In a record fleet, `atlasd status` on the seam host prints what its record allows and every configured entry outside it, and members print the imports they refuse. The snapshot carries `interconnect_record`, per seam `refused_routes`, `refused_maps`, `refused_export` and `dropped_by_record`, and on members `interconnect_imports_refused` with a row per refusal, also per announcing member in `members[]` (see the [REST API](https://nexusatlas.dev/docs/3.0.0/api#stats-interconnect-record)).

## Boundaries

- 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. In mapped mode, ICMP error messages generated inside one network carry the untranslated header of the packet that caused them.

- Two networks that share an address space cannot be interconnected.

- Prefix mode routes the other network's members, not LANs of non-Atlas hosts; member routes are installed on Linux.

Ready to build one? The [interconnect guide](https://nexusatlas.dev/guides/interconnect) walks the two-daemon setup end to end.