Private networks

A private network links the devices your team uses: laptops, servers, CI runners, deployed apps. Each device gets a private address, and the devices reach each other directly, even behind home routers and office firewalls, as if they were on one local network. Nothing on a private network is visible from the internet. Private networks are part of **Premium**. ## How it works, in one paragraph Each device runs WireGuard, a modern encrypted tunnel, through zev. Zaryn's role is to introduce devices to each other: it tells each one the others' public keys and addresses, and who is allowed to reach whom. The devices then connect **directly** to each other. When two devices can't (some networks block it), their traffic goes through a teammate that reaches both, or else Zaryn's relay, which only passes encrypted packets along and can't read them. Zaryn never carries your general internet traffic: this is a network between your devices, not a VPN for browsing. ## Make a network On [zaryn.xyz/network](https://zaryn.xyz/network), create a network (for example `office`) and add the people who should be on it. With no rules, every device on the network can reach every other. To limit that, add rules on the network's page: who may reach whom, and on which ports, by person, by device, or by tag (`tag:dev`, `tag:ci`). ## Join a device On Linux (with `wireguard-tools`, `iproute2` and `nftables` installed), sign in with `zev login` and run: ```bash sudo zev net up your-name/office ``` On a network that blocks the way to Zaryn, choose a proxy of yours first (`zev proxy use <name>`, see [Using zev through a proxy](/docs/en/proxy)): `zev net up` takes it along, and the device joins, and reaches the relay, through it. The device joins and stays joined across restarts (it runs as a service). Check it: ```bash zev net status ``` ```text your-name/office zevnet0 port 41641/udp public 203.0.113.9 relay connected ● build-server 10.77.0.4 direct 198.51.100.7:41641 (12 ms) handshake 12s ago, ↓ 8.4 MB ↑ 1.2 MB ● sara-desktop 10.77.0.7 through the relay (encrypted end to end) handshake 40s ago, ↓ 310 KB ↑ 95 KB ``` `direct` means the two devices talk to each other with nothing in between. "Through the relay" means a direct path wasn't possible, so the encrypted packets pass through Zaryn's relay; "through <device>" means they pass through a teammate instead ([below](#when-two-devices-cant-reach-each-other-through-a-teammate)). Other devices on the network have names: `build-server.office` reaches the build server from any device on `office`. ### Servers and CI, without a person A machine that can't sign in interactively joins with a **join key** you create on the network's page: ```bash sudo zev net up --key znk_… --name ci-runner-1 --kind ci ``` ### Phones and other devices Devices that can't run zev can use the official WireGuard app. Make a config for them: ```bash zev net config your-name/office --name phone ``` The network's page on Zaryn can also show it as a QR code to scan. ## When two devices can't reach each other: through a teammate Some networks stop two devices from talking directly (a strict firewall, a filter between two countries, two carriers' NATs). Before falling back to Zaryn's relay, zev looks for a **teammate**: another device on your network that reaches both of them directly. Their packets go through it instead, still encrypted end to end with WireGuard, so the teammate can't read them, just as the relay can't. ```text ● build-server 10.77.0.4 through office-gw (a teammate; encrypted end to end) ``` Zaryn plans these routes from what every device reports (who reaches whom directly, and how fast), and gives each device its two best teammates for every peer it can't reach directly. The fastest one that's up carries the packets, and the next takes over if it goes. A teammate is usually faster than Zaryn's relay, keeps your traffic among your own devices, and keeps working when the relay is unreachable. A device only passes packets between two of its own peers that it reaches directly, never back the way they came. To keep one from passing anything on (a laptop on a metered connection, say), start it with `ZEV_NET_NO_FORWARD=1`. ## See the network's shape: zev net map `zev net map` shows who reaches whom, and what a single failure would cost: ```text your-name/office 5 devices online ● build-server office-gw 3 ms ● office-gw build-server 3 ms, sara-desktop 2 ms, vps 48 ms ● sara-desktop office-gw 2 ms ● laptop vps 61 ms ● vps office-gw 48 ms, laptop 61 ms Pairs 5 direct · 4 through a teammate · 1 only through Zaryn's relay If one thing fails ! office-gw is the only direct link between parts of the network: if it goes, they fall back to the relay ! the link office-gw ↔ vps is the only one joining two parts ! 1 pair only Zaryn's relay joins; if it's unreachable, they lose each other: build-server↔laptop · the weakest seam: 1 direct link keep laptop, vps joined to the rest ``` What it looks for: | | What it means | |---|---| | **A single point of failure** | a device whose loss splits the network's direct links into separate parts (an *articulation point*) | | **A lone link** | the only direct link joining two parts (a *bridge*) | | **The weakest seam** | the fewest direct links whose loss splits the network, and the devices on the smaller side (a *minimum cut*, found with the Stoer–Wagner algorithm) | | **The only teammate** | a device that's the one teammate route for some pairs | | **Relay only** | pairs with neither a direct link nor a teammate: Zaryn's relay is all that joins them | Adding one well-connected device (a small server or an office machine that everyone reaches) is usually what removes the warnings. `zev net map --json` prints the same for scripts and AI agents. ## Share an app with your team Run something on a device (a web app on port 3000, say) and share it with the network: ```bash zev net share 3000 --name web ``` Teammates on the network open `http://web.office`. Choose who may open it with `--allow`: ```bash zev net share 3000 --name web --allow tag:dev,user:sara ``` `zev net apps` lists shared apps; `zev net unshare web` stops sharing. ## Faster pulls from teammates When devices on the same network pull or clone the same repository, zev fetches what teammates already have directly from them, at local network speed, and checks every piece against its hash before using it. The rest comes from Zaryn as usual. ## Leave ```bash sudo zev net down # disconnect for now sudo zev net down --forget # leave the network on this device ``` ## Commands | Command | What it does | |---|---| | `sudo zev net up <owner>/<network>` | join with your zev sign-in | | `sudo zev net up --key znk_…` | join with a join key (servers, CI, apps) | | `sudo zev net down [<network>] [--forget]` | disconnect, or leave | | `zev net status` | peers, connections, traffic | | `zev net ls` | networks this device is in | | `zev net share <port> [--name n] [--allow …]` | share an app | | `zev net unshare <name>` / `zev net apps` | stop sharing / list shared apps | | `zev net config <owner>/<network> [--name n]` | a config for WireGuard's apps | ## Good to know - Traffic between devices is end-to-end encrypted with WireGuard's keys, which never leave each device. - Linux is fully supported today. macOS and Windows support is new; if something doesn't work, please tell us. - If a Premium plan ends, the network keeps working for a short grace period, then stops until it's renewed.