How the network works

The machinery, end to end, in plain language. The precise version is the protocol specification.

Everything on this page comes from SPEC.md in the spec repository, the document that legally and technically defines the network. The spec is the authority; an app is just one implementation of it, and anyone can build a compatible one from the spec alone. Section numbers below refer to it.

The one-paragraph version

When you open the app, your machine becomes a node. It reaches a few other nodes over the Tor network, catches up on everything it missed, and from then on holds a complete copy of every guide. Reading never touches the network at all: the text is already on your disk. Writing, reviewing, and voting produce small signed objects that flood from node to node until everyone has them. A rotating, community-bound group of editors signs an index that says which revision of each guide is the approved one, and every node independently checks that the editors followed the rules. No step in any of this asks a server for permission, because there are no servers.

Everything is a signed object (SPEC 3-5)

Every piece of data on the network, a guide revision, a review vote, a petition, the index itself, is an immutable, signed object. Each one names its author (a public key), carries a signature, and is addressed by the hash of its own bytes, so an object can never be altered after the fact: change one character and it is simply a different object. There are no usernames and no accounts anywhere in the data model; an identity is a keypair your machine generates locally, and reputation attaches to it by what it does.

Because ordering by clock is impossible on a network with no central time, nothing important ever depends on timestamps. Order comes from explicit references: each index release numbers itself and points at the previous one, forming a chain anyone can audit back to the first.

Old software never breaks the network: a node that sees an object type it does not understand stores and forwards it anyway. Upgrades never need a flag day.

The transport: Tor only (SPEC 10)

Nodes talk to each other exclusively as Tor onion services. There is no clearnet listener at all: a node has no public IP address to find, log, or attack, and neither your internet provider nor anyone watching the wire can see which nodes you talk to or what you exchange. This is not an optional privacy mode; it is the only transport the protocol has.

And because your node already holds all the text, the strongest privacy property costs nothing: reading sends no request. There is no lookup to log, no page load to observe, nothing to correlate. What you read is between you and your own disk.

Every node holds the library (SPEC 10)

All guide text is fully replicated to every node. That single decision buys most of the network's character:

• Reading is instant and works offline. No fetch, no spinner, no dead links. A village with one intermittent connection has the whole library on every laptop.
• Every node is a backup. Destroying the corpus means destroying every reader's machine.
• Read patterns never leak. You cannot be profiled by what you fetch if you never fetch.

This is affordable because text is small: all of Wikipedia's text is about 20 GB compressed, and this network will be a fraction of that for years. Guides sync in priority order, the approved text first, so a fresh install is usable in minutes while history and votes fill in behind.

How media survives (SPEC 6, 17)

Images, diagrams, and video are too big to give to everyone, so they work differently. A media file is a blob, addressed by the hash of its bytes. Nodes that hold a blob announce the fact in tiny flooded messages; every node builds a map of who has what, fetches a blob directly from a holder the moment a reader opens it, verifies the bytes against the hash, and then becomes a holder itself. Popularity is replication: the more something is viewed, the more copies exist.

Unpopular media is the hard case, and luck is not a strategy. Every node donates a slice of disk (you set the size), and part of it is a durability reserve run by a simple rule: each node computes, from its own key and the blob's hash, whether it is one of the nodes responsible for a rare blob right now. When a blob has too few holders, many nodes elect themselves and copies multiply; as holders appear, nodes stop electing themselves, and the loop settles at the target number of copies. No coordinator, no tracker, no messages beyond the announcements, and responsibility spreads evenly across the network by math rather than by agreement.

How two nodes catch up (SPEC 10, 16)

When two nodes connect, they must discover which objects each is missing, and they must do it cheaply over Tor, where every round trip is slow. Sending full inventories would cost megabytes to learn that two well-synced nodes differ by three objects. Instead they compare fingerprints of ranges of the object space: if a range's fingerprints match, that whole range is in sync and is never mentioned again; if they differ, the range is split and the comparison recurses. Identical libraries agree in one exchange; a handful of differences is found in a logarithmic number of steps. After the catch-up, new objects are pushed to connected peers as they arrive.

Finding peers, resisting capture (SPEC 15)

A brand-new install needs its first peer. The app ships with a tiny handful of genesis addresses, but the real seed directory lives on the network itself as a signed bootstrap list: signed by the same editor threshold as the index, strictly versioned so it can never be rolled back, and updated by publishing a new one. Seed hosts can change completely without anyone shipping a new app, which is what makes "the network outlives its seeds" literally true. Getting a host onto that list is a community decision, and being on it grants no power beyond being easy to find.

After first contact, nodes trade addresses of peers they have personally verified, remember who has been reliable across restarts, and keep a couple of connection slots reserved for bootstrap-list seeds, so no attacker can ever surround a node completely with hostile peers.

Could someone who did surround a node lie to it? No, and this is the deep reason the design holds: every object is signed and checked, and the index is a numbered, signed chain. An attacker who controls all of your connections still cannot forge a guide, an approval, or an index. All they can do is withhold newer data, and even that fails the next time your node compares notes with any honest seed. Surrounding a node buys silence, not lies, and only temporary silence.

Reaching it under censorship (SPEC 19)

Some countries block the Tor network itself. Because the whole transport is Tor, reaching the network from behind a national firewall is a first-class requirement, not an afterthought, and it turns on one property that makes this far easier than it sounds.

Get through once, read forever. Every node holds the whole library and reading is completely offline, so a person needs to reach the network only occasionally to sync, and after that the knowledge is on their machine permanently, with nothing more to block. Circumvention only has to succeed now and then, not every time you want to read. That is a much lower bar than a website you must reach on every visit.

To punch through when Tor is blocked, the app connects through bridges (unlisted entry points) using pluggable transports that disguise the traffic. It tries a direct connection first and falls back automatically, with no setup:

• Snowflake routes you through a rotating crowd of volunteer proxies with no fixed address for a censor to find and block. It is the primary path against the strictest firewalls.
• obfs4 scrambles the connection so it looks like random noise rather than Tor. Effective across most censored networks.
• meek hides the traffic inside an ordinary connection to a big cloud provider, a slower last resort.

Fresh bridges reach you the way they always have: carried by nodes already connected, fetched through Snowflake's address-less broker, or pasted and scanned from a friend. And getting the app in the first place is deliberately easy to route around: the installer is small, signed, and reproducibly built, so any mirror, USB stick, or hand-to-hand copy is verifiable and safe, and one person who gets through can seed both the app and the whole library to others entirely offline.

An honest note: this is an arms race, and a determined government can always make it harder. The promises that do not bend are the ones that matter most: reading is unobservable and works offline, the library survives once it is synced, and knowledge that reaches a country cannot be taken back out of it.

Keeping junk out (SPEC 9)

Everything published floods to every disk, so admission is controlled at the door:

• Proof of work. Publishing costs a few seconds of your own CPU, priced per object type. A person never notices; a flood of a million fake submissions becomes a compute bill.
• Rate limits. Nodes cap how much they will forward per author per day. Excess is stored but not spread.
• Validity checks. Anything with a bad signature, bad proof of work, or a malformed body is dropped on arrival and never forwarded, and the peer that sent it loses standing with the node it sent it to.
• Bounded parameters. The knobs (difficulty, quorums, thresholds) live in the signed index so they can be tuned, but hard floor-and-ceiling bounds are burned into the protocol, so no editor set can quietly turn the community's protections off.

Reading in your language (SPEC 12.1)

Human translations are first-class: a guide in another language links to the original and improvements flow both ways. While a human translation does not exist yet, the app can machine-translate any guide on your own machine. Small open translation models are fetched from peers like any other media, work offline once fetched, and no cloud service is ever called, because reading in translation must leak as little as reading. Machine output is clearly labeled as unreviewed, never enters the library, and the only path to a published translation remains a human submission through review (the machine draft may give the translator a head start).

Seed nodes (SPEC 18)

A seed is an ordinary node that is always on and generously resourced: it holds all the text, donates a large media budget, accepts many more connections than a laptop, and keeps a stable address. That is the entire description. A seed has no authority: it cannot approve content, influence a review, or sign the index, and the network depends on it for nothing except a faster first sync and better media durability. A headless build runs as a background service on a cheap VPS or a Raspberry Pi, and volunteering one is the single most useful donation the network can receive; one reviewable script sets a host up. See Get involved and Legal before you volunteer a host.

Built to be left (SPEC 11, 13, 14)

The final protection is that nobody is trapped here:

• Any user can export the entire library to plain files with one click, readable forever with no special software.
• All published content is CC BY-SA licensed, the code is AGPL, and the protocol is defined by a public document, so a compatible client, or a complete fork of the whole network, can be built by anyone.
• Governance failures have exits too: the community can recall reviewers, restore wrongly revoked content, replace the entire editor group against its will, and the corpus survives even a total collapse of all of it. See Governance.