Getting real
How to build and test this.
FrogNet is a network fabric — a matrix of system-level and application-level code that implements a whole architecture — not an application you install and open. There is no honest “try it on your laptop in five minutes,” because the thing it does, keep operating while the network underneath it changes, only exists across multiple cooperating machines. This is the unvarnished version: what it actually is, and what it actually takes to stand one up and put it under test.
A fabric, not an app.
You do not run FrogNet the way you run a program. FrogNet is the layer other programs run on: a transport-agnostic mesh with its own discovery, host election, wire protocol, semantic codec, adaptive media stack, and a floating shared-memory database. The demos you have seen — a call that will not drop, a game table, a sensor map — are applications on top of it. They are the paint, not the building.
a chat app
The Communicator is one demonstration that a session survives conditions that kill other stacks. It is not the product. The product is the fabric underneath it — and a dozen other applications ride the same fabric at once.
a single binary
A FrogNet is N cooperating nodes sharing one live memory — a daemon, handlers, a codec, an elected database host, and a wire protocol all running together. You can stand up many nodes on a single machine over loopback, which addresses 254 hosts, so even one box runs a genuine multi-node network.
a cloud service
There is nothing to sign up for and no server of ours in the path. You own every box in it. That is the whole point — and it is also why standing one up is real work, not a download.
At least two boxes. Realistically, a few.
Nothing exotic — FrogNet is designed to run on hardware you already have. But it is genuinely a multi-machine system, and the honest minimum reflects that.
Nodes — two minimum, three to see anything interesting
Two boxes make a pond. Three or more is where election, merge, and self-healing actually have something to do. A Raspberry Pi is a real node; so is a retired laptop. Mix them — heterogeneity is the normal case, not the exception.
The database host — the one that matters
One node is elected — deterministically, no vote or coordinator — as the most-capable box actually running the database, and it holds the shared memory every other node reads and writes. The store is memory-bound, so RAM decides it, and that box's capacity sets the ceiling for the whole pond: a Pi bounds a small one, a capable box carries a much larger one. It isn't pinned to a machine — split the network and each island elects its own; merge and the most-capable box wins again.Magnum Croakus § 14 — Selecting the service hosts →
Transports — anything two points can talk over
Wired Ethernet, Wi-Fi, WireGuard tunnels, 900 MHz radios — FrogNet does not care. If you want to see transport independence rather than take our word for it, put two different bearers in the same path and watch the fabric not notice.Magnum Croakus § 5 — Transports multiplexed under one topology →
A broker — an introducer, in the cloud or on the LAN
Two nodes on the same wire need no broker; they find each other unaided. The broker exists for the third case — nodes that cannot see each other directly. It is a stateless introducer that holds no truth and carries no traffic: it hands out membership and mints the WireGuard tunnels that carry the 10-net between peers, then gets out of the way. There is a public broker you can point at; you can also run your own. On a LAN a broker earns its keep differently — it mints a tunnel not to reach a node but to shorten a path it already has, collapsing a long discovery chain to a direct hop.Magnum Croakus § 17 — The Broker →
Or stand up any topology in the simulator.
Three boxes show you election and merge. They don't show you a five-node ring, two LANs bridged by a tunnel, or a sprawling multi-site pond — and they don't let you kill the middle node a hundred times before lunch. FrogNet ships a simulator that stands up arbitrary topologies and runs the real discovery engine against them — so you can build and test networks you don't have the hardware for, and prove a fix before it ever touches a live mesh.
The whole network is one object
The fabric models the nodes, links, bearers, and the getHosts graph as a single object and derives what each node can actually see — so an echo only “carries” a peer's identity when the observer could truly reach it. The inputs aren't hand-fed; they fall out of the model, which is the only way a whole-system test means anything.
It runs the code, not a script
Each round runs the actual ported discovery; routes install into a per-node kernel; packets route over the actually-installed tables with real longest-prefix, lowest-metric semantics, each round's routes carried forward as the next round's input. A fix is proven against ground truth, never against a model that might share the bug — last run, 67 discovery oracles green, zero regressions.
A laptop, or a real kernel
By default it runs on deterministic fake backends — no privileges, the whole suite in seconds on any laptop (18/18 topologies converge). Set FROGNET_SIM_BACKEND=real on a Linux box with root and the identical logic installs into real network namespaces — one netns per node, veth per segment — where the kernel itself is the oracle: an off-link gateway is rejected as invalid, so a route the engine got wrong simply won't install. Same 18/18, now against a live FIB.
The 120→ny1 chain
The load-bearing proof: five nodes — Sea2 → Sea3 → Sea6 → Sea5 ==wg==> NY1 — proven three independent ways: the engine crawls the whole chain, a packet walk arrives end to end and back, and on a real kernel FIB all 49 chain pairs resolve. The ground truth is folded from a physical run on the real boxes, confirmed by ping both directions — the sim grades the algorithm against what hardware did, not its own opinion.
The topologies it stands up
| Topology class | Shape | What it exercises | Result |
|---|---|---|---|
| Three-node chain | A — B — C | Multi-hop route install; each node reached downstream via its neighbor's .1. Baseline captured from real hardware. | 12/12 pairs · 3 cycles |
| Five-node ring | ○ 5 nodes, cyclic | Convergence on a cyclic topology — every pair reachable, no route folds into a loop. | all pairs · loop-free |
| Two LANs, one tunnel | LAN ⇄ wg ⇄ LAN | A forwarder carries a whole subtree over one WireGuard tunnel; two LANs resolve as one 10/8 overlay. | all pairs reachable |
| Multi-site pond | many LANs + forwarders | Cross-site overlay and per-service election across the whole pond, to a fixpoint. | converges |
| Seattle guest chain | Sea2→Sea3→Sea6→Sea5 ==wg==> NY1 | Deep multi-pass crawl to the far end, then tunnel egress — the 120→ny1 proof, folded from a physical run. | arrives both ways |
| Kill-a-node (fault) | 5-chain, middle dies | Partition into exactly the two islands it should — and no phantom route anywhere still points at the node that's gone. | split asserted · 0 phantom |
Representative classes from the 18-class suite; each stood up and converged by the real engine.
How each run is scored · 2026-07-12
| Scenario | What it proves | How it's checked | Result |
|---|---|---|---|
| Discovery regression catalog | Engine and route-render fidelity across the catalog of known breakages | Curated oracle suite | 67 / 67 · 0 regressions |
| Topology convergence | Every node sees every subnet; all pairs reachable over installed routes | Real engine to a fixpoint vs a fake kernel | 18 / 18 classes |
| Chain-depth crawl | Multi-pass discovery reaches the far end of a guest chain, then stops | Real engine, neighbours frozen to immediate knowledge | NY1→Sea2 · 3 passes |
| End-to-end route walk | A packet traverses the full Seattle chain to NY over installed tables | Fabric traceroute, each hop resolved by the node's own table | arrived |
| Role election | databasehost, gamehost and mediahost chosen deterministically per pond | Real election engine over a converged system | 3 / 3 |
| Media codex (SotF / UnREST) | SAME/DIFF bandwidth savings, multi-writer visibility, float re-assert | Codex simulator | 18 / 18 |
| Real-kernel FIB | Converged routes install and resolve on an actual Linux kernel FIB | Each node in its own netns; kernel ip route get is the oracle | 18 / 18 · 49-pair chain |
Single-machine validation of the routing and election core — RC build 20260710-ax-LANVIA-CLEAN. Real engine, independent oracle: route correctness and election outcome, not timing or RF.
Every fix ships an oracle that fails on the old code and passes on the new, reproducing the real failure — so the day a contract breaks, one test turns red with the line that did it. And the caveat the project holds itself to: this gate proves route correctness and election outcome — not timing, RF, WireGuard crypto, or live A/V under loss, which need a real box. A green curated suite is not a full-spec result; report the measured numbers, name the gaps.
Magnum Croakus § 30 — What the simulator holds →Linux, the daemon, and your handlers.
The system code is FrogNet's job; the application code is yours. The line between them is the handler interface — and the handler source is available, so you can see exactly where your code meets the fabric.
The proxy and the daemon
Two services come up with each node: the proxy takes port 80 for FrogNet traffic — a redirect scoped to the 10/8 plane — and the daemon is the worker pool behind it that learns templates, runs the UnREST handlers, and collapses each exchange to SAME, DIFF, or FULL. Discovery and election ride the same path; a separate tunnel daemon owns any WireGuard links. No central coordinator.
Linux, in its real variety
FrogNet runs on the Linux you already have, on the mix of boxes you already have. Breadth is a first-class concern here — the same discipline that put a configuration agent across 42 distinct system configurations at Microsoft.
UnREST handlers — source available
You write to the network the way you write to local variables: parse, intercept, vector, fan out. The handler source is published, so the boundary between application and fabric is inspectable, not a black box.
WireGuard for tunneled hops
Any hop you want encrypted or routed across the public net can ride a WireGuard tunnel — always AllowedIPs 10/8, so the route table alone decides which tunnel a packet takes. WireGuard is user-supplied; FrogNet ships no crypto of its own. Nothing above the tunnel changes.
Two cooperating ends, and a rendezvous between them.
FrogNet is a private layer that lives alongside the internet, not on top of it. Crossing the public net means both ends run FrogNet and meet through a broker. This is the honest constraint stated plainly: it is infrastructure for a network you own on both sides.
# a real heterogeneous path FrogNet holds a live call across — # adaptation responds to the characteristics of each hop, not to any one medium: laptop → Wi-Fi → Seattle node → WireGuard → broker → WireGuard → NY node → 900 MHz radio → NY node → laptop # traffic to the private 10.x network rides the adaptive FrogNet node; # everything else routes straight out to the internet, at normal speed.
Nodes that can already see each other need no broker at all. You need one to introduce nodes that cannot — to bridge across NAT and the internet by minting WireGuard tunnels that carry the 10-net between sites, after which two LANs become one 10.0.0.0/8 overlay. The two coexist on the same machine, and a 10.x network you already run keeps working — FrogNet nodes just need unique addresses.
Magnum Croakus § 18 — The Tunnel →Loopback, then a LAN, then a second transport, then the world.
There is no single command that produces a network, because a network is more than one machine agreeing. Build it up in stages — each stage proves one more thing the last could not.
One box, loopback — already a real network
Loopback is a network: it addresses 254 hosts, so you can bring up several nodes on a single machine and watch discovery, election, and shared memory work for real across them. What one box can't show you yet is physical transport diversity or a true partition — those need more than one machine.
You should see · multiple nodes, autonomous discovery, an elected host, shared state — all on one boxA second machine — the network spans hardware
Bring up nodes on a second box across a real wire. Now discovery is finding peers over physical links, and election spans machines — the coordination you saw on loopback, proven across hardware it can actually lose.
You should see · cross-machine discovery, an elected host spanning boxes, state shared over the wireAdd a third and a second transport — break it on purpose
Add a node, then add a different bearer to the path. Now do violence to it: pull a cable, kill the elected host, split the network in two. Watch it re-elect, keep operating on each side, and merge with no reconciliation when the path returns.
You should see · re-election, partition tolerance, clean automatic mergeOr rehearse all of it in the simulator first — it is built for exactly this abuse.Cross the internet — join two ponds
Point the nodes at a broker — the public one, or your own — and let it introduce the two sides and mint the WireGuard tunnels that carry the 10-net between them. The two FrogNets converge into one 10.0.0.0/8 overlay, and the fabric behaves exactly as it did on the LAN — the internet is just one more bearer underneath it. That sameness is the whole result.
You should see · two networks converge into one overlay, transport-independent, liveStill with us
Still want to build one?
Good — that is exactly the reader this was written for. The developer license is free, the handler source is available, and the build manual walks every step in full detail.