The networking and topology model

Polari does not treat "the network" as one thing. A device sits on an isle, isles can federate into an archipelago, and beyond that lies a zero-trust mesh. Every capability, budget and timeout is a property of the path to one specific place right now, never of the network as a whole. This page is the model behind all of it.

Audience

Anyone running or extending an isle; network engineers evaluating the design

Companion

Isle VPN covers the tunnel providers and their placement

The isle

An isle is your own local network, made deliberately: a VLAN carved on top of the normal LAN by a small OpenWrt router that runs as a virtual machine on the host. The router owns the subnet, hands out addresses, and serves names. Every device on the isle is a full member of a private LAN and fully trusted there.

Names and containment

Devices announce themselves with mDNS; the router's join protocol turns what it sees into DNS records, so a device is reachable as name.local and name.isle. The .isle namespace never leaves the isle. "Exposing" an app to the outside never moves it; it grants an additional outside URL through a dedicated gateway container, with authentication, and only once the isle's entrypoint has been enabled by its owner.

The agent proxy is the policy

Each device runs an isle agent whose nginx is the sole ingress for that device's apps. The proxies are generated from the device's registry, and Polari derives the protocol matrix from those proxies: which app permits http, https or mutual-TLS https, per device. What the proxies allow is the policy; there is no second list to drift out of sync.

Connectivity modes and uplinks

A device is either sole-isle (it lives on the isle and nothing else) or dual-home (internet and isle at once, with the separation enforced). Dual-home is first-class, not a workaround. Uplinks are typed per device (ethernet, wifi, usb-wifi) and measured (latency, jitter, loss, link state), so a topology page can say what a device is actually connected through.

Availability

The default availability mode is always available: the isle survives reboots unattended, with no interactive login in the way. On-demand modes, where parts of the isle come up when asked and go down when idle, build on the same control plane and are the keystone for the more elaborate modes.

Devices, tiers and hardware guests

Devices join with an agent in one of two roles. A core hosts the router and can create the isle; a remote joins one. Beyond the role, a device declares a tier that bounds what can be placed on it:

A hardware app is a guest of its own with a declared shape: image, memory, CPUs, the bridges it attaches to, what it needs passed through, and either an OpenWrt UCI profile or a provisioner script. The router is the first such guest, woven into the isle. The isle relay is a second OpenWrt guest that extends the isle across its own WiFi segment; the guest network is an isolated segment with client isolation and an allow-list. A hardware extension app rides inside an existing guest rather than being one: the Reticulum bearer in the relay, a print camera in a printer guest, a VPN gateway in the router. A hardware map scans a host's ports and slots and says what can be mapped to which potential guest before anything is defined.

The exposure ladder

An app is not "public" or "private". It is exposed rung by rung, each rung a deliberate enablement, and the default is always the most restrictive. Exposure is a row that names the app, the rung, the scope and our role toward the app at that rung, and it can be switched off at will.

Two rules keep the ladder honest. A rung only appears as an option when the thing that makes it real is installed: .vpn exists on a device only when a gateway-kind VPN app is registered there. And an app can hold exposure rows at several rungs at once, each stating our role: server, user, observer, or relay-only.

The archipelago

An archipelago is a set of isles meshed as one network, fast enough that a site on another isle loads directly under an .arch name. The picture is a farmers' market: vendors mesh their isles so customers move between stalls as if on one network. The transport underneath is Reticulum, a self-configuring, encrypted, bearer-agnostic packet network that runs over WiFi, ethernet, LoRa, or a serial link alike.

Membership is measured, not declared

A node is in an archipelago only while its measured path meets the archipelago's service floor: round-trip time, loss and bitrate against thresholds (defaults 150 ms, 1 percent, 1000 kbps, to be tuned). Reachability is a measurement with a timestamp, kept separate from trust. A trusted node below the floor is still trusted, but its .arch names render as slow and no site is promised to load. When an archipelago app slips under the floor, the system suggests a change, converting the app to a mesh app or adding relays, and never changes anything silently.

A path, not a network

The same Reticulum network is fast in places and slow in others, and a multi-hop path is as slow as its worst hop. So every measurement is keyed on the path to a specific destination, with hop count and the worst hop named, and every decision reads that path at send time: encoding, forward error correction versus retransmission, snapshot versus delta, admission, and timeout. Timeouts are derived from measured round-trip time with a margin, never constant. Capability is answered per peer, with the number: streaming no, this path is 1.2 kbps at four hops; small messages yes. Stale measurements are not measurements; past a freshness horizon the honest answer is "unknown, measure first".

Trust is graded and never means write

Trust on an archipelago node is a grade, not a boolean, and it says what that peer may ask for. A higher grade may raise the auto-approval level for named low-authority operations such as telemetry ingest, never for irreversible ones. "Extension of our isle" describes routing and naming, not authority: every change still arrives as a proposal.

Traffic classes and the right to relay

Reticulum has no traffic classes of its own, so the split is ours, enforced in our maintained fork at the forwarding decision and the per-bearer outbound queue. Four classes: control (announces, path requests, keepalives, always forwarded), baseline messaging for anyone, mesh-app data, and archipelago app streams. Classification keys on the destination hash learned from announces; payloads are end-to-end encrypted and never inspected. Use and relay are two separate knobs per isle, per app kind and per bearer, so a household can relay a neighbour's app it never runs, or run a heavy app it refuses to relay. Duty cycles and airtime budgets cap what a bearer may transmit, and nothing transmits on a radio until its legal basis is confirmed and recorded.

The mesh

The mesh is the zero-trust tier. A mesh app has a broadcast core, a relay that fans out the app's current state, and optionally some prior states, to consumers who are tracked only by their Reticulum identity hash. Consumers are not peers and are not trusted: they receive state and send returns, and nothing they send changes anything except through the same proposal seam everyone else uses. Consumers may optionally link an identity on the app's own login server; a mode that requires enrolment deliberately does not exist, because a zero-trust tier that demands enrolment is not zero-trust.

Two accountability mechanisms ride with every relay. Adaptive cadence: the publisher paces itself to what consumers collectively demonstrate, clamped by an airtime floor and a staleness ceiling, and every adjustment names the numbers that drove it. User census: how many users should exist versus how many distinct identities were seen in the window, reported as a finding, because a relay that silently gains a thousand consumers is a problem worth naming.

The VPN rung

Between the archipelago and the mesh sits the VPN: point-to-point and hub tunnels for devices and isles that are elsewhere, run by the isle itself with two providers and ten purpose-named kinds, placed as router extensions, guests of their own, or containers depending on what each carries. It has its own page: Isle VPN.

Who is in charge of what

• The isle is authoritative over networking. Names, addresses, firewall zones, tunnels and exposure are decided on the isle. Polari holds a mirror of that state, fed by the isle's own pushes, and an inbox of proposals that a local operator applies. Configuration APIs bind to isle-local addresses and refuse requests arriving over a tunnel or from outside the isle.
• Consent is a row both sides keep. Joining, federating, or becoming a VPN member starts as a request; a person on the isle approves it, and the approval mints a scoped, revocable token. Nothing is auto-admitted.
• Keys never leave the device that made them. Private keys and certificates are generated where they are used. Public material rides the push to Polari; proposals never carry secrets.
• No free-text hooks. Where a tunnel needs a firewall or routing change, the change is a named toggle rendered from a template: forward, masquerade, route-add. Exits and forwarding are off until turned on.
• Blind by default. Anything that forwards traffic for others holds no keys and sees no plaintext unless it is a hub you own on hardware you own, and every such row is labelled sees traffic or blind so nobody mistakes one for the other.

What Polari adds on top

Polari's side is the model, the mirror and the views. Machines, instances, and the assignment of modules to instances are rows; placement is recorded as an observation against that intent, so drift shows up as a difference rather than a surprise. Module health comes from a registrar that verifies every module's declared pieces against the live server. The networking levels each have a dedicated topology display that pairs the level's definition with its live rows:

Terms

← All documentation