byhand · network

Your pages

Two separate questions: how a page reaches a reader's browser, and how your devices find each other (your other devices, your guardians, byhand get). Whatever the answers, pages, comments and messages stay encrypted end to end: what changes is only who sees your IP address and who learns that a page exists.

1. How a page reaches a reader

A browser never reads the records of part 2: it asks the gateway for your device, then tries these in order, by itself.

Directly, over WebRTC default

Nothing to set. The gateway passes only the WebRTC offer and answer, sealed with the link's key. STUN servers (Cloudflare, then Google) tell each side its public address. Then the page, and the comments, votes and messages that follow, go over an encrypted data channel (DTLS) between the reader's browser and your device.

introducesReaderbrowserYour devicebyhand appdirectly (WebRTC)
Pros
  • The gateway sees neither the page nor the conversation pass.
  • Faster: one hop instead of two.
  • Over IPv6 there is no NAT: it works from a phone on 4G.
Cons
  • The reader and your device learn each other's IP address; the STUN servers see both public addresses (nothing else).
  • On IPv4, mobile carriers' NAT (CGNAT) and company firewalls often block it: then TURN, or the gateway, by themselves.
  • Still through the gateway, sealed: presence, files over 60 KB, and everything while you are away (a guardian answers there).

Through your TURN server

When the direct path is blocked and your gateway runs a TURN server next to it (byhand gateway --turn, with coturn, on a VPS: see docs/self-host.md). The reader's browser relays through it to your device. Not on byhand.page while it is hosted on Render, which forwards HTTP only.

ReaderbrowserTURN servercoturn, your VPSYour devicebyhand appencryptedrelayed
Pros
  • Gets through blocked networks without going through the gateway.
  • Still encrypted end to end: the TURN server cannot read anything.
Cons
  • The TURN server sees both IP addresses and how much goes through.
  • You run it, and its bandwidth counts.

Through the gateway

Always there, as the fallback: your device keeps a WebSocket open to the gateway, which relays the encrypted page and the sealed messages.

Your devicebyhand appGatewaykeeps nothingReaderbrowserkept openencrypted page
Pros
  • Works on every network.
  • Only the gateway sees IP addresses: the reader never learns yours.
Cons
  • The gateway sees the encrypted page and the sealed messages pass (and their size and timing).
  • A detour: slower, and it counts against the gateway's bandwidth.

Side by side

The gateway does not see it passIP hidden from the readerSpeedBlocked networksWho sees your IP
Direct (WebRTC)●●●●○○●●●●○○the reader, the STUN servers
Your TURN server●●●●○○●●○●●●the reader (in the WebRTC answer), your TURN server, the STUN servers
The gateway●○○●●●●●○●●●the gateway only

●●● = the best on that point. Direct is tried first; TURN only when your gateway has one; the gateway always works. Through TURN too, the reader learns your address (it is in your device's WebRTC answer): only the gateway path, or --hide-ip, keeps it from readers.

2. How your devices find each other

To reach each other peer to peer (to sync a page, hand it to a guardian, or serve byhand get and the gateway's bridge), your devices publish small signed pkarr records under the page's id (an Ed25519 public key): which iroh nodes serve it, and at which address. Nobody can forge them, and they never contain a page or a key. What you choose is where they go, and who sees them.

1. The DHT and public pkarr relays default

Nothing to set. Records go on the BitTorrent Mainline DHT and through pkarr's public relays over HTTPS, both.

Your devicebyhand appDHT + relaysmany nodesReaderor other devicepublisheslooks up
Pros
  • Nobody runs the DHT: it never shuts down.
  • Nothing to set up, works everywhere.
Cons
  • DHT nodes see your page ids and your IP address.
  • Lots of UDP traffic to strangers: some hosts forbid it (one banned byhand's first account).

2. Public pkarr relays only

byhand install --server (or --no-dht): records go through pkarr's public relays over HTTPS only. Typed pairing codes need the DHT, so invitation links are used instead.

Your device--no-dhtpkarr relaysHTTPS, publicReaderor other devicepublisheslooks up
Pros
  • Plain HTTPS: accepted by every host.
  • One service sees the records instead of thousands of nodes.
Cons
  • The relays' operator sees who publishes and who looks up which id.
  • If the relays go down, your devices no longer find each other (readers still get pages through the gateway).

3. Your own pkarr relay

On your gateway: byhand gateway --pkarr. On every device: --pkarr-relay https://your.domain/pkarr --no-dht, also given to byhand install. Or yours and the public ones together, so nothing hangs on one server: --pkarr-relay https://your.domain/pkarr,public --no-dht.

Your device--no-dhtYour gateway--pkarrReaderor other devicepublisheslooks up
Pros
  • Only you see the records (or you and the public relays, with ,public).
  • No public service needed, no host to upset.
Cons
  • Your gateway must keep running: it holds the records in memory, 3 hours (devices publish again every 30 minutes).
  • Every device has to be told where it is.

4. No IP addresses: --hide-ip

With any of the above. Records name the device's iroh relay only, and the device never connects to readers directly: no WebRTC, readers get pages through the gateway.

Your device--hide-ipiroh relayencrypted QUICOther devicebyhand appconnectsconnects
Pros
  • Your IP address is published nowhere, and no reader learns it.
Cons
  • Slower: connections go through the iroh relay (n0's by default, or --relay for yours), and readers through the gateway.
  • The iroh relay's operator sees both sides' IP addresses, not the content.

5. No records at all: --only web

byhand share --only web: no peer to peer between apps. Readers still get the page directly (WebRTC) or through the gateway.

Your device--only webGatewaykeeps nothingReaderbrowserkept openpage, comments
Pros
  • The simplest: nothing published anywhere.
Cons
  • No guardians: when your device is off, the page is offline.
  • Your devices do not sync with each other, and byhand get cannot fetch it.

Side by side

Decen­tral­isedPrivacyRelia­bilityFine on a hostSimpli­cityWho sees your IP
1. DHT + pkarr●●●●○○●●●●○○●●●thousands of DHT nodes, the pkarr relays
2. Public pkarr relays●●○●●○●●○●●●●●●the pkarr relays' operator
3. Your pkarr relay●○○●●●●○○●●●●○○you only (with ,public: and the public relays)
4. --hide-ip●●○●●●●●○●●●●●○the iroh relay's operator only
5. --only web●○○●●●●○○●●●●●●nobody (no records; readers: see part 1)

●●● = the best on that point. Decentralised: no single service everything depends on. Privacy: how many learn that the page exists and where it is served from. Reliability: it still works when a service goes down. Fine on a host: no risk of being banned from a rented server. No option wins everywhere.

Recommended

ForSettingWhy
Your own computers (the usual case)Nothing to change: direct for readers, DHT + pkarr (part 2, 1) between your devicesThe most reliable, no single service sees everything, and the page goes direct whenever the network allows. Your IP is public, as it already is to every site you visit.
A rented server (a guardian on a VPS)Public pkarr relays only (part 2, 2): byhand install --server No BitTorrent traffic, so no ban from the host.
Readers on mobile networks, with your own gatewayTURN: byhand gateway --turn They get through without falling back to the gateway.
A company, or the most discretionYour pkarr relay + --hide-ip (part 2, 3 + 4)Your records stay with you and your IP is published nowhere. In exchange: your gateway must run, readers go through it, and it is slower.

Who sees what, and what byhand does not protect: security. Running your own gateway: home page.