Get started with private networks and proxy

Two tools for two problems, and how they work together. Skip to [the proxy](#8-one-command-zev-proxy-start) if that's what brought you here. ## 1. Two problems, two tools ```diagram type: cards --- 🕸 | My devices can't reach each other | Laptops, servers and CI behind different NATs and firewalls | accent 🔐 | Private networks | One encrypted WireGuard network for your team's devices, through any NAT (Premium) | good 🚧 | Zaryn is blocked or slow here | A filtered network blocks or throttles Zaryn, GitHub and more | warn 🛰 | zev proxy | Your own proxy server for zev, for every app, or for the whole computer (free) | good ``` They're separate: a private network connects **your devices to each other**, and a proxy gets **you out** to Zaryn and the internet. They also combine: a device behind a filter joins its team's network **through** the proxy ([chapter 13](#13-a-private-network-through-the-proxy)). ## 2. How a private network connects ```diagram type: graph title: Direct first, then a teammate, then the relay alt: Zaryn introduces devices; your laptop and the build server connect directly; when your laptop can't reach Sara's desktop, packets go through a teammate device, and only when there's none, through Zaryn's relay legend: path=Direct; path2=Through a teammate; warn=Through the relay start: Introductions height: 56 --- node zaryn | Zaryn | 50 6 | cloud | accent | Introduces devices: keys, addresses, who may reach whom. Never carries your traffic node laptop | your laptop | 10 28 | laptop node build | build-server | 50 28 | server node sara | sara-desktop | 90 28 | laptop node gw | office-gw | 50 48 | host | | A teammate's device that reaches both link zaryn laptop | | ghost link zaryn build | | ghost link zaryn sara | | ghost link laptop build | | dim link laptop gw | | dim link gw sara | | dim link laptop sara | | dim step Direct | Your laptop and the build server talk directly: WireGuard, end to end. link laptop build | path | direct step Blocked | A strict firewall stops your laptop reaching Sara directly. A teammate that reaches both carries the packets; it only sees encrypted bytes. link laptop sara | down link laptop gw | path2 link gw sara | path2 ``` Each device runs **WireGuard** through zev. Zaryn only introduces them; the devices connect **directly**. When that's blocked, packets go through a **teammate** device that reaches both, and only when there's none, through Zaryn's **relay**. All three are encrypted end to end. ## 3. How the proxy helps ```diagram type: graph title: Three levels, one proxy alt: zev's own connections, then apps pointed at port 10808, then every program through the VPN, all go through the engine to your proxy server legend: path=zev; path2=Apps on port 10808; new=Every program (VPN) height: 44 --- node zev | zev | 12 8 | laptop | accent | Sign-in, clone, push, pull, updates node apps | browsers, git, SSH | 12 22 | user | | Anything that can use a SOCKS5 or HTTP proxy node rest | every other program | 12 36 | folder | | Only the VPN catches these node xray | engine (Xray) | 46 22 | collector | | Runs your VLESS, Trojan, Hysteria2… link on this computer node proxy | your proxy server | 86 22 | server | good | Yours: Zaryn carries none of its traffic link zev xray | | path link apps xray | | path2 link rest xray | | new link xray proxy | | path ``` | Level | What goes through | Turn it on | |---|---|---| | zev only (default) | zev's own connections | `zev proxy use <name>` | | Every app | browsers, git, SSH, pip, npm… | `zev proxy share on` (port 10808) | | The whole computer | every program, its DNS and IPv6 | `sudo zev vpn on` (Linux) | ## 4. Make a network and join it ```diagram type: flow title: Two minutes --- Make it | zaryn.xyz/network → a network, e.g. `office`, and its people | accent | 🕸 ~ on each computer Join | `sudo zev net up you/office`: stays joined across restarts | | ⏻ ~ zev net status Connected | Each peer: direct, through a teammate, or the relay, with its latency | good | ✓ ``` ```bash zev login sudo zev net up your-name/office zev net status ``` On Linux you need `wireguard-tools`, `iproute2` and `nftables`. Devices get names: `build-server.office` reaches the build server from any device on the network. Without rules everyone reaches everyone; add rules on the network's page by person, device or tag (`tag:dev`). ## 5. Servers, CI and phones ```diagram type: cards title: Three ways onto the network --- 💻 | A computer | `zev login`, then `sudo zev net up you/office` | accent 🤖 | A server or CI runner | A join key from the network's page: `sudo zev net up --key znk_… --name ci-runner-1` | 📱 | A phone | The WireGuard app, with a config from `zev net config` or a QR code on the page | ``` ## 6. See its weak spots ```diagram type: graph title: What zev net map points out alt: office-gw links three devices; if it fails they fall back to the relay; build-server and laptop are only joined through Zaryn's relay legend: path=Direct; ghost=Relay only height: 44 --- node build | build-server | 10 10 | server node gw | office-gw | 40 22 | host | warn | A single point of failure: the only direct link between parts of the network node sara | sara-desktop | 10 36 | laptop node vps | vps | 70 22 | cloud node laptop | laptop | 94 22 | laptop link build gw | 3 ms | path link gw sara | 2 ms | path link gw vps | 48 ms | warn link vps laptop | 61 ms | path link build laptop | relay only | ghost ``` ```bash zev net map ``` It lists who reaches whom, then **what one failure would cost**: single points of failure, lone links, the weakest seam, and pairs only Zaryn's relay joins. Adding one well-connected device usually clears the warnings. `--json` gives the same to scripts and agents. ## 7. Share an app, pull faster ```diagram type: flow title: An app on one device, open to the team --- Run it | A web app on port 3000 of your device | | ▶ ~ zev net share 3000 --name web Shared | `--allow tag:dev,user:sara` chooses who may open it | accent | 🔗 ~ open Teammates | `http://web.office` from any allowed device | good | 👥 ``` And when teammates on the network pull the same repository, zev fetches what they already have **from them**, at local speed, checking every piece against its hash. ## 8. One command: zev proxy start ```diagram type: flow title: Everything, at once --- zev proxy start | Asks for your server's link the first time | accent | ⏻ ~ does Set up | Saves it, installs the engine, opens port 10808, sets the desktop proxy | | ⚙ ~ then On | Shows where you appear from; stays on across restarts | good | ✓ ``` ```bash zev proxy start # paste your link when asked zev proxy start --tun --kill-switch # the whole computer, and nothing leaks if it stops zev proxy stop ``` The proxy is free on every plan: you bring the server, and Zaryn carries none of its traffic. ## 9. Your links and subscriptions ```diagram type: cards title: What zev understands --- 🔷 | vless:// vmess:// trojan:// | TLS or REALITY, Vision, the ws, grpc, xhttp transports | accent 🔶 | ss:// hysteria2:// | Shadowsocks 2022 ciphers; Hysteria2 over QUIC with obfuscation | 🟩 | wireguard:// | Including Cloudflare WARP; no root needed | 🔗 | A subscription URL | One link, many servers: `zev proxy sub add myvpn <url>` | good ⛔ | Refused on purpose | Old insecure ciphers, dropped transports; `allowInsecure` never turns checks off | warn ``` ```bash zev proxy add work --use # paste the link when asked, so it stays out of your shell history zev proxy test # engine, Zaryn and the internet, each timed ``` ## 10. Every app, or the whole computer ```diagram type: cards --- 🌐 | Your desktop and browsers | `zev proxy system on`: GNOME, KDE and the browsers that follow them | accent 🔑 | SSH and git | `zev proxy ssh`: git over SSH through the proxy too | ▶ | One command | `zev proxy run -- <command>`: just this program | 🛡 | The whole computer | `sudo zev vpn on`, with a kill switch: nothing gets out directly | good ``` ```bash zev proxy check ``` `zev proxy check` shows where websites see you from, with and without the proxy, and with the VPN on, whether every app, DNS and IPv6 really go through it. ## 11. When it doesn't work ```diagram type: flow title: It finds a way through by itself --- Notices | Every 30 s it checks traffic gets through; three failures in a row | warn | 🔔 ~ zev proxy doctor Finds | DNS lies, a blocked port, SNI filtering, a clock that's off | accent | 🔍 ~ saves a fix for this network Fixed | The engine restarts with it, and tells you what it did | good | ✓ ``` ```bash zev proxy doctor ``` You can run the doctor any time. It remembers fixes per network, so your office Wi-Fi and your phone's hotspot each keep their own. ## 12. Many servers: the fastest, and failover ```diagram type: flow title: A pool of servers --- Time them all | One small request through each, at once | | ⏱ ~ keep the best three Fastest first | Each connection takes the fastest that answers | accent | 🚀 ~ one goes down Failover | The next connection takes another; nothing for you to do | good | ↻ ``` ```bash zev proxy use myvpn # every server of a subscription zev proxy use work,home,backup # these ones ``` Servers are timed again every 30 minutes, so one that got better comes back. Chains (one proxy through another) and routes (what goes direct) are in [the proxy guide](/docs/en/proxy). ## 13. A private network through the proxy ```diagram type: graph title: Joining from behind a filter alt: A device behind a filtered network joins its team's private network through the proxy; its WireGuard packets reach the relay inside the proxy and stay end to end encrypted legend: path=Through the proxy; path2=WireGuard, end to end height: 36 --- node dev | your device | 10 18 | laptop | accent | Behind a network that blocks almost everything node px | your proxy | 40 18 | server | | Carries the relay's traffic too node relay | Zaryn's relay | 68 18 | collector | | Only sees encrypted WireGuard packets node team | the team | 92 18 | laptop | good | link dev px | | path link px relay | | path link relay team | | path2 ``` `sudo zev net up you/office` takes the proxy you use and keeps it with the network, so the network's background service reaches Zaryn and the relay through it. `zev net status` shows `through the proxy …` when it does. ## 14. Safe by default ```diagram type: cards --- 🚫 | No silent fallback | If the proxy can't be used, zev stops and says why; it never goes out directly behind your back | accent 🔒 | Certificate checks stay on | A link can pin the server's certificate; it can't switch checks off | good 🏠 | The shared port is yours | 127.0.0.1 only; opening it to the LAN needs a password | 🗝 | A link is a password | It holds your key on that server: if one leaks, ask for a new one | warn ``` Local and private addresses (your LAN, `100.64.0.0/10`, `*.zaryn.internal`) never go through the proxy. Everything else, in depth: [Private networks](/docs/en/private-networks) and [Proxy and VPN](/docs/en/proxy).