# URnetwork > Open-source network privacy for humans and AI agents: residential egress in > 90+ countries through a decentralized provider network, with the same > identity and privacy guarantees for people and agents alike. ## For agents - [Agents guide (machine-readable)](https://ur.io/agents.md): the MCPv2 server (https://mcp.bringyour.com, OAuth), add-server recipes for 21 agent harnesses, x402 pay-as-you-go, and the proxy fallbacks. - [API authentication without OAuth](https://ur.io/docs-md/api.md): a person creates an auth code at https://ur.io/app/account/settings; exchange it at `POST https://api.bringyour.com/auth/code-login` for a JWT, or make a long-lived `urn_` key with `POST /account/api-key`; send either as `Authorization: Bearer ` - [Live network stats](https://api.bringyour.com/stats/last-90): providers, countries, cities, daily series — the JSON feed behind the coverage figures, for verifying claims instead of quoting them. - [Check my IP](https://ur.io/ip): asked for JSON, it answers `{"ip": "
"}` — the egress address a site sees through your proxy: `curl -H 'Accept: application/json' https://ur.io/ip` - [OpenAPI 3.1 spec](https://ur.io/openapi.yml) ([markdown summary](https://ur.io/docs-md/api.md)) - [Skill file](https://github.com/urnetwork/skill/blob/main/SKILL.md): the default skill for runtimes without MCP — auth-code sign-in, proxies, reading a 402, paying, and retrying. - [The core in one file](https://ur.io/llms-full.txt): home, products, install, agents, the docs index and the top docs — not the whole site ## Plans - [Plans and pricing](https://ur.io/products.md): Free, 30 GiB per day, 2 concurrent clients; UR Pro, 10 TiB per month, $5/month or $40/year, 1000 concurrent clients. Prices an agent can quote live, once x402 is on: `GET https://api.bringyour.com/x402/skus` — it is not on yet, and the endpoint answers an error (500 today, 404 later) until it is: anything but a 200 with a sku list means ask the human to upgrade instead ## Docs - [Documentation](https://ur.io/docs) — overview, per-platform setup guides, tours, FAQ, and comparisons; Markdown sources are at https://ur.io/docs-md/.md (translated docs also at https://ur.io/docs-md//.md); HTML documents use .html instead - [API reference](https://ur.io/docs/api) — the index, with one page per section: [Authentication](https://ur.io/docs/api/auth), [Network](https://ur.io/docs/api/network), [Stats](https://ur.io/docs/api/stats), [Subscription](https://ur.io/docs/api/subscription), [Wallet](https://ur.io/docs/api/wallet), [Device](https://ur.io/docs/api/device), [Account](https://ur.io/docs/api/account), [Preferences](https://ur.io/docs/api/preferences), [Feedback](https://ur.io/docs/api/feedback), [Connect protocol](https://ur.io/docs/api/connect), [Transfer](https://ur.io/docs/api/transfer), [Solana](https://ur.io/docs/api/solana), [Referral codes](https://ur.io/docs/api/referral-code), [Other](https://ur.io/docs/api/other) - [SDK examples](https://ur.io/docs/examples): install the SDK and connect sockets and HTTP clients in twelve languages (English only). Installable today: Go (`go get github.com/urnetwork/sdk/v2026@latest`), JavaScript and TypeScript (`npm install @urnetwork/sdk`); the other languages' packages are not published yet ([availability](https://ur.io/docs/install-sdk)) ## Pages - [Products and pricing](https://ur.io/products) ([markdown](https://ur.io/products.md)) - [Agents](https://ur.io/agents) - [Install](https://ur.io/install) ([markdown](https://ur.io/install.md)) - [URnode](https://shop.ur.io): the hardware node, sold at shop.ur.io - [About](https://ur.io/about) ([markdown](https://ur.io/about.md)) - [Blog](https://ur.io/blog): research and notes on internet privacy ([RSS](https://ur.io/blog/rss.xml) with the newest 20 articles, per-article markdown at https://ur.io/blog-md/.md) ## Optional - [Changelog](https://ur.io/changelog) ([markdown](https://ur.io/changelog.md)) - [Outages](https://ur.io/outages) ([markdown](https://ur.io/outages.md)): every outage, when it started and ended, what went wrong and what we changed - [Buy data](https://ur.io/buy-data) - [Locations](https://ur.io/location): per-country pages (93 countries) --- # The Privacy Network — URnetwork > Whole-internet encryption, powered by people. Welcome to URnetwork. ## A Network Built by the People Your traffic is encrypted on your device and routed through a mesh of community nodes. No single node sees the full path. No logs stored. Privacy by architecture, not promise. ## How is URnetwork different from a traditional VPN? A traditional VPN asks you to trust them with your traffic. URnetwork doesn't. Your traffic routes peer-to-peer through community-run devices, with Tor-like anonymization. No logs. 100% open source and reproducible so you can verify it yourself. Home: https://ur.io/ · Compare with other VPNs and privacy tools: https://ur.io/docs/comparison --- # URnetwork products & pricing > Powerful privacy, performance, and control, built for creators, gamers, and innovators. Whether you're just starting out or scaling your capabilities, URnetwork gives you the speed, security, and flexibility you need. ## Community — FREE - 30 GiB / day of network data - 2 Concurrent Clients - Anonymous access via the world's largest network of egress and ingress providers - Post-Quantum Encryption between you and decentralized providers - Split-tunnel - Custom DNS - No ads. No logs. 100% open source - Agentic skills - Blocks ads and trackers - Always blocks malware and bots - Connect to network peers ## UR Pro — $40 / year (or $5 / month) Everything in Community, plus: - 10 TiB / month of network data - 1000 Concurrent Clients - WireGuard profiles - SOCKS proxy Machine-readable prices: `GET https://api.bringyour.com/x402/skus` — and the x402 flow lets an agent pay for an upgrade in-band (see /agents.md). Availability: x402 is not switched on for this deployment yet. Until it is, `GET /x402/skus` answers an error instead of a sku list (today an HTTP 500; the intended not-enabled answer is 404 "x402 is not enabled."). Treat any answer other than a 200 with a JSON sku list as "not available": ask the human on the account to upgrade, and do not retry the purchase flow. URnode hardware is sold separately at https://shop.ur.io Full comparison: https://ur.io/products --- # Install URnetwork > Free apps for Android, iOS, macOS, Windows and Linux, plus browser > extensions — every build open source and reproducible. https://ur.io/install - Android: [Google Play](https://play.google.com/store/apps/details?id=com.bringyour.network), [F-Droid](https://f-droid.org/packages/com.bringyour.network/), or the APKs on [GitHub releases](https://github.com/urnetwork/build/releases) - iOS and macOS: [App Store](https://apps.apple.com/us/app/urnetwork/id6741000606) - Windows 10/11 (x64, ARM64): the MSI on GitHub releases — https://ur.io/install/windows - Ubuntu 24.04+ (amd64, arm64): the daemon .deb on GitHub releases and the AppImage — https://ur.io/install/ubuntu - Browsers: [Chrome](https://chromewebstore.google.com/detail/urnetwork/kpnklgbgjkihebbieiggfeokkddjbkfb), [Edge](https://microsoftedge.microsoft.com/addons/detail/urnetwork/jegjndonglfogpmldpmokincfecdombi), [Firefox](https://addons.mozilla.org/en-US/firefox/addon/urnetwork/) - SDK (build it into your own app): https://ur.io/docs/install-sdk --- # URnetwork for agents Give your agent residential network egress in 90+ countries, with the same identity and privacy guarantees as human users. The happy path is the MCP server; everything else on this page is fallback or detail. ## MCP server (preferred) ``` https://mcp.bringyour.com ``` - Protocol: MCPv2 — the stateless 2026-07-28 revision of the Model Context Protocol (streamable HTTP, JSON responses). Older protocol revisions are negotiated down automatically. - Auth: OAuth. The first connect opens a browser sign-in to your account on https://ur.io and issues your agent a scoped token. No keys to paste. Discovery metadata: https://mcp.bringyour.com/.well-known/oauth-protected-resource - A network account is required; a person creates it at https://ur.io. Start with a free account — x402 (below) tells your agent when an upgrade is actually needed. ### Tools - `providerLocations` — find available provider locations (countries, regions, cities), with provider counts, stability, and strong-privacy flags. - `fetch` — load a URL from a chosen country, region, or city, as if browsing from there, optionally returning referenced resources. State is threaded through the caller: pass back `signed_proxy_id` (reuse the same egress), `cookies` (opaque site session), `continuation` (collect remaining resources). Requires the `mcp:fetch` scope. When the network is at a plan limit the result carries `payment_required` — see x402 below. ## Add the server to your harness ### Claude Code ``` claude mcp add --transport http urnetwork https://mcp.bringyour.com ``` OAuth: run /mcp in a session, pick urnetwork, and finish the browser sign-in. ### Cursor ``` { "mcpServers": { "urnetwork": { "url": "https://mcp.bringyour.com" } } } ``` .cursor/mcp.json (or ~/.cursor/mcp.json). Authenticate under Settings → MCP; the browser consent opens on connect. ### VS Code ``` code --add-mcp '{"name":"urnetwork","type":"http","url":"https://mcp.bringyour.com"}' ``` OAuth: on first start VS Code shows a trust prompt, then opens the browser sign-in (Copilot agent mode). ### Codex ``` codex mcp add urnetwork --url https://mcp.bringyour.com ``` OAuth: codex mcp login urnetwork opens the browser sign-in. ### Cline ``` { "mcpServers": { "urnetwork": { "type": "streamableHttp", "url": "https://mcp.bringyour.com" } } } ``` MCP Servers → Remote Servers → Add (or cline_mcp_settings.json); recent builds run the browser sign-in when the server asks. ### Claude.ai ``` Settings → Connectors → Add custom connector → https://mcp.bringyour.com ``` Every plan, web and desktop. Connect runs the browser sign-in. ### ChatGPT ``` Settings → Developer mode → + → MCP server URL: https://mcp.bringyour.com ``` Plus/Pro/Business: pick OAuth as the connector auth; sign-in runs on connect. ### OpenClaw ``` openclaw mcp add urnetwork --url https://mcp.bringyour.com --transport streamable-http --auth oauth ``` OAuth: openclaw mcp login urnetwork prints the authorization link. ### Hermes ``` hermes mcp add urnetwork --url https://mcp.bringyour.com --auth oauth ``` OAuth: first connect prints an authorize URL and opens your browser, waiting on a loopback port; hermes mcp login urnetwork re-authenticates. ### OpenCode ``` { "mcp": { "urnetwork": { "type": "remote", "url": "https://mcp.bringyour.com", "enabled": true } } } ``` opencode.json. OAuth is automatic on first use; opencode mcp auth urnetwork re-authenticates. ### Antigravity ``` { "mcpServers": { "urnetwork": { "serverUrl": "https://mcp.bringyour.com" } } } ``` Agent panel → MCP Servers → Manage → edit the raw config (note serverUrl), then tap Authenticate. ### Devin ``` Settings → Connections → MCP servers → Add a custom MCP → Streamable HTTP → https://mcp.bringyour.com ``` Full OAuth flow, per person or per org. (Windsurf is now Devin Desktop; same place there.) ### Perplexity ``` Settings → Connectors → Add connector → https://mcp.bringyour.com ``` Pro/Max/Enterprise: choose OAuth at setup; works on web, Comet, and the Mac app. ### Zed ``` { "context_servers": { "urnetwork": { "url": "https://mcp.bringyour.com" } } } ``` settings.json (note the context_servers key), or Settings → AI → MCP Servers → Add Remote Server; Zed prompts the standard MCP OAuth flow when no header is set. ### Factory Droid ``` droid mcp add urnetwork https://mcp.bringyour.com --type http ``` OAuth is the default for remote servers. Run /mcp inside droid to complete the sign-in. ### JetBrains ``` { "mcpServers": { "urnetwork": { "url": "https://mcp.bringyour.com" } } } ``` Settings | Tools | AI Assistant | MCP → paste As JSON. No OAuth flow yet; use a static Authorization header or the mcp-remote bridge. ### Trae ``` { "mcpServers": { "urnetwork": { "url": "https://mcp.bringyour.com" } } } ``` Settings → MCP → Add → Add Manually. Header auth only today; no OAuth in Trae yet. ### Qwen Code ``` qwen mcp add --transport http urnetwork https://mcp.bringyour.com ``` OAuth: runs automatically on connect (httpUrl + oauth.enabled in ~/.qwen/settings.json); manage via /mcp. ### Gemini CLI ``` gemini mcp add --transport http urnetwork https://mcp.bringyour.com ``` OAuth: automatic on first use; /mcp auth urnetwork re-authenticates. (Enterprise Gemini Code Assist; individual access moved to Antigravity.) ### Grok ``` grok.com → Connectors → New Connector → Custom → https://mcp.bringyour.com ``` OAuth runs during connector setup. Grok Build CLI: grok mcp add --transport http urnetwork https://mcp.bringyour.com. ### Kimi Code ``` kimi → /mcp-config → "add urnetwork https://mcp.bringyour.com" ``` AI-native MCP config: describe the server in /mcp-config and Kimi Code adds and authenticates it, with no JSON to hand-edit. (Successor to kimi-cli.) ## Live network data - `GET https://api.bringyour.com/stats/last-90` — the network's public stats feed (providers, countries, cities, daily series for the last 90 days). Unauthenticated JSON; the source behind the coverage figures the docs cite. Use it to verify claims instead of quoting them. - `curl -H 'Accept: application/json' https://ur.io/ip` — the public IP address the request came from, as `{"ip": "
"}`. Send it through a proxy to see the egress address a site sees. ## The API - OpenAPI 3.1 spec: https://ur.io/openapi.yml (rendered at https://ur.io/docs/api, summarized at https://ur.io/docs-md/api.md) - Authentication: `Authorization: Bearer `, where the token is a network JWT from an auth code or a long-lived `urn_` API key (both in the fallback below) ## x402 — pay as you go The MCP server and the HTTP API both support x402: when a job hits a plan limit, the server answers `402 Payment Required` with machine-readable terms (`x402Version`, `accepts[]` — USDC, one accept per settlement chain). Payment settles on-chain through an x402 facilitator, so an agent pays on whichever quoted chain it holds funds on. Sign a payment for exactly the quoted amount and retry the same request with the `X-PAYMENT` header; the response carries an `X-PAYMENT-RESPONSE` settlement receipt. Availability: x402 is not switched on for this deployment yet. Until it is, `GET /x402/skus` answers an error instead of a sku list (today an HTTP 500; the intended not-enabled answer is 404 "x402 is not enabled."). Treat any answer other than a 200 with a JSON sku list as "not available": ask the human on the account to upgrade, and do not retry the purchase flow. - Public sku list (prices): `GET https://api.bringyour.com/x402/skus` - Quote terms without paying (requires an account JWT; nothing is charged without a signed X-PAYMENT): ``` curl -i -X POST https://api.bringyour.com/x402/purchase \ -H "Authorization: Bearer $URNETWORK_JWT" \ -d '{"sku_id": "pro_1month"}' ``` - Spend cap honored by the default skill: ``` URNETWORK_X402_MAX=25.00 ``` ## Fallback: auth code + proxies If OAuth is not an option in your runtime, sign in with an auth code instead: 1. A person signed in to the network creates an auth code at https://ur.io/app/account/settings and gives it to your agent, for example as `URNETWORK_AUTH_CODE=`. A code works once and expires after 5 minutes. 2. Exchange the code for a network JWT. This call takes no authentication: ``` curl -s -X POST https://api.bringyour.com/auth/code-login \ -H 'Content-Type: application/json' \ -d '{"auth_code": ""}' ``` The answer is `{"by_jwt": ""}`, the token the next calls send (as `$URNETWORK_JWT` below). An unknown, used or expired code answers `{"error": {"message": "Invalid auth code."}}`. 3. Send the JWT as `Authorization: Bearer `. For example, `POST /network/auth-client` with a `proxy_config` creates a client and returns its ready-to-use proxy endpoints in `proxy_config_result`: ``` curl -s -X POST https://api.bringyour.com/network/auth-client \ -H "Authorization: Bearer $URNETWORK_JWT" \ -H 'Content-Type: application/json' \ -d '{"proxy_config": {}}' ``` Pick the endpoint for the job: | Use case | Protocol | Where | | --- | --- | --- | | Scraping / web browsing | HTTPS proxy | `proxy_config_result.https_proxy_url` | | Low-level sockets / UDP | SOCKS5 (UR Pro) | `proxy_config_result.socks_proxy_url` (SOCKS5H supported) | | System-wide / OS level | WireGuard (UR Pro) | `proxy_config_result.wg_config.config` (set `proxy_config.enable_wg: true` in the request) | ### Long-lived API keys The JWT is tied to the session that created the auth code and ends with it. For access that outlives that session, create an API key with the JWT: ``` curl -s -X POST https://api.bringyour.com/account/api-key \ -H "Authorization: Bearer $URNETWORK_JWT" \ -H 'Content-Type: application/json' \ -d '{"name": "my agent"}' ``` The answer's `api_key` is a `urn_…` key, shown only in this answer. Send it wherever a JWT goes: `Authorization: Bearer urn_…`. `GET /account/api-keys` lists your keys and `POST /account/api-key/remove` with `{"id": ""}` revokes one. ## Skill The default skill wires the auth-code + proxy fallback path — including reading a 402, paying, and retrying — into your runtime: https://github.com/urnetwork/skill/blob/main/SKILL.md (For MCP-capable harnesses, the add-server recipes above are the whole setup; the skill is the path for runtimes without MCP.) --- # About URnetwork > We're building an internet that gives, not takes. ## The Problem Our access to content is moderately to severely restricted and controlled depending on where we are in the world. Corporate networks extract richly from the creators who make the internet interesting and from everyday users alike. Meanwhile sacrifices of privacy and security have ratcheting consequences and have become real concerns for people. ## But it doesn't have to be this way! We believe when networks are decentralized and employ modern security protocols, not only can we make them safe, but we put the users in control of what they do online and where their data goes, so we're not in the business of extracting value from our participants. We believe this is not only the right thing to do, it's the way the internet was supposed to be built in the first place! --- # Documentation index Every document, with its summary. Each renders at https://ur.io/docs/ and links to its source in the document's original format. - [URnetwork vs Apple iCloud Private Relay](https://ur.io/docs/compare-apple-private-relay) — Private Relay is the closest big-tech relative of URnetwork's split design; URnetwork applies the same idea to the whole device, in open code… ([markdown](https://ur.io/docs-md/compare-apple-private-relay.md)) - [URnetwork vs Cloudflare WARP](https://ur.io/docs/compare-cloudflare-warp) — WARP is free last-mile encryption into Cloudflare's network, and Cloudflare says itself that it is not an anonymity product… ([markdown](https://ur.io/docs-md/compare-cloudflare-warp.md)) - [URnetwork vs ExpressVPN](https://ur.io/docs/compare-expressvpn) — ExpressVPN is the premium flagship of the mainstream VPNs; URnetwork splits the path so the exit never learns who you are and the operator cannot read… ([markdown](https://ur.io/docs-md/compare-expressvpn.md)) - [URnetwork vs Hola VPN](https://ur.io/docs/compare-hola) — Hola is one of the most installed unblocking tools ever made, and its free tier is paid for by enrolling users' devices as peers in the Bright Data proxy… ([markdown](https://ur.io/docs-md/compare-hola.md)) - [URnetwork vs Hotspot Shield](https://ur.io/docs/compare-hotspot-shield) — Hotspot Shield built the original mass-market free VPN, ad-funded and speed-first; URnetwork splits the path so the exit never learns who you… ([markdown](https://ur.io/docs-md/compare-hotspot-shield.md)) - [URnetwork vs IPVanish](https://ur.io/docs/compare-ipvanish) — IPVanish is a long-running US datacenter VPN with unlimited devices and a 2016 logs handover on its record… ([markdown](https://ur.io/docs-md/compare-ipvanish.md)) - [URnetwork vs IVPN](https://ur.io/docs/compare-ivpn) — IVPN is the classic VPN with the cleanest conduct record and an annual published audit cadence; URnetwork splits the path so the exit never learns who you… ([markdown](https://ur.io/docs-md/compare-ivpn.md)) - [URnetwork vs Mullvad](https://ur.io/docs/compare-mullvad) — Mullvad is the most proven datacenter VPN; URnetwork splits the path so the exit never learns who you are and the operator cannot read the sealed session. ([markdown](https://ur.io/docs-md/compare-mullvad.md)) - [URnetwork vs Mysterium](https://ur.io/docs/compare-mysterium) — Mysterium is the most established paid-residential dVPN; URnetwork filters what leaves a member's line and splits the path so the exit never learns who you… ([markdown](https://ur.io/docs-md/compare-mysterium.md)) - [URnetwork vs NordVPN](https://ur.io/docs/compare-nordvpn) — NordVPN is the biggest and most polished name in consumer VPN; URnetwork splits the path so the exit never learns who you are and the operator cannot read… ([markdown](https://ur.io/docs-md/compare-nordvpn.md)) - [URnetwork vs NymVPN](https://ur.io/docs/compare-nymvpn) — NymVPN ships the strongest anonymity design in commercial VPN, a five-hop mixnet that is not its default mode… ([markdown](https://ur.io/docs-md/compare-nymvpn.md)) - [URnetwork vs Obscura](https://ur.io/docs/compare-obscura) — Obscura is the closest design to URnetwork's on the market, and on one axis it is ahead: its entry hop cannot read user traffic under any configuration. ([markdown](https://ur.io/docs-md/compare-obscura.md)) - [URnetwork vs Orchid](https://ur.io/docs/compare-orchid) — Orchid invented the pay-per-packet VPN marketplace and documents its own limits more candidly than most of the industry… ([markdown](https://ur.io/docs-md/compare-orchid.md)) - [URnetwork vs Private Internet Access](https://ur.io/docs/compare-pia) — Private Internet Access holds the strongest court-tested no-logs record of any VPN; URnetwork splits the path so the exit never learns who you… ([markdown](https://ur.io/docs-md/compare-pia.md)) - [URnetwork vs Proton VPN](https://ur.io/docs/compare-proton-vpn) — Proton VPN is the establishment pick, with annual published audits and the only unlimited-data free tier among major VPNs… ([markdown](https://ur.io/docs-md/compare-proton-vpn.md)) - [URnetwork vs Sentinel](https://ur.io/docs/compare-sentinel) — Sentinel decentralizes the coordinator, a public blockchain that matches you to an independent node; URnetwork keeps one accountable operator and splits every… ([markdown](https://ur.io/docs-md/compare-sentinel.md)) - [URnetwork vs Surfshark](https://ur.io/docs/compare-surfshark) — Surfshark is the value pick of the mainstream VPNs; URnetwork splits the path so the exit never learns who you are and the operator cannot read the sealed… ([markdown](https://ur.io/docs-md/compare-surfshark.md)) - [URnetwork vs Tailscale](https://ur.io/docs/compare-tailscale) — Tailscale connects machines you own into a private encrypted mesh; URnetwork is private egress to the public internet. ([markdown](https://ur.io/docs-md/compare-tailscale.md)) - [URnetwork vs Tor](https://ur.io/docs/compare-tor) — Tor is the strongest widely deployed anonymity network; URnetwork keeps the split-knowledge idea at everyday speed… ([markdown](https://ur.io/docs-md/compare-tor.md)) - [URnetwork vs TunnelBear](https://ur.io/docs/compare-tunnelbear) — TunnelBear is the simplest consumer VPN and the first to publish an outside security audit; URnetwork splits the path so the exit never learns who you… ([markdown](https://ur.io/docs-md/compare-tunnelbear.md)) - [URnetwork vs Windscribe](https://ur.io/docs/compare-windscribe) — Windscribe is the freemium VPN whose no-logs policy has passed a criminal court test; URnetwork splits the path so the exit never learns who you… ([markdown](https://ur.io/docs-md/compare-windscribe.md)) - [The comparison map](https://ur.io/docs/comparison) — This documentation compares URnetwork against twenty-one other networks, one document per product. This page is the overview: every product… ([markdown](https://ur.io/docs-md/comparison.md)) - [How the comparison map is scored](https://ur.io/docs/comparison-methodology) — The comparison map places twenty-two networks, URnetwork and every product in the twenty-one head-to-head pages, on two 0–10 indexes… ([markdown](https://ur.io/docs-md/comparison-methodology.md)) - [Comparison scores](https://ur.io/docs/comparison-scores) — This page is the complete scoring record behind the comparison map: every product's sub-scores on both axes, the anchor ladders they were assigned against… ([markdown](https://ur.io/docs-md/comparison-scores.md)) - [Comparison sensitivity](https://ur.io/docs/comparison-sensitivity) — This page records the two Monte Carlo stability tests behind the comparison map: resampling the axis weights across their whole space with the sub-scores… ([markdown](https://ur.io/docs-md/comparison-sensitivity.md)) - [Developers](https://ur.io/docs/developers) — Three things to build on URnetwork, and three different credentials. Picking the right one is the first decision, and the difference is not cosmetic. ([markdown](https://ur.io/docs-md/developers.md)) - [Embed](https://ur.io/docs/embed) — Whitelabel URnetwork into your own apps: your backend provisions a client for each installation, your apps embed the SDK… ([markdown](https://ur.io/docs-md/embed.md)) - [Extenders](https://ur.io/docs/extenders) — A feature-by-feature comparison of the accessibility protocols that keep everyday encryption usable on any network, with URnetwork's extenders and VLESS. ([HTML](https://ur.io/docs-md/extenders.html)) - [Frequently asked questions](https://ur.io/docs/faq) — Short answers about what URnetwork is, what it stores, and how to use it. The overview explains the full architecture… ([markdown](https://ur.io/docs-md/faq.md)) - [Getting started on Android](https://ur.io/docs/getting-started-android) — Getting started on Android: this guide takes you from nothing installed to connected, in about five minutes. ([markdown](https://ur.io/docs-md/getting-started-android.md)) - [Getting started in your browser](https://ur.io/docs/getting-started-browser) — This guide takes you from nothing installed to connected, in about two minutes, on any desktop OS. It covers install, sign-in, connecting, and where to get… ([markdown](https://ur.io/docs-md/getting-started-browser.md)) - [Getting started on iPhone and iPad](https://ur.io/docs/getting-started-ios) — This guide takes you from the App Store to connected, in about five minutes. It covers install, sign-in, permissions, connecting, and where to get help. ([markdown](https://ur.io/docs-md/getting-started-ios.md)) - [Getting started on Linux](https://ur.io/docs/getting-started-linux) — This guide takes you from nothing installed to connected. It covers the two-part install, sign-in, connecting, and where to get help. ([markdown](https://ur.io/docs-md/getting-started-linux.md)) - [Getting started on macOS](https://ur.io/docs/getting-started-macos) — URnetwork on the Mac is the same app as on iPhone and iPad, built native for macOS. This guide takes you from the Mac App Store to connected… ([markdown](https://ur.io/docs-md/getting-started-macos.md)) - [Getting started with the URnetwork SDK](https://ur.io/docs/getting-started-sdk) — Install the SDK with your language's package manager, then explore the language examples and socket guide. ([markdown](https://ur.io/docs-md/getting-started-sdk.md)) - [Getting started on Windows](https://ur.io/docs/getting-started-windows) — Getting started on Windows: this guide takes you from nothing installed to connected, in about five minutes. ([markdown](https://ur.io/docs-md/getting-started-windows.md)) - [Install the SDK](https://ur.io/docs/install-sdk) — Choose your language's native package manager. Go, JavaScript and C/C++ use the base Go, JS/WASM and CGo SDKs directly. ([markdown](https://ur.io/docs-md/install-sdk.md)) - [Integrate Provider](https://ur.io/docs/integrate-provider) — Run a URnetwork provider inside your app. Each installation provides as a client of your network and earns to one Bittensor wallet that you set once. ([markdown](https://ur.io/docs-md/integrate-provider.md)) - [How URnetwork works](https://ur.io/docs/overview) — URnetwork is a privacy network powered by its members. Your traffic exits through another member's device, not a datacenter VPN server. ([markdown](https://ur.io/docs-md/overview.md)) - [Sign in with URnetwork](https://ur.io/docs/sign-in-with-urnetwork) — Let people admit your app or agent to their private network, so it can coordinate with everything else they have running there. ([markdown](https://ur.io/docs-md/sign-in-with-urnetwork.md)) - [Socket](https://ur.io/docs/socket) — Use an SDK socket to connect your application's TCP or UDP client through a URnetwork Device. It has familiar reads, writes, deadlines, and close behavior… ([markdown](https://ur.io/docs-md/socket.md)) - [Threat model](https://ur.io/docs/threat-model) — This section is for readers who will not read the full record. Each sentence in it is backed by a numbered section below or by the assurance statement above. ([markdown](https://ur.io/docs-md/threat-model.md)) - [The Android app, in depth](https://ur.io/docs/tour-android) — This is the deep dive: every major surface of the Android app, its settings with their shipped defaults, and the troubleshooting that goes with them. ([markdown](https://ur.io/docs-md/tour-android.md)) - [The browser extension: the tour](https://ur.io/docs/tour-browser) — The extension is URnetwork inside the browser, and the ur.io web app is its control plane: one product, two halves. ([markdown](https://ur.io/docs-md/tour-browser.md)) - [The iOS app, in depth](https://ur.io/docs/tour-ios) — This is the deep dive: every screen of URnetwork on iPhone and iPad, the settings with their shipped defaults… ([markdown](https://ur.io/docs-md/tour-ios.md)) - [The Linux app, in depth](https://ur.io/docs/tour-linux) — This is the deep dive: every major surface of the Linux app, what it controls, its defaults, and how to fix it when something breaks. ([markdown](https://ur.io/docs-md/tour-linux.md)) - [The macOS app, in depth](https://ur.io/docs/tour-macos) — URnetwork on the Mac is built from the same Xcode project as the iPhone and iPad app: one codebase, one engine, two window shapes. ([markdown](https://ur.io/docs-md/tour-macos.md)) - [A tour of the URnetwork SDK](https://ur.io/docs/tour-sdk) — This is the deep dive behind getting started: how each of the four bindings is put together, the defaults it ships, and the sharp edges we know about. ([markdown](https://ur.io/docs-md/tour-sdk.md)) - [The Windows app, in depth](https://ur.io/docs/tour-windows) — This is the deep dive: every major surface of the Windows app, what it controls, its defaults, and how to fix it when something breaks. ([markdown](https://ur.io/docs-md/tour-windows.md)) --- # How URnetwork works URnetwork is a privacy network powered by its members. Your traffic exits through another member's device, not a datacenter VPN server. Websites see that device's IP address instead of yours. This overview explains the path and what each party can see. The exits are thousands of member devices across more than 2,000 real cities in 90+ countries, not virtual IPs served from a handful of datacenters. The live counts are published at `api.bringyour.com/stats/last-90`. ## The path Traffic takes four legs: you → extender → operator → provider → internet. - **Client.** The app or SDK instance on your device. A *network* is URnetwork's word for your account, the billing and identity unit; it can hold many users, devices, and clients. - **Extender.** A volunteer-run forwarding hop on an independent address, and the first leg. It forwards your encrypted session to the platform without terminating it, so it carries bytes it cannot read. As your first hop, it does see your IP address. - **Operator.** BringYour, Inc., the party that coordinates the network. Its platform (`connect.bringyour.com`, `api.bringyour.com`) authenticates clients, matches you with providers, relays traffic, and handles contracts and payments. - **Provider.** A member device that shares its internet connection and forwards your traffic to the internet, so websites see a residential address in the provider's city. The operator and the provider are the two relay parties, and the design splits knowledge between them. The extender is a reachability hop outside that split and adds no encryption of its own. It keeps the network reachable where the platform is blocked. ![The path: four legs, split knowledge — what each party can and cannot see](/docs-assets/diagram-the-path.svg) ## Who can see what With the seal on, no single party holds both your identity and your activity. That statement rests on two properties with different scopes, and only the first holds without touching a setting. **The provider never learns who you are.** The operator stands between you and the provider, so the provider sees a device id and the destinations it serves, never your address. This holds on every relayed path, with no setting to get wrong. **The operator cannot read what you send, once the session is sealed.** The native apps seal the client↔provider session end to end when you switch on Post Quantum Encryption, and the operator then carries ciphertext plus timing and volume. The switch ships off, so a fresh install runs the standard path in the table below: the operator relays packets it can read, and what keeps your destinations out of its records is discipline, not encryption. The browser extension and the proxy endpoints have no sealed session at all. That is scope, not a default, and it is architectural: a browser or a plain proxy client cannot run the network's engine, so the operator runs the client's device remotely and translates between protocols — a seal started from that device would begin inside the operator, the party it exists to blind. The implementation traded the seal for reaching those platforms at all. There, storage discipline pinned by a test, not encryption, keeps the operator from accumulating your destinations ([threat model](/docs/threat-model) §2.4). | Mode | Operator sees | Provider sees | Default and availability | |---|---|---|---| | **Relayed sealed** | account/source connection, provider association, ciphertext and timing/volume | destination traffic, device/contract id, **not** your real source IP | the native apps, opt-in: switch on Post Quantum Encryption, which ships off | | **Relayed standard** | account/source connection, provider association, inner destinations and packet bytes | destination traffic, device/contract id, **not** your real source IP | the native default, out of the box, since the seal ships off; the browser and proxy paths always; with the seal on, a provider that cannot be sealed to is skipped rather than served here | | **Direct** | less relay involvement | **your real source IP** and destination traffic | opt-in, by disabling Strong Anonymization | The table is canonical. The [threat model](/docs/threat-model) works the same split against named adversaries, including a hostile operator and colluding providers. ## Why four legs Speed is a design goal, not a concession. Every extra hop lengthens the round trip between you and the internet, which is why long chains hurt for everyday use. Bounding the path at four legs keeps the knowledge split at streaming-class speed. URnetwork puts average streaming speed on the network at 40 Mbps+. The formal description is a latency-bounded multi-hop with data separation. The wire protocol supports chaining additional provider intermediaries; the shipping network uses the single-provider path. Other designs make other trades. Tor pays for longer chains in latency. Apple's Private Relay is an encrypted two-party split, inside closed implementations, with both parties selected and paid by one company. Most VPNs attempt no split at all. The [comparison map](/docs/comparison) covers these product by product. ## What happens when you connect 1. **Sign in.** The app signs in with a token that expires in about a day and refreshes automatically, so a stolen token goes stale fast. Engineers call it a JWT. Accounts can use email or phone, Google or Apple sign-in, a Solana or Bittensor wallet signature, a seed phrase, or a one-tap, email-free Instant Account whose whole credential is a recovery seedphrase. The phrase is comparable to Mullvad's numbered accounts and survives a reinstall; the server generates it, shows it once, and keeps only hashes, so losing it loses the account. 2. **Reach the platform.** The client opens an encrypted channel to the platform: TLS over WebSocket, or QUIC/HTTP-3 where the network allows it. The channel runs through an extender and terminates at the platform. Direct routes are raced first; the extender leg takes over when they fail. 3. **Find providers.** The client asks for providers matching your selection: best available, a country from the list, or a city you find by typing its name into the search box. The platform scores candidates continuously on reliability and measured speed and returns a ranked set. 4. **Open contracts and go.** The client holds a *window* of several providers and balances your connections across them. The default profile runs two windows: a quality set of 2–6 providers for HTTPS, and a speed set of 1–2 for everything else. Three to eight providers are typically live. Connections to a given site stay pinned to one provider, so that site sees one stable address for your whole session. A provider that underperforms or drops is replaced; the rest of the window absorbs its work. Every byte moves under a *transfer contract*, the accounting unit that meters what each provider carries. ![Plural exit identity: the provider window — per-site affinity and failover](/docs-assets/diagram-provider-window.svg) Your exit identity is plural: several providers at once, churning over time, so no single exit sees more than a slice of your browsing. The window is also the speed strategy: residential connections vary more than datacenter servers, and shedding slow ones keeps streaming smooth. ## Encryption The client↔platform channel is always encrypted: TLS 1.3 or QUIC. **The sealed session.** With the seal on, the app encrypts traffic all the way to the provider, so the operator relays bytes it cannot read. What reaches it is ciphertext plus timing and volume. The control is named **Post Quantum Encryption** in the connect drawer of the Android, iOS, macOS, Windows and Linux apps, and it ships off in all five: a fresh install is unsealed until you switch it on. The seal is a TLS 1.3 handshake directly between client and provider, with the hybrid post-quantum key exchange **X25519MLKEM768** and AES-256-GCM per message. Identity keys are Ed25519; "post-quantum" refers to the key exchange only. Scope: with the seal on, a provider that cannot establish it does not carry your traffic at all. The client refuses to send application data in the clear rather than quietly falling back — a provider that cannot be sealed to is skipped, not used unsealed. Every current provider build supports the seal, so this mostly affects older builds, and it costs availability rather than confidentiality. With Post Quantum Encryption off, as it ships, the client opens no session to the provider at all, and every packet takes the standard path, where the platform can read packet addresses and contents. Limit: no app yet reports whether a given connection is sealed. That gap is real but it is no longer the dangerous one — you cannot be silently downgraded while the seal is on. This and everything else URnetwork does not defend against is set out in the [threat model](/docs/threat-model). **Strong Anonymization, and direct mode.** A provider sees the destination addresses of the traffic it serves, as your ISP does today. It does not learn who you are: by default it never sees your real IP, only the platform does. That default is the **Strong Anonymization** switch in the connect drawer, which ships on. Turning it off opts into *direct mode*: the client talks straight to the provider and throughput goes up. The cost: that provider now sees your real address. Hosted profiles force direct mode off regardless. ![What the sealed session changes — standard path vs sealed session, and what happens when a provider cannot be sealed to](/docs-assets/diagram-sealed-session.svg) ## What each party can see | Party | Sees | Does not see, or does not keep | |---|---|---| | Operator (platform) | your account; your address at the moment you connect; a coarse city/region/country derived from it; which providers you used; byte counts; with the seal on, ciphertext with its timing and volume, and with it off, as it ships, the packets themselves | packet destinations and contents, once the seal is on; your raw address (a keyed block-hash instead); any destination field in the transfer ledger | | Provider | destination IPs/SNI of the traffic it carries out; a device id carried by the contract | your identity or real IP on the relayed paths; only the operator can resolve the device id to an account | | Extender | encrypted bytes; your IP | anything inside the tunnel | | Website | a residential provider address | your IP; your ISP identity | Behind the operator row: - The stored form of your connecting address is a keyed one-way hash of the surrounding /29 (IPv4) or /56 (IPv6) block, not the address itself. A coarse city/region/country derived from the address is kept per connection. - The discipline is in code, not only policy. HTTP logging passes a five-header allowlist. The transfer ledger records client and network ids and byte counts, with no destination, host, URL, SNI, port or domain field to write into. The proxy data path logs nothing, pinned by a regression test. - The seal makes your traffic unreadable to the operator. Storage discipline covers what the operator still sees (provider associations, byte counts, coarse location) and stands in where there is no seal: the browser extension, the proxy endpoints, and the native apps with the seal off. - Limit: these are properties of the records the code writes. The ingress load balancer's access logs were never audited, and address- and SNI-bearing lines reach service stderr, whose production destination is not established. Full record: the [threat model](/docs/threat-model). ![What the operator stores — and what never exists](/docs-assets/diagram-what-is-stored.svg) ## Open source, and what is not audited The entire stack is open source: apps, SDK, protocol engine, and the operator's own server code, so the mechanisms described here can be read rather than taken on trust. Open source proves the design, not which build is deployed. No independent audit covers the protocol, the connect engine, or the operator's server code, where the privacy claims live. Two 2025 third-party assessments cover other surfaces. One is an independent penetration test of the web application and API (April–May 2025). The other is a Leviathan Security Group MASA AL2 assessment of the Android app, which passed; Leviathan scopes it as not a holistic security evaluation. Open code under permanent scrutiny is URnetwork's answer to the yearly point-in-time audit. Full record: the [threat model](/docs/threat-model). ## Safe to share: the ip_security layer Sharing a connection should not mean inheriting a stranger's legal risk. The provider client ships `ip_security`, an open-source traffic-security layer in the connect engine and one of its largest components. It inspects the provider's own egress, its exit to the internet. Risky traffic is blocked before it leaves the member's connection: - **DMCA-class filtering.** A stateful detector recognizes BitTorrent by its signatures on any port, 443 included. On ports 1024 and above it also drops opaque traffic. A flow whose payloads look like random data and match no recognized protocol is dropped at its third such payload, since encrypted file-sharing looks the same. Infringing peer-to-peer transfers do not exit the member's line. - **CFAA-class filtering.** Addresses on public botnet, malware and hijacked-network lists are blackholed, and so are BitTorrent's usual ports and the ports below 1024 that everyday apps do not use, so the connection is not the launch point for someone else's intrusion. - **A detector built not to see.** The file-sharing check clears the server name from its own flow key. It decides on addresses, ports and the leading bytes of a flow's first few packets, and tallies its counters by protocol and port, never by address. What the rules let through, on your device and on the provider's: - **Recognized protocols** pass the opaque-traffic check: TLS, DTLS and QUIC; WebRTC's STUN, TURN and RTP; WireGuard and OpenVPN; RTMP, RakNet and Monero's Levin; and Ethereum's discovery v4 and RLPx. So do WhatsApp, Steam traffic to Valve's own servers, and plaintext that is not BitTorrent. - **Low ports.** Below 1024, the open ports are 443 for HTTPS and QUIC, 80 for plain HTTP, 53 for plain DNS over UDP and 853 for DNS over TLS. Secure mail on 465, 587, 993 and 995, time on 123, VPN key exchange on 500 and 4500 and Telegram's call relays stay open too. Other low ports, such as SSH on 22, are dropped. SMTP on port 25 never uses a provider: your device sends it over your own connection, even with the kill switch on. - **Dropped by design.** Protocols that look random from their first byte cannot be told apart from encrypted file-sharing. Mosh, ZeroTier, Bitcoin's encrypted v2 transport, obfs4, Ethereum's discovery v5 and game or voice protocols with their own encryption are among them. A match produces a dropped packet. A BitTorrent match also emits an abuse flag to the operator: the peer's device id and a boolean, with no destination, domain or contents. The operator ships no handler for the flag today, so nothing is stored on receipt. Opaque-protocol drops are silent, with no report. The layer runs at the edge, on both sides of it: on your device when you connect, and on the provider's device, where traffic exits. The operator does not inspect traffic centrally, and the seal does not bypass the filter, because the filter runs at the endpoints the seal connects. Your device stops a signature, port or address match before it goes to a provider. An opaque flow is decided only at its third payload, after its first packets have gone to a provider. Your device then ends the flow: the app gets a TCP reset, or an ICMP port unreachable for UDP. In the apps, the kill switch decides what happens next. With it on, dropped traffic stops, and for ten minutes new connections to an ended opaque flow's destination are refused at once. With it off, dropped traffic leaves over your own connection instead, outside the tunnel and with your own address. A port or address drop goes there from its first packet, and after an opaque flow ends, so do the app's new connections to its destination, for ten minutes. BitTorrent signatures and non-public destinations are blocked either way. Most countries have CFAA- and DMCA-family laws; one standard answers them at every exit, and URnetwork follows the law wherever it distributes. The filter is maintained, not frozen: its threat lists are regenerated at release from public malware, abuse and botnet feeds (Spamhaus DROP, abuse.ch's botnet tracker, Emerging Threats and others), so an up-to-date app blocks the latest known-bad address space. A provider applies the rules of its own release, so a protocol that only a newer release recognizes can still be dropped there. After such a drop your device prefers providers with current rules for a few minutes. The [terms of service](/terms) cover providing. ![ip_security: enforcement at the edge, without surveillance — matched traffic is blackholed at the provider's own egress](/docs-assets/diagram-ip-security.svg) ## Getting through blocks Extenders carry the path through local and regional firewalls. Each one answers TLS on believable service ports (443, DNS-over-TLS 853, LDAPS 636, and others) and presents to scanners like a misconfigured CDN. Each is hard-coded to forward the encrypted stream to the platform on an address of its own, so blocking `connect.bringyour.com` does not block the way in. The client rotates through generated extender personas, with randomized packet fragmentation and reordering, until one works. Where only DNS escapes, a DNS-shaped transport reshapes QUIC packets as DNS queries and answers. Anyone can run an extender. ![Getting through blocks: extenders and the DNS-shaped transport](/docs-assets/diagram-getting-through.svg) ## Providers and coverage Locations are presence-backed: a city is offered only while a member's device is online in it. The platform geolocates the connection it observes; a provider cannot declare its own city. An address that looks like a datacenter, a VPN or a re-announced range is demoted rather than trusted. Limit: no outside party has measured the fleet, and nothing verifies that the providers offered to one client are independent of each other or of the operator. See the [threat model](/docs/threat-model). Providing is opt-in sharing of spare bandwidth: off until you switch it on, Wi-Fi-only unless you allow cellular, and pointed at either public traffic or your own devices alone. Public traffic is metered: the platform stamps each transfer contract with a secret only that provider holds, so the provider can check a contract is genuine and for the audience it agreed to. The escrow is denominated in bytes; both ends report what they carried, and the settled figure is their average within a tolerance. Providers participate in the UR protocol; [ur.xyz](https://ur.xyz) documents rewards, and this page does not restate them. Free tiers exist because paid members fund the network's growth. Anyone can provide. ## Plans and the operator API There are two plans: a free tier with a daily data allowance, and Pro with a large monthly allowance, more concurrent clients, and the proxy and WireGuard conveniences. Pro can be paid by card, or from a wallet in USDC on Solana, Monero or shielded Zcash. The allowance is metered, not throttled: when it runs out, the network stops opening new transfers rather than slowing you down. The tunnel goes quiet, your own connection is untouched, and the allowance refills on its cycle. Current numbers are on [ur.io/products](https://ur.io/products), machine-readable at `GET https://api.bringyour.com/x402/skus`. Everything the apps do goes through the public operator REST API (auth, devices, provider discovery, subscriptions, stats), documented in the [API reference](https://ur.io/docs/api). Agents get first-class access: an MCPv2 server at `mcp.bringyour.com` (OAuth; `providerLocations` and `fetch` tools) and x402 pay-per-need purchasing. See [ur.io/agents](https://ur.io/agents). ## Fallback endpoints: HTTPS, SOCKS5, WireGuard For software that cannot embed the SDK, the operator runs bridge endpoints: an HTTPS CONNECT proxy, SOCKS5, and a WireGuard endpoint for stock WireGuard apps. SOCKS5 supports CONNECT and UDP associate; BIND is not supported, and UDP datagrams over 2 KiB are dropped by design. Limit: the WireGuard path assigns one stable tunnel address from a platform-allocated private pool, not your real IP. That stable address lets one client be correlated across providers, and the endpoint hands the client a fixed public resolver (1.1.1.1). The apps and SDK remain the most private way to use the network. ## Where to go next - Set up: the [getting started guides](/docs) for Android, iOS, macOS, Windows, Linux, the browser extension, and the SDK. - Per-platform depth: the tour docs. - Other products: the compare docs and the [comparison map](/docs/comparison). - The protocol: [ur.xyz](https://ur.xyz) for the whitepaper, economics, and provider rewards. --- # Frequently asked questions Short answers about what URnetwork is, what it stores, and how to use it. The [overview](/docs/overview) explains the full architecture, and the [threat model](/docs/threat-model) keeps the complete technical record. ## The basics ### Is URnetwork a VPN? It does what you use a VPN for: it encrypts your traffic and changes the address websites see. The architecture differs. A VPN concentrates everyone into datacenters with publicly catalogued IP ranges. URnetwork exits through members' real residential connections in 2,000+ real cities across 90+ countries. The path is you → extender → operator → provider → website. On the relayed path the provider never learns who you are, and the apps can seal traffic to the provider once you switch on Post Quantum Encryption, which ships off. The [overview](/docs/overview) explains what each party sees. ### Do I have to share my internet to use it? No. Using the network and providing to it are separate switches. Installing an app never turns your device into an exit for anyone else. Providing is opt-in; see "Sharing your connection" below. ### Is it really free? Yes. The free tier is a daily data allowance, with no card required, and it is not a trial. Paid members (UR Pro) fund the network, and the free allowance refreshes every day out of that. There is no ad or data-sale model. Current allowances and prices: [ur.io/products](https://ur.io/products). ### Who is behind URnetwork? BringYour, Inc., a Delaware, USA company, operates the network. Everything is open source at [github.com/urnetwork](https://github.com/urnetwork): the apps, the SDK, the protocol engine, and the operator platform. The protocol effort is documented at [ur.xyz](https://ur.xyz). ### Has URnetwork been audited? No independent audit covers the protocol, the connect engine, or the operator's server code. That is the layer the privacy claim rests on. Two third-party assessments from 2025 cover other surfaces. **Web application and API:** a credentialed, manual penetration test by an independent firm, April to May 2025, against the OWASP Top 10 with a review of OWASP ASVS controls. **Android app:** a Leviathan Security Group assessment under Google's App Defense Alliance MASA programme, May 2025, at assurance level AL2. It passed. Leviathan states the work "should not be read as a holistic security evaluation or comprehensive penetration test," and it covers Android only. Neither assessment examined logging, retention, or the data path. What URnetwork offers instead is continuous verification: all code is public, F-Droid rebuilds the Android app from published source, and egress is a fleet of member devices rather than one custodian. ### What platforms can I use? All of them: Android (Play, F-Droid, Solana dApp Store, direct APK), iPhone and iPad, macOS, Windows, Linux, browser extensions for Chrome, Edge and Firefox, and a web app at ur.io. Every app is open source. Each platform has a getting-started guide in these docs. ### Does it cover my whole device, or just my browser? The OS apps cover the whole device. Android, iOS, macOS, Windows, and Linux tunnel everything the device sends: mail, music, games, updates, not only the browser. The browser extension covers browser traffic. The ur.io web app is the extension's control plane, not a separate product: sign in once on the web and it sets up, connects, and re-points the extension for you. ### Can I run URnetwork alongside another VPN? Not as two device tunnels. An operating system runs one system VPN at a time, so URnetwork and a work VPN cannot both cover the whole device. The browser extension is a proxy, not a VPN, so it can run on top of another VPN and cover browser traffic while the other VPN holds the device. ## Privacy ### Can URnetwork itself see what I do? Not once you switch on Post Quantum Encryption, which ships off. The provider sees the destinations it carries but never learns whose traffic it is; the operator stands in between, knowing your account and which provider carried you. With the seal on, the session is encrypted end to end to the provider: the operator cannot read what you send, and no single party sees both who you are and what you do. With it off, the default, the operator relays packets it can read. It parses only the routing header and writes no destination to its ledger, but that is discipline, not encryption. | Mode | Operator sees | Provider sees | Default and availability | |---|---|---|---| | **Relayed sealed** | your account and source connection, provider association, ciphertext, timing and volume | destination traffic, device and contract id, **not** your real source IP | the native apps, opt-in: switch on Post Quantum Encryption, which ships off | | **Relayed standard** | your account and source connection, provider association, inner destinations and packet bytes | destination traffic, device and contract id, **not** your real source IP | the native default, out of the box, since the seal ships off; the browser and proxy paths always; with the seal on, a provider that cannot be sealed to is skipped rather than served here | | **Direct** | less relay involvement | **your real source IP** and destination traffic | opt-in, by turning off Strong Anonymization | Comparing notes gets them little: the operator writes no destination to its ledger and cannot read one through a sealed session, and the provider holds no identity to contribute. **Limit:** provider independence is not measured, and the operator could itself run providers. See the [threat model](/docs/threat-model). ### What does URnetwork log? URnetwork's main service records do not contain a browsing history. **It stores:** account details you provide, a keyed hash of your IP block, an approximate city, provider associations, and byte counts. **It does not store in the transfer ledger:** destinations, hostnames, URLs, SNI, or ports. **Limit:** the ingress load balancer's access logs have not been audited, and the production destination of service stderr is not established. See the [threat model](/docs/threat-model) for the full record. ### If police show up with a warrant, what can be handed over? Only what is stored can be handed over, and no browsing history is stored. **What exists:** keyed hashes of address blocks, an approximate city per connection, client ids, byte counts, and your sign-up details. The sign-up details are what can name you: an email or phone number if you gave one, a wallet address, a payment record. **Limit:** BringYour is a US company and can be compelled like any operator. What is stored decides the outcome. The [threat model](/docs/threat-model) itemizes the records. ### Who are the providers? Members. A provider is anyone who runs the app and turns providing on, sharing their connection as an exit. Assume some are curious. **Limit:** provider independence is not measured, and nothing prevents the operator from running providers itself. The [threat model](/docs/threat-model) works through the hostile-provider case. ### Can a provider see what I do? A provider sees what an ISP sees, for the slice of traffic it carries: destination addresses and site names. It does not learn who you are; your real IP stays with the operator unless you opt in to direct mode. It does not read your contents; HTTPS stays end-to-end encrypted to the site. ### Can a provider tamper with my traffic? Not by impersonating a site. Certificate checking happens in your browser, so a provider faking your bank produces a warning, not a working copy. Running many providers gains an attacker little; no provider learns whose traffic it carries. The hostile-provider case is worked through in the [threat model](/docs/threat-model). ### If everything is HTTPS already, why do I need this? HTTPS hides what you send. It does not hide who you are or where you went. Your ISP, your employer, and every café network still see the name of each site you connect to, and each site sees an address that identifies your household. URnetwork moves that trail to parties that each hold only a fragment of it. Encryption and anonymity are different problems. ### What does my own ISP see? An encrypted tunnel and nothing inside it. Your ISP sees that your device holds a TLS/QUIC connection to the network, or to an extender that looks like an ordinary service, plus volume and timing. Destinations and contents travel inside the tunnel. ### What does "post-quantum" cover? It seals the session between your app and the provider once you switch it on; it ships off. With it on, the operator in the middle carries bytes it cannot read. The key exchange is X25519MLKEM768, a hybrid of a classical curve and the NIST-standardized ML-KEM, so traffic recorded today cannot be decrypted by a future quantum computer. It covers that session's key exchange; identities stay Ed25519. **Limit:** the browser extension and the proxy endpoints have no sealed session, and cannot: their client device runs inside the operator, which translates the browser's or proxy's protocol into the network's. A seal started there would begin at the operator. See the [threat model](/docs/threat-model) for the full mechanism. ### How do I know the sealed session is on? It starts off, so the first answer is to check the switch. The control is named Post Quantum Encryption and lives in the connect drawer, not in Settings; a fresh install is not sealed until you turn it on. Every current provider build supports the provider side. The stronger answer is that while it is on you cannot end up unsealed without knowing. The client refuses to send or accept your traffic in the clear, so a provider it cannot establish a session with is skipped rather than used unsealed — you lose that provider, not your encryption. What the app still cannot do is show a per-connection sealed-or-not verdict; that indicator has not been built yet. ## Using it ### How do I check it's actually working? Open [ur.io/ip](https://ur.io/ip). It shows the address and city the internet currently sees for you, whether that address is connected through URnetwork, and both your IPv4 and IPv6. The IPv6 line catches a half-configured setup. Different sites reporting different exits is normal here, not a fault. ### Will my bank lock me out? It shouldn't: your bank sees one steady residential address for the whole session, which raises fewer fraud flags than a shared datacenter IP. The client pins each site to one provider, so the address does not change mid-session. Banks react to sudden country jumps more than to addresses. Pick a location near you, or keep the bank off the tunnel with a split rule. ### Why do different sites see different IP addresses for me? Because your traffic exits through several providers at once, commonly three to eight. Per-site affinity keeps each site on one provider, so any single site sees one steady address. The variety is across sites, not within one. ### What do I do when a site blocks me or floods me with CAPTCHAs? Disconnect and reconnect, which draws a fresh provider window and fresh exit IPs, or pick a different city. Residential addresses attract fewer wholesale blocks than datacenter ranges, but none is pristine: a home IP can carry history from whoever held the lease before. For one stubborn site, add a split rule that routes it around the tunnel. ### Can I keep one app, like my banking app, off the tunnel? Yes. Per-app split tunneling is available on Android and Windows: pick the apps that bypass the tunnel, and everything else stays inside it. Split rules by domain or IP address are available on Android, Apple platforms, Windows, and Linux, so you can exempt one bank's domain without exempting a whole app. ### Is there a kill switch? Yes, on every platform: a toggle in each app on Android, iOS, macOS, Windows, and Linux, plus the extension's own. When no provider is reachable, the client refuses to fall back to your ordinary local route, so traffic stops. The app toggles start off; the extension's starts on. Android adds an OS-level mode that holds even if the app dies (Always-on VPN plus Block connections without VPN). **Limit:** on iOS and macOS, enforcement is client-level. Kill the tunnel process outright and the system restores normal networking. ### Which location should I pick? "Best available" picks the highest-scored providers near you and is the right default for speed. Browsing the list shows countries. To land somewhere specific, type a place name and a Cities section appears in the results. The provider count shown per location is live. ### Can a provider fake its location? Not by declaring one. The operator works out where a provider is from the connection it observes, so a provider cannot type in a city it is not in. A location is listed only while a member's device is online in it. **Limit:** this is an address-derived estimate. An address that looks like a datacenter, a VPN, or a re-announced range is demoted rather than trusted, not excluded outright. ### How fast is it? URnetwork puts average streaming speed on the network at 40 Mbps+. Speed is a design goal: the path stops at four legs instead of chaining hops, to keep latency down. Your own figure varies, because traffic rides through another member's real connection; their uplink and their distance from you both count. The client replaces slow providers automatically, so a member closing their laptop usually means a brief stall, not a dropped session. ### How do I make it faster? Reconnect, or pick a nearer city. The remaining speed setting is a trade: Strong Anonymization, on by default, is what keeps the operator between you and the provider. Turn it off and the client connects directly to the provider. That is faster, and that provider then sees your real IP address. Make the trade knowingly. ### Does it drain my battery? The battery cost is that of any VPN tunnel. The Android service also backs off under battery-saver and thermal pressure. ### Can I torrent through it? No. BitTorrent is dropped deliberately: a member's home connection would receive the complaint, and no filter can tell a Linux ISO from a movie. Connecting first does not get around the check, because it also runs on your own device. Plaintext BitTorrent is stopped there before it reaches a provider, and encrypted BitTorrent within a flow's first few packets. **Limit:** the kill switch decides what happens to retries. With it off, after your device drops an encrypted torrent connection, your torrent app's retries to that peer leave over your own connection for ten minutes, outside the tunnel and with your own address. With it on, they stop. ### How is torrenting detected without recording what I do? By checks at the edges, not by central monitoring. Signatures catch plaintext BitTorrent on any port, and encrypted file-sharing falls to the rule against opaque traffic that matches no recognized protocol. The checks run on the provider's device where traffic exits, past the end of the sealed session, so the operator inspects nothing. A signature match drops the packet and raises a flag carrying only the peer's device id and a yes/no: no destination, no domain, no contents. The operator has no handler for that flag today, so nothing is stored on arrival. Other drops raise nothing at all. See the [threat model](/docs/threat-model). ### Can I run an Ethereum node through it? The execution client, yes, with discovery v4 left on. The security filter drops traffic that looks like random data and matches no recognized protocol, because encrypted file-sharing looks the same. An up-to-date filter recognizes Ethereum's discovery v4 and RLPx peer connections by cryptographic checks on their packets, so both pass. Discovery v5 cannot be recognized, so it is dropped: its packet headers are masked with the receiving node's id, which a provider never sees. Leave discovery v4 enabled in your execution client. With the kill switch off, your own device sends discovery v5 over your local connection instead, outside the tunnel; with it on, discovery v5 stops. **Limit:** a consensus client discovers peers only over discovery v5, so its discovery does not work through the tunnel. ### Does URnetwork work where VPNs are blocked? It is designed to. The extender leg is community-run relays on their own addresses, answering on believable service ports, plus a DNS-shaped transport for networks where only DNS gets out. Blocking the platform's name does not block the way in, because each extender forwards from its own address. The client races direct routes first and falls back to extenders; there is no promise against every censor. An extender cannot read what it carries, and as your first hop it does see your address. ### What are the HTTPS/SOCKS5/WireGuard endpoints? They are bridges for software that cannot run the apps or SDK: a router, a stock WireGuard client, a tool that only speaks SOCKS. The apps remain the most private path. The WireGuard bridge shows the trade. The tunnel address is one the platform allocates, not your home address. But it stays fixed for the life of the profile and is reused with every provider, so providers could link those flows to one client. The bridge has no sealed session and cannot have one: your endpoint of it runs inside the operator, which translates WireGuard into the network's own protocol. One public DNS resolver is hard-coded into the profile. Profile export is a Pro feature, created in your ur.io account. See the [overview](/docs/overview). ## Sharing your connection ### Can I earn by sharing my connection? Yes. Turn on providing in the app, or run the provider CLI on a spare machine. Public traffic you carry is metered under signed contracts, and providers participate in the UR protocol; [ur.xyz](https://ur.xyz) documents how rewards work. You can also restrict providing to your own devices, unpaid. ### What does providing cost me? It costs uplink and ISP data, within limits you control. Providing uses your uplink and counts against your ISP's data cap, so it suits a device on a charger. It never spends your own URnetwork allowance. It is set to Wi-Fi only out of the box, so it will not spend your mobile data. ### If someone does something illegal through my line, do police come to me? Sharing is engineered so the traffic that draws complaints never leaves your connection. The connect engine's ip_security layer runs on your own device and drops copyright-class file-sharing and intrusion-class attack traffic at your egress. The categories that produce DMCA notices and abuse reports are removed at the source. Its threat lists are rebuilt from public malware, abuse and botnet feeds with each release, so keeping the app updated keeps the filter current. The full mechanism is in the [threat model](/docs/threat-model), and the [terms of service](/terms) cover providing. ## Accounts and billing ### How do I pay? Card via Stripe, or crypto: USDC on Solana, Monero, or shielded Zcash. USDC is a dollar-pegged stablecoin; Solana Pay handles it today, and x402 lets an agent pay in-band on any quoted chain. Monero and Zcash go to a one-time address on URnetwork's own nodes, so no payment processor sees them. A crypto payment is one-time: it buys its plan or data pack for the stated term and does not renew. Card numbers stay with the payment processor. Current prices: [ur.io/products](https://ur.io/products). ### How anonymous is payment? You can pay without attaching a name. One tap creates an email-free Instant Account backed by a recovery phrase, the mechanism numbered-account VPNs use. Wallet sign-in works by signature only; URnetwork never asks for a wallet's seed phrase or private key. What the payment itself reveals depends on how you pay. Card payments identify you to the payment processor. A USDC payment is public by nature: a public ledger leads back to the paying wallet. Monero and shielded Zcash show no sender or wallet to us or to anyone reading the chain. Whichever you use, we know which account paid, how much and when. We keep the link between a cryptocurrency payment and the account it paid for, for 30 days after the payment is credited. Until then the transaction reference is kept against your account; then the link is removed. **Limit:** support cannot recover a secret account. Write the recovery phrase down. ### What happens when I hit the free daily limit? Traffic through URnetwork stops until the allowance refreshes the next day. It is a stop, not a slowdown: a transfer in flight fails rather than crawls, and the app reports that the balance is out. Your device's own connection is untouched; disconnect and you are back on your ordinary line. Upgrade to Pro for the monthly multi-terabyte allowance, or top up with a one-time data balance code, no subscription required. ### How do I delete my account? Settings → Delete account in the Android, iPhone/iPad, and macOS apps, or in your account settings at [ur.io](https://ur.io). The web app is the place to do it if you use Windows, Linux, or the extension. Deletion removes your account and associated personal information. ## Troubleshooting ### What do I do if it won't connect? Try three things first. 1. Toggle the connection off and on. The client draws a fresh provider window. 2. Check that the OS granted VPN permission. Android: accept the first-run consent dialog in the app, not the quick tile. iOS and macOS: approve the VPN profile in Settings. 3. On a hostile network, give it a minute while the client rotates through transports and extenders. On a hotel or airport portal, disconnect, sign in to the Wi-Fi, then reconnect. Each platform's tour in these docs has a full troubleshooting section. ### Where do I get help? Use the Support tab in any app, which files a report and can attach client logs, or [feedback.ur.io](https://feedback.ur.io). One quick triage: if you can sign in at ur.io, your account is fine and the problem is client-side. Security reports go to [security@ur.io](mailto:security@ur.io) under the [vulnerability disclosure policy](https://ur.io/vdp). --- # Getting started on Android This guide takes you from nothing installed to connected, in about five minutes. It covers install, sign-in, permissions, connecting, and where to get help. For every screen and setting, read the [Android tour](/docs/tour-android). URnetwork uses member-run exit devices. Providers do not receive your source IP on relayed paths. Native apps can also encrypt traffic to the provider, once you switch on Post Quantum Encryption; it ships off. Read [How URnetwork works](/docs/overview) for the full model. ## What you need URnetwork for Android runs on Android 8.0 (API 26) or newer. The package is `com.bringyour.network` in every channel below. ## Install Pick the channel you trust most: - **Google Play** — [play.google.com/store/apps/details?id=com.bringyour.network](https://play.google.com/store/apps/details?id=com.bringyour.network) - **F-Droid** — [f-droid.org/packages/com.bringyour.network](https://f-droid.org/packages/com.bringyour.network/) - **Direct APK** — download from [github.com/urnetwork/build/releases](https://github.com/urnetwork/build/releases) and sideload. Fine from this official releases page. You handle updates yourself. - **Solana dApp Store** — on Solana Seeker devices. F-Droid and GitHub builds do not include Google sign-in. Use Google Play if you need it. F-Droid rebuilds the app from public source. Third-party security assessments, and their limits, are covered in the [threat model](/docs/threat-model). ## Sign in The app opens on the sign-in options. Pick the identity model you are comfortable with: - **Email or phone.** You get a one-time code each time. There is no password. The account is as secure as that inbox or number. - **Google.** Play builds only. The F-Droid and GitHub builds leave it out. - **Solana wallet.** Sign a message with your wallet. That signature is your sign-in. - **Bittensor wallet.** The same idea on the TAO side. - **Seedphrase.** Sign back in with the phrase an Instant Account gave you. It is URnetwork's own recovery phrase. URnetwork never asks for a crypto wallet's seed phrase. - **Auth code.** Already signed in on another device? Generate a one-time auth code there and enter it here. Codes expire after five minutes. - **Create Instant Account.** No email, no phone, no password. Tap it, tick the terms box, and tap **Create Account**. You now have a real, permanent network. Instead of a login it hands you a **seedphrase**: a numbered list of words, shown once, that is the credential. Save it on that screen. There is a copy button, and the app makes you confirm before it moves on. Nobody can recover the account without it. It brings the account back on any device, even after a reinstall. The Instant Account is the fastest path if you are just evaluating. Whichever you pick, you can attach a second sign-in method later in Settings, so losing one does not lock you out. Every network starts on the free tier, a daily data allowance that refreshes each day. Pro ($5/month or $40/year) replaces it with a large monthly allowance. Current numbers: [ur.io/products](https://ur.io/products). ## The VPN permission The first time you connect, Android asks for consent: - On Android 13 and up, a notification prompt comes first. It is for the ongoing tunnel notification. Declining it still connects. - Android then shows its system **Connection request** dialog, asking whether URnetwork may set up a VPN connection. Tap **OK**. This is Android's consent gate for any VPN app, with the same wording for every one. You see it exactly once. For what URnetwork records about your connections, read the [threat model](/docs/threat-model). ## Connect 1. Open the app and tap the big connect button on the Connect tab. 2. On your first connect, answer the permission prompts above. 3. The tunnel comes up. A key icon appears in your status bar. ![The connect screen](/docs-assets/connect-android.png) The quick-settings tile cannot show the consent dialog; only an app screen can. Tap the URnetwork tile before your first consent and it opens the app to finish the job. After that one consent, the tile connects and disconnects on its own. If your first tap of connect seems to do nothing, the dialog was dismissed. Tap connect again. ### Choose a location By default you connect to the **Best available provider**. The network keeps picking fast, reliable providers for you. That is the right choice for most sessions. To choose where your traffic exits: 1. On the Connect tab, tap the current location to open the provider picker. 2. Scroll for countries, or type to search. Cities and regions appear only in search results, so type a city's name to find it. 3. Tap a location, then connect. Each place shows a live provider count. Providers are member devices, not datacenters, so counts rise and fall with the time of day. The [overview](/docs/overview) explains the path your traffic takes. The [tour](/docs/tour-android) explains the connection settings and their trade-offs. ## Confirm it works Look for the key icon in your status bar. It is Android's own VPN indicator. While it shows, the tunnel is up. If the key ever disappears, the tunnel is down. ## If something fails The **Support** tab in the app reaches the team at [feedback.ur.io](https://feedback.ur.io). It can attach app logs when something misbehaves. The [FAQ](/docs/faq) answers common questions. ## What next - **Take the [tour](/docs/tour-android).** Every screen and setting: per-app split tunneling, domain and IP rules, custom DNS, the kill switch (off by default), and Android's always-on/lockdown mode. - **Share your connection.** Provide mode is off by default, and Wi-Fi-only once on. Sharing over mobile data takes a second, separate toggle. Providers participate in the UR protocol; [ur.xyz](https://ur.xyz) documents how rewards work. - **Try another platform:** [iOS](/docs/getting-started-ios), [macOS](/docs/getting-started-macos), [Windows](/docs/getting-started-windows), [Linux](/docs/getting-started-linux), and the [browser](/docs/getting-started-browser). --- # Getting started on iPhone and iPad This guide takes you from the App Store to connected, in about five minutes. It covers install, sign-in, permissions, connecting, and where to get help. For every screen and setting, read the [iOS tour](/docs/tour-ios). URnetwork uses member-run exit devices. Providers do not receive your source IP on relayed paths. Native apps can also encrypt traffic to the provider, once you switch on Post Quantum Encryption; it ships off. Read [How URnetwork works](/docs/overview) for the full model. ## What you need URnetwork runs on any iPhone or iPad with iOS 16.6 or later. Signing up needs no email, and the free tier needs no card. ## Install 1. Open the App Store and search for **URnetwork**, or go directly to [apps.apple.com/us/app/urnetwork/id6741000606](https://apps.apple.com/us/app/urnetwork/id6741000606). 2. Tap **Get**. The same listing covers iPhone, iPad, and Mac. Install once and use it on all three. 3. Open the app. Third-party security assessments, and their limits, are covered in the [threat model](/docs/threat-model). ## Sign in The app opens on the sign-in options. Pick the identity model you are comfortable with: - **Apple or Google.** The familiar one-tap paths. - **Solana wallet.** Approve a message signature with your wallet. No email involved. - **Bittensor wallet.** The same idea, through the ur.io/wallet-connect bridge. - **Seedphrase.** Sign back in with the recovery phrase an Instant Account gave you. It is URnetwork's own phrase. The wallet options above sign a challenge message, so URnetwork never sees a wallet's key or recovery words, and no URnetwork screen will ever ask for them. - **Auth code.** Already signed in on another device? Generate a one-time auth code there and enter it here. - **Create Account.** The classic email or phone path. - **Create Instant Account.** No email, no phone, no password. One tap makes a real, permanent network. Instead of a login it hands you a **seedphrase**: a list of words, shown once, that is the credential. Save it before you tap **I've Saved My Seedphrase**. Only a hash of it is stored, so nobody can show you those words again. Still signed in but lost the paper? Account → Settings → Seedphrase issues a new one and retires the old. The Instant Account is the fastest path if you are just evaluating. Whichever you pick, you can attach a familiar sign-in later without losing anything. Every network starts on the free tier, a daily data allowance that refreshes each day. Spend it and the app says *Insufficient balance* until the next refresh. Nothing is charged, because there is no card on file. Pro replaces the free tier with a large monthly allowance. Current plans: [ur.io/products](https://ur.io/products). ## The VPN permission The first time you connect, iOS asks for permission to add a **VPN configuration**. This is the operating system speaking, not the app. The tunnel runs as a system network extension, and iOS requires your approval before any app can route your traffic. Tap **Allow** and confirm with Face ID, Touch ID, or your passcode. You approve the configuration once. Afterwards it lives in Settings → General → VPN & Device Management like any other VPN profile. Tapped **Don't Allow**? Nothing was installed. Tap the connect button again and iOS asks again. For what URnetwork records about your connections, read the [threat model](/docs/threat-model). ## Connect 1. On the Connect tab, tap the big connect button under the globe. 2. On your first connect, approve the VPN configuration above. 3. The app finds providers and connects. The globe lights up with the locations your traffic is exiting from. ### Choose a location By default the app chooses **best available**: the highest-scored providers near you. That is the right choice for most sessions. To choose where your traffic exits: 1. Tap the location card on the Connect tab to open the **Available providers** sheet. 2. Scroll for countries, or type to search. Cities appear only in search results, so type a city's name to find it. 3. Tap a location. The app reconnects through providers there. Each place shows a live count of providers online. Providers are member devices, not datacenters, so counts rise and fall with the time of day. The [overview](/docs/overview) explains the path your traffic takes. The [tour](/docs/tour-ios) explains the connection settings and their trade-offs. ## Confirm it works The globe on the Connect tab lights up with the locations your traffic exits from. To check from outside the app, open [ur.io/ip](https://ur.io/ip). It reports the address the internet now sees, which should be a provider's rather than yours. ## If something fails The **Support** tab in the app reaches the team at [feedback.ur.io](https://feedback.ur.io). The [tour](/docs/tour-ios) ends with a troubleshooting section for common iOS issues. The [FAQ](/docs/faq) answers common questions. ## What next - **Take the [tour](/docs/tour-ios).** Every screen and setting: custom DNS, split rules, Siri shortcuts, the kill switch (off by default), and troubleshooting. - **Share your connection.** Provide mode starts at *Never*, in Account → Settings → Connections. *Network* keeps sharing to your own devices. It shares on Wi-Fi unless you also allow cellular. Providers participate in the UR protocol; [ur.xyz](https://ur.xyz) documents how rewards work. - **Same app, bigger screen:** [macOS](/docs/getting-started-macos). - **Try another platform:** [Android](/docs/getting-started-android), [Windows](/docs/getting-started-windows), [Linux](/docs/getting-started-linux), and the [browser](/docs/getting-started-browser). --- # Getting started on macOS URnetwork on the Mac is the same app as on iPhone and iPad, built native for macOS. This guide takes you from the Mac App Store to connected, in about five minutes. It covers install, sign-in, permissions, connecting, and where to get help. For every screen and setting, read the [macOS tour](/docs/tour-macos). URnetwork uses member-run exit devices. Providers do not receive your source IP on relayed paths. Native apps can also encrypt traffic to the provider, once you switch on Post Quantum Encryption; it ships off. Read [How URnetwork works](/docs/overview) for the full model. ## What you need URnetwork runs on any Mac with macOS 13.5 or later. Signing up needs no email, and the free tier needs no card. ## Install 1. Open the App Store on your Mac and search for **URnetwork**, or go to [apps.apple.com/us/app/urnetwork/id6741000606](https://apps.apple.com/us/app/urnetwork/id6741000606). 2. Click **Get** and open the app. It is the same listing as iPhone and iPad, so if you already have the app on your phone it shows as available on your Mac too. Third-party security assessments, and their limits, are covered in the [threat model](/docs/threat-model). ## Sign in The app opens on the sign-in options. Pick the identity model you are comfortable with: - **Apple or Google.** The familiar one-tap paths. - **Solana wallet.** Approve a message signature with your wallet. - **Bittensor wallet.** The same idea, signed through WalletConnect. - **Seedphrase.** Sign back in with the recovery phrase an Instant Account gave you. It is URnetwork's own phrase. URnetwork never asks for a crypto wallet's seed phrase. - **Auth code.** Sign in with a code from a device that is already logged in. Handy for moving from your phone to your Mac. - **Create Account.** The classic email or phone path. - **Create Instant Account.** No email, no phone, no password. One click makes a real, permanent network. Instead of a login it hands you a **seedphrase**: a list of words, shown once, that is the credential. Save it on that screen. While the Mac stays signed in you can mint a replacement under Account → Settings → Seedphrase, which retires the old one. Once you are signed out with nothing saved, no one can recover the account for you. Not sure which? Create Account with an email is the simplest and most portable. The Instant Account is the fastest and the most private. The wallet options matter if you would rather anchor your identity to a wallet you already use. Every network starts on the free tier, a daily data allowance that refreshes each day. Pro replaces it with a large monthly allowance. Current plans: [ur.io/products](https://ur.io/products). ## The VPN permission The first time you connect, macOS asks for permission to add a **VPN configuration**. This is the operating system speaking, not the app. The tunnel runs as a system network extension, and macOS requires your approval before any app can carry your traffic. Approve it once and you are done. The result lives in **System Settings → VPN**. If you ever change your mind, deleting that VPN entry in System Settings is how you undo it. For what URnetwork records about your connections, read the [threat model](/docs/threat-model). ## Connect 1. Click the connect button on the Connect screen. 2. On your first connect, approve the VPN configuration above. 3. The globe lights up with the locations your traffic exits from. URnetwork also lives in your menu bar, with Connect and Disconnect, a Show button for the window, and Quit. Closing the window leaves the tunnel running; the menu bar keeps the controls one click away. **Quit** disconnects first and then exits. The app hands macOS no auto-connect rule, so after a restart you reconnect yourself. ### Choose a location By default the app chooses **best available**: the highest-scored providers near you. That is the right choice for most sessions. To choose where your traffic exits: 1. Click the location card on the Connect screen, or the toolbar button marked **Show Provider List**. The list slides out beside the globe. 2. Scroll for countries, or type in the search field. Regions and cities appear only in search results, so type a city's name to find it. 3. Pick a location. The app reconnects through providers there. Each place shows a live count of providers online. Providers are member devices, not datacenters, so counts rise and fall with the time of day. The [overview](/docs/overview) explains the path your traffic takes. The [tour](/docs/tour-macos) explains the connection settings and their trade-offs. ## Confirm it works Visit any "what is my IP" site. It should show a provider's address and city rather than yours. After that, the menu-bar icon is your at-a-glance status for whether the tunnel is up. ## If something fails The **Support** section in the sidebar reaches the team at [feedback.ur.io](https://feedback.ur.io). The [tour](/docs/tour-macos) covers macOS-specific troubleshooting. The [FAQ](/docs/faq) answers common questions. ## What next - **Take the [tour](/docs/tour-macos).** Every screen and setting: the sidebar, the menu-bar extra, custom DNS, split rules, the kill switch (off by default), and macOS-specific troubleshooting. - **Share your Mac's spare bandwidth.** Provide mode ships on *Never*, in Account → Settings → Connections, and can be limited to your own devices. Providers participate in the UR protocol; [ur.xyz](https://ur.xyz) documents how rewards work. - **Same account, other devices:** [iPhone and iPad](/docs/getting-started-ios) and [Android](/docs/getting-started-android). - **Try another platform:** [Windows](/docs/getting-started-windows), [Linux](/docs/getting-started-linux), and the [browser](/docs/getting-started-browser). --- # Getting started on Windows This guide takes you from nothing installed to connected, in about five minutes. It covers install, sign-in, permissions, connecting, and where to get help. For every screen and setting, read the [Windows tour](/docs/tour-windows). URnetwork uses member-run exit devices. Providers do not receive your source IP on relayed paths. Native apps can also encrypt traffic to the provider, once you switch on Post Quantum Encryption; it ships off. Read [How URnetwork works](/docs/overview) for the full model. ## What you need URnetwork for Windows runs on Windows 10 version 21H2 or later and Windows 11, on both x64 and ARM64. ## Install Download the signed **MSI installer** from [github.com/urnetwork/build/releases](https://github.com/urnetwork/build/releases). Pick the build matching your processor: x64 for most PCs, ARM64 for Snapdragon-based machines. Run it. The installer puts four pieces on your machine: - **URnetwork.exe.** The tray app, running as you, unprivileged. - **urnetworkd.** A Windows service that starts with the machine and owns the tunnel. It restarts itself if it crashes. - **wintun.** A virtual network adapter, built by the WireGuard project, that the service uses to carry traffic. - **The split-tunnel driver.** An optional installer feature, included by default, that lets you exempt specific apps from the tunnel later. Third-party security assessments, and their limits, are covered in the [threat model](/docs/threat-model). ## Sign in The app opens on the sign-in options. Pick the identity model you are comfortable with: - **Email or phone.** Enter it and continue. A new account asks for a network name and a password of at least 12 characters, then a one-time code sent to that address. A returning one asks for the password. Password reset runs through that inbox, so the account is as secure as the inbox or number behind it. - **Auth code.** Already signed in on another device? Generate a one-time auth code there, in any URnetwork app or at [ur.io](https://ur.io), and paste it here. - **Try Guest Mode.** One click, plus the terms box, creates a real, permanent network with nothing handed over. The button predates the current sign-up flow: the recovery phrase for that account is discarded rather than shown to you, so there is no way back into it from another machine. Treat it as a throwaway for evaluating. Before you keep anything in it, create an account from the Account tab's plan card. - **Bittensor wallet.** Approve a signature in your wallet. That signature is your sign-in. - **Solana wallet.** The same idea, via Phantom or Solflare. There is no Google or Apple sign-in on Windows. If you want an email-free account you can keep, the phone and Mac apps offer a one-tap **Create Instant Account** that does show you its recovery phrase. Create it there and bring it to this PC with an auth code. Every network starts on the free tier, a daily data allowance that refreshes each day. Pro ($5/month or $40/year) replaces it with a large monthly allowance. Current numbers: [ur.io/products](https://ur.io/products). ## The administrator permission The installer asks for administrator approval once, because it registers the `urnetworkd` service. That service, not the app, holds the privilege to create a tunnel. So connecting, disconnecting, and changing settings never ask for admin again, and Windows shows no consent dialog when you connect the way phones do. For what URnetwork records about your connections, read the [threat model](/docs/threat-model). ## Connect 1. Click **Connect** in the app, or left-click the tray icon and use the flyout. 2. The tunnel comes up. There is no permission prompt, because you approved the service at install time. 3. The tray icon changes state. It has four looks, connected or not and providing or not, and matches your taskbar with light or dark artwork. Closing the window does not disconnect you. The window hides to the tray and the tunnel keeps running, because it lives in the service, not the window. Even quitting the tray app leaves the tunnel up. **Disconnect** is what turns it off. ### Choose a location By default you connect to the **best available provider**. The network keeps picking fast, reliable providers for you. That is the right choice for most sessions. To choose where your traffic exits: 1. Click the location row on the Connect screen to open the picker. 2. Scroll the list for countries, plus your own devices. Regions and cities appear only in search results, so type a city's name to find it. 3. Pick a location. The app reconnects through providers there. Each row shows a live count of providers online. Providers are member devices, not datacenters, so counts rise and fall with the time of day. The [overview](/docs/overview) explains the path your traffic takes. The [tour](/docs/tour-windows) explains the connect drawer's settings and their trade-offs. ## Confirm it works Visit any "what is my IP" site. You should see a provider's address and city instead of yours. After that, the tray icon is your at-a-glance status for whether the tunnel is up. ## If something fails The **Support** section in the app sends feedback to the team. [feedback.ur.io](https://feedback.ur.io) is the same channel from a browser. The [FAQ](/docs/faq) answers common questions. ## What next - **Take the [tour](/docs/tour-windows).** Every screen and setting: the two-process design, per-app split tunneling through the driver, the connect drawer's options, custom DNS, and the kill switch (off by default). - **Set provide mode.** The connect drawer has a four-way selector: Auto, Always, Network (your own devices only), or Never. Providers participate in the UR protocol; [ur.xyz](https://ur.xyz) documents how rewards work. - **Try another platform:** [Android](/docs/getting-started-android), [iOS](/docs/getting-started-ios), [macOS](/docs/getting-started-macos), [Linux](/docs/getting-started-linux), and the [browser](/docs/getting-started-browser). --- # Getting started on Linux This guide takes you from nothing installed to connected. It covers the two-part install, sign-in, connecting, and where to get help. For every screen and setting, read the [Linux tour](/docs/tour-linux). URnetwork uses member-run exit devices. Providers do not receive your source IP on relayed paths. Native apps can also encrypt traffic to the provider, once you switch on Post Quantum Encryption; it ships off. Read [How URnetwork works](/docs/overview) for the full model. ## What you need URnetwork for Linux is a native GTK4 desktop app paired with a system daemon that owns the tunnel. It targets **Ubuntu 22.04 or newer** and equivalent Debian-family releases, on **amd64 and arm64**, and needs systemd and `/dev/net/tun`. That is a normal desktop or server install. ## Install The app installs as two pieces, because a tunnel needs privilege and a GUI must never have it: - **`urnetworkd`** — a small root daemon under systemd. It owns `/dev/net/tun`, routes, and DNS. It has no GUI dependencies at all, so it installs fine on a headless box. - **The URnetwork app** — a GTK4/libadwaita desktop app shipped as an AppImage, running as your normal user. It never needs root. Both come from [github.com/urnetwork/build/releases](https://github.com/urnetwork/build/releases). ### 1. Install the daemon Use the **`.deb`** on Debian, Ubuntu, and derivatives: ``` sudo apt install ./urnetwork-daemon__.deb ``` or the **install tarball** on distributions without dpkg: ``` tar xf urnetwork-daemon--.install.tar.gz sudo urnetwork-daemon/install.sh ``` The installer runs preflight checks (systemd, glibc, `/dev/net/tun`) and prints what it will do; `install.sh --dry-run` shows the plan without touching anything. It creates a system group called `urnetwork`, installs the daemon, its systemd unit, the desktop entry, icons, and a `/usr/bin/urnetwork` launcher, then enables and starts the service. Starting it on install is safe: the daemon starts idle. It never brings up a tunnel until an authenticated desktop client asks it to. ### 2. Put the app where it can update itself The GUI AppImage is deliberately not installed by the package. It lives in your home directory so it can replace itself without root: ``` mkdir -p ~/.local/lib/urnetwork cp URnetwork--.AppImage ~/.local/lib/urnetwork/URnetwork.AppImage chmod +x ~/.local/lib/urnetwork/URnetwork.AppImage ``` `/usr/bin/urnetwork` finds it there and runs it, so the desktop entry, the app menu, and `urnetwork://` links keep working across app updates. AppImages need `libfuse2`; the `.deb` declares that dependency for you. ### 3. Add yourself to the `urnetwork` group Only root and members of the `urnetwork` group can command the daemon, so your own user has to join: ``` sudo usermod -aG urnetwork "$USER" ``` Log out and back in; group membership is picked up at login. Skip this and the app will tell you it cannot reach the service. Third-party security assessments, and their limits, are covered in the [threat model](/docs/threat-model). ## Sign in Launch URnetwork from your app menu, or run `urnetwork`. The app opens on the sign-in options. Pick the identity model you are comfortable with: - **Email or phone.** Enter it and continue. The app finds your account or offers to create one, verifying with a one-time code. - **Create account.** Network name, email or phone, password, and an optional referral code. - **Sign in with code.** Already signed in on another device? Generate a one-time auth code there, in any URnetwork app or at [ur.io](https://ur.io), and paste it in. - **Try Guest Mode.** One click creates a real, permanent network with nothing handed over. The button predates the current sign-up flow: the recovery phrase for that account is discarded rather than shown to you, so there is no way back into it from another machine. Treat it as a throwaway for evaluating. Add an email, phone, or wallet before you rely on it. - **Sign in with Bittensor.** Your browser opens a wallet bridge, your wallet signs a message, and the app takes it from there. - **Sign in with Solana.** The same flow, via Phantom or Solflare. There is no Google or Apple sign-in on Linux. If you want an email-free account you can keep, the phone and Mac apps offer a one-tap **Create Instant Account** that shows you its recovery phrase. Create it there and bring it to this machine with an auth code. Every network starts on the free tier, a daily data allowance that refreshes each day. Pro ($5/month or $40/year) replaces it with a large monthly allowance, bought in the app from **Get UR Pro**. Current numbers: [ur.io/products](https://ur.io/products). ## The tunnel permission No consent dialog appears when you connect, because you granted the privilege at install time. The daemon runs as root and owns the tunnel device; the app runs as you and asks the daemon over its control socket. That socket is gated by kernel-verified peer credentials: root, or a member of the `urnetwork` group. Nothing else on the system can start a tunnel. For what URnetwork records about your connections, read the [threat model](/docs/threat-model). ## Connect 1. Click **Connect** in the app. 2. The tunnel comes up. There is no permission prompt, because the daemon, not the app, is what opens the tunnel device. 3. The globe and the status line come alive, and a tray icon appears if your desktop supports one. ### Choose a location The default is **best available**. The network continuously picks fast, reliable providers for you. That is the right choice for most sessions. To choose where your traffic exits: 1. Click the location row to open the picker. 2. Scroll for countries, or type to search. Regions, cities, and devices appear in search results, so type a city's name to find it. 3. Pick a location. The app reconnects through providers there. Each entry carries a live count of providers online there right now. Providers are member devices, not datacenters, so counts rise and fall with the time of day. The [overview](/docs/overview) explains the path your traffic takes. The [tour](/docs/tour-linux) explains the connection settings and their trade-offs. ## Confirm it works Visit any "what is my IP" site. You should see a provider's address and city rather than yours. After that, the app's globe and status line, and the tray icon where your desktop shows one, tell you the tunnel is up. ## If something fails If the app reports the service unreachable, out of date, or a different build from the app, that is a real state with a real fix: see [Troubleshooting](/docs/tour-linux#troubleshooting) in the tour. The two halves are version-matched deliberately, so a half-upgraded install tells you instead of failing strangely. For tunnel problems, `journalctl -u urnetworkd -f` is the first thing to check. [feedback.ur.io](https://feedback.ur.io) reaches the team, and the [FAQ](/docs/faq) answers common questions. ## What next - **Take the [tour](/docs/tour-linux).** Every screen and setting: the daemon split, routing and DNS behavior and its limits, the sheets (custom DNS, split rules, live contracts), the device-location override, the kill switch (off by default), and troubleshooting. - **Share your connection.** Provide mode is in the app's home controls: **Auto**, **Always**, **Network** (your own account's devices only, never the public), or **Never**, and it starts on **Never**. A Linux desktop or server on a good uplink is exactly the kind of node the network wants; the [overview](/docs/overview) covers the abuse filtering that runs on your machine before traffic leaves it. For a headless box, the standalone provider CLI at [github.com/urnetwork/build/releases](https://github.com/urnetwork/build/releases) does the same job: `urnetwork auth` with a code from any app, then `urnetwork provide`. Providers participate in the UR protocol; [ur.xyz](https://ur.xyz) documents how rewards work. - **Try another platform:** [Android](/docs/getting-started-android), [iOS](/docs/getting-started-ios), [macOS](/docs/getting-started-macos), [Windows](/docs/getting-started-windows), and the [browser](/docs/getting-started-browser). --- # Getting started in your browser This guide takes you from nothing installed to connected, in about two minutes, on any desktop OS. It covers install, sign-in, connecting, and where to get help. For every control and setting, read the [browser tour](/docs/tour-browser). URnetwork uses member-run exit devices. Providers do not receive your source IP on relayed paths. One scope note: the extension has no sealed session — your client device runs inside the operator, which translates the browser's protocol into the network's — so what stands between the operator and your content is the storage design described in the [threat model](/docs/threat-model), not a seal. Read [How URnetwork works](/docs/overview) for the full model. ## What you need A desktop browser: Chrome and most Chromium browsers, Edge, or Firefox. The extension proxies this browser's traffic and nothing else. It works by configuring the browser's proxy settings, so everything the browser does exits through URnetwork providers, and nothing else on your computer is touched. It is not a device-wide VPN. For the whole machine, use the URnetwork app for [Windows](/docs/getting-started-windows), [macOS](/docs/getting-started-macos), or [Linux](/docs/getting-started-linux). The extension is also one half of one product. Sign in once at [ur.io](https://ur.io) and the web app installs, sets up, connects, and re-locates the extension for you; the extension is what enforces it inside the browser. The popup drives all of it too, if you would rather not keep a tab open. ## Install Install from your browser's store: - **Chrome** (and most Chromium browsers): [chromewebstore.google.com/detail/urnetwork/kpnklgbgjkihebbieiggfeokkddjbkfb](https://chromewebstore.google.com/detail/urnetwork/kpnklgbgjkihebbieiggfeokkddjbkfb) - **Edge**: [microsoftedge.microsoft.com/addons/detail/urnetwork/jegjndonglfogpmldpmokincfecdombi](https://microsoftedge.microsoft.com/addons/detail/urnetwork/jegjndonglfogpmldpmokincfecdombi) - **Firefox**: [addons.mozilla.org/en-US/firefox/addon/urnetwork/](https://addons.mozilla.org/en-US/firefox/addon/urnetwork/) Pin the icon to your toolbar; you will be opening the popup a lot. Or skip the list: signed in at ur.io, the app offers the right store link for your browser. A note for Firefox tinkerers: a ZIP you load yourself via `about:debugging` is temporary and disappears when Firefox restarts. Use the listing above. Third-party security assessments, and their limits, are covered in the [threat model](/docs/threat-model). ## Sign in Easiest: sign in at [ur.io](https://ur.io) and press **Set up extension to use your network**. The web app hands this browser your session directly, with no code to copy, and then reads "Extension connected and ready to use". From the popup instead, pick either path: 1. **Login with SSO.** Single sign-on: the same account you would use in the apps. It opens a web sign-in flow in a new tab; sign in or create your network there, and the extension picks up the session when the tab returns you. An email or phone one-time code is enough. To sign up with no email at all, sign the login message with a Solana or Bittensor wallet. 2. **Paste an auth code.** A short code that signs this browser into an account you already have; it cannot create one. Generate it in any URnetwork app or from your ur.io account panel, and paste it promptly. A ur.io code is single-use and expires about a minute after you make it. New here? Take the SSO path. Every network starts on the free tier, a daily data allowance that refreshes each day. Pro ($5/month or $40/year) replaces it with a large monthly allowance. Current numbers: [ur.io/products](https://ur.io/products). ## The proxy permission There is no operating-system dialog. Adding the extension from the store is the consent step: that is what lets it manage this browser's proxy settings, and connecting later asks for nothing more. One browser-level consent remains on Firefox. Firefox keeps extensions out of Private Windows unless you allow "Run in Private Windows" in the add-on's settings; until you do, private-window traffic bypasses the proxy. Chromium browsers apply the proxy profile-wide, incognito included. For what URnetwork records about your connections, read the [threat model](/docs/threat-model). ## Connect 1. Open the popup from the toolbar icon and hit connect. **Best available** is the default: the network keeps picking fast, reliable providers for you. 2. The popup names your public address and says whether you are on URnetwork. ![The extension popup](/docs-assets/connect-extension.png) ### Choose a location To choose where your traffic exits: 1. Open the location picker and type into **Search providers**. Left empty it lists countries; a search returns **Best matches** plus cities filed under their region. That is how you pick a city, not just a country. 2. Pick one, then connect. Every entry carries a live provider count: how many member devices, real people's phones, computers, and routers sharing spare bandwidth, can be your exit right now. Counts rise and fall with the time of day. The [overview](/docs/overview) explains the path your traffic takes and what each party can see. The [tour](/docs/tour-browser) explains the popup's settings and their trade-offs. ## Confirm it works The popup names your public address and says whether you are actually on URnetwork; [ur.io/ip](https://ur.io/ip) is the same check on the web. You should see a residential address, an IP belonging to a real home connection rather than a data center, in your chosen location. Different sites may see different addresses: traffic spreads across a few providers at once, though any given site consistently sees one. ## If something fails Pages refusing to load usually means the kill switch is doing its job. It ships on, subtitled *Blocks traffic on failure*: if the proxy connection drops, the extension blocks the browser's traffic rather than silently letting it fall back to your real connection. It health-checks every minute and retries on its own; pages load again when it reconnects or you disconnect. Turn the toggle off and a dropped connection fails open instead. It guards this browser only. [feedback.ur.io](https://feedback.ur.io) reaches the team. The [tour](/docs/tour-browser) has the per-browser troubleshooting, and the [FAQ](/docs/faq) answers common questions. ## What next - **Take the [tour](/docs/tour-browser).** The proxy machinery per browser, kill-switch semantics (on by default), the geolocation override, health checks, what it collects (nothing), and troubleshooting. - **Cover the whole machine.** The extension guards this browser only: [Windows](/docs/getting-started-windows), [macOS](/docs/getting-started-macos), [Linux](/docs/getting-started-linux), [Android](/docs/getting-started-android), and [iOS](/docs/getting-started-ios). - **Read [How URnetwork works](/docs/overview).** Who the providers are, what they can see, and how the economics keep the network supplied. --- # Getting started with the URnetwork SDK [Install the SDK](/docs/install-sdk) with your language's package manager, then explore the [language examples](/docs/examples) and [socket guide](/docs/socket). This guide takes a developer from an empty project to a first connection: get an account JWT, install the binding for your platform, bring up a device, and confirm traffic flows. The SDK is one Go module, `github.com/urnetwork/sdk`, exposed through four bindings: - **Android** — the core compiled to native code and bound for Kotlin/Java, shipped as an AAR. - **iOS / macOS** — the same gomobile path, bound for Swift, shipped as an xcframework. - **cgo (Windows, Linux)** — the core as a c-shared library behind a C ABI, with a C++17 header over it. Any language with an FFI reaches it here. - **JavaScript (wasm/web)** — the core compiled to WebAssembly and run in the page, driven by your browser framework. They front one core, so behavior matches across platforms — but they are not interchangeable, and the differences decide your architecture rather than just your syntax. Read [Which binding](#which-binding) before you pick one, and the [SDK tour](/docs/tour-sdk) for how each is built. ![Your app's first connection — network space, account JWT and Device inside your app, traffic out through URnetwork to the internet, and which bindings run the packet path](/docs-assets/diagram-dev-getting-started-sdk.svg) URnetwork uses member-run exit devices. Providers do not receive your users' source IPs on relayed paths. Devices built on the SDK can also encrypt traffic to the provider, but only once you turn on `PostQuantumEncryption`; a new device starts with it off. Read [How URnetwork works](/docs/overview) for the full model. ## What you need All four bindings front the same core the official URnetwork apps are built on: the device (the connection engine), the API client, the network-space configuration model (which platform deployment you talk to, with what endpoints and flags), and the view controllers, headless state-plus-events objects for the common screens that you can bind your UI to or ignore. The operator API behind it is documented at [/docs/api](/docs/api). You are building your own app on URnetwork's hosted platform: the API, relays, and providers are the live service, and your users bring or create accounts. Platform floors, per binding: - **Android** — API level 24 or newer. The Java package is `com.bringyour.sdk`. - **iOS / macOS** — iOS 16.0 and macOS 13.5. - **cgo** — Ubuntu 22.04+ (glibc 2.35+) or Windows 10+, amd64 and arm64. - **JavaScript** — browser-only. - **Building from source** — Go 1.27.3. The SDK is MPL-2.0 (Mozilla Public License): link it freely into closed-source apps. The file-level copyleft only obliges sharing changes to the SDK's own files. ## Which binding {#which-binding} The native bindings can own the device packet path. A browser page cannot own an operating-system TUN interface; its JavaScript Device controls a remote device. The updated JS SDK also exposes application [sockets](/docs/socket) through a socket-capable remote Device, including TCP, UDP, TLS/DTLS, and the JavaScript Direct Sockets interface. This routes those application connections without making the browser page an operating-system VPN. | | Android | iOS / macOS | cgo | JavaScript | | --- | --- | --- | --- | --- | | You write | Kotlin / Java | Swift | C++ (or any FFI) | JS / TypeScript | | The core arrives as | native code, gomobile-bound | native code, gomobile-bound | c-shared library, C ABI | wasm in the page | | Runs the packet path | yes, in your app process | yes, in the NetworkExtension | yes, in a daemon you write | **no** | | Process model | single process | app + extension, loopback mTLS | UI + privileged service, loopback mTLS | page only | | Artifact | ~37 MB AAR | ~116 MB xcframework | ~21–25 MB library | ~43.5 MB wasm | What that costs you, in the order it will bite: - **Android** is the simplest: one process holds the UI and the `VpnService`, so your app owns the `DeviceLocal` directly and `IoLoop` pumps the tun fd inside Go with no per-packet JNI crossing. - **iOS / macOS** is the same binding with a harder shape. Every Apple VPN runs packet handling in a separate sandboxed process, so the device lives in the extension and your app drives it remotely. Budget for the re-attach lifecycle and the extension memory limit from day one — it is not an edge case, the OS restarts that process routinely. - **cgo** is the most portable and the least ergonomic. The ABI is handles and JSON rather than typed objects, which is what lets Rust, Python and C# reach it; the C++17 header is the one place that ergonomics were spent. You also write the privileged daemon yourself. - **JavaScript** trades the packet path for reach. You get the API surface, the view controllers, and `DeviceRemote` against a device hosted elsewhere — and a 43 MB payload to lazy-load. Threading is where all four converge on one rule: non-view objects are concurrent-safe, view controllers are not. Browser JS gets that for free; the other three do not. See the [tour](/docs/tour-sdk) for the details. ## Sign in Every snippet below takes a `byJwt`: the account JWT, a signed login token the URnetwork API issues when an account authenticates. There is no separate API-key system. Your app runs a login flow once through the SDK's API client. `authLogin` reports an identifier's auth methods; `authLoginWithPassword` completes it (`authVerify` finishes an emailed or SMS'd code), and wallet auth and `networkCreate` are parallel entry points. Wallet auth is signature-only: you send `wallet_address`, `wallet_message`, and `wallet_signature`, never a key, and no URnetwork surface asks for a wallet's private key or mnemonic. `networkCreate` with no auth method at all is the instant-account path: it mints a permanent account and returns a `seedphrase`, URnetwork's own recovery phrase for that account, generated server-side and handed back exactly once. Surface it to the user then, or the account has no recovery path. Every path returns `by_jwt`. Persist it, call `setByJwt`, and pass it to the device constructor. You write no refresh code; the `Api`'s token manager rotates the JWT. Treat a hard auth failure as "run login again." The account is also the billing unit: the account whose JWT the device holds is the one whose plan is metered. Free is a daily data allowance, Pro a large monthly one; current numbers at [ur.io/products](https://ur.io/products). Intend one account per end user, which the instant-account path makes frictionless, rather than one embedded account pooling every user's usage and conduct into a single actor. When an account runs out of data, transfer stalls until the allowance refreshes, so say "out of data" in your UX, not a generic network error. The SDK also owns the paid-plan flow, because the client must never name its own price: register an intent with `createSolanaPaymentIntent` (`reference` from `createPaymentReference`, `plan` `"monthly"` or `"yearly"`), take `amountUsd` from the result, and pass it to `buildSolanaPaymentUrl`. The C ABI has the intent call, not yet the URL builder. ## Install Prebuilt artifacts are release assets on [github.com/urnetwork/build](https://github.com/urnetwork/build/releases). Versions are date-based, `vYYYY.M.D-` (e.g. `v2026.7.22-999364023`), not SemVer: pin a release and upgrade deliberately, since the version says when it was cut, not whether the API moved. **Android.** Download `URnetworkSdk-.aar` (plus `-sources.jar` for IDE navigation) and drop them into a directory your Gradle module already scans, e.g.: ```groovy dependencies { implementation fileTree(dir: 'libs', include: ['*.aar']) } ``` **iOS / macOS.** Download `URnetworkSdk.xcframework.zip`, unzip it, and reference it from a local Swift package as a `binaryTarget`: ```swift // Package.swift targets: [ .binaryTarget(name: "URnetworkSdk", path: "URnetworkSdk.xcframework") ] ``` All types are `Sdk`-prefixed (`SdkDeviceLocal`, `SdkNetworkSpace`, ...). The xcframework carries `ios/arm64`, `iossimulator/arm64`, `macos/arm64`, and `macos/amd64`; there is no Intel iOS-simulator slice. **cgo (Windows, Linux).** C-shared libraries, the same layer the shipping URnetwork Linux and Windows apps are built on, with two curated headers alongside them: - `libURnetworkSdk.so` — Linux. - `URnetworkSdk.dll` (+ `urnetwork_sdk.def`) — Windows. - `urnetwork_sdk.h` — the plain C ABI. - `urnetwork_sdk.hpp` — a header-only C++17 RAII wrapper over it, requiring [nlohmann/json](https://github.com/nlohmann/json) on your include path. Anything with a C foreign-function interface (Rust bindgen, Python ctypes, C# P/Invoke) maps onto this handles-and-JSON ABI; the C++ header is the one language convenience. With MSVC, generate the import library from the `.def` file first: ```bat lib /def:urnetwork_sdk.def /machine:x64 /out:URnetworkSdk.lib ``` **JavaScript (browser and Node).** The canonical package is `@urnetwork/sdk`, containing the loader, TypeScript declarations, Go's `wasm_exec.js` and the matching SDK WASM. Use a socket-capable release. ```sh npm install @urnetwork/sdk@nightly # then pin the version it resolved to ``` The WASM contains the Go networking core and is a large download. Serve it as a static asset (gzip or brotli, cached hard) and load it lazily, only when the user reaches a connect surface. Never let a bundler inline or transform it, and always ship `sdk.wasm` and `wasm_exec.js` from the same build; the glue is ABI-paired with the Go toolchain that compiled the wasm, and the SDK's build gates on the two matching byte for byte. **From source.** You need Go 1.27.3, and for mobile `make init` first: it pins the exact gomobile the bindings are cut with and installs the checksec the Android target runs. `build_android` also needs `ANDROID_NDK_HOME` set, since it strips `.comment` with the NDK's `llvm-objcopy`. `sdk/build-android.sh` and `sdk/build-ios.sh` wrap both. From `sdk/build`: ```sh make init # pinned gomobile + checksec; run before the mobile targets make build_android # AAR make build_apple # xcframework (build_ios is an alias) make build_js # wasm + loader make build_linux # c-shared .so, cross-compiled with zig make build_windows # c-shared .dll; not in `all` — the shipped one builds in a VM ``` `build_android` gates on gomobile's skip list, so a missing symbol is a version mismatch, not a silent binding drop; gomobile binds no slices of structs (lists cross as `SdkStringList`, `SdkIdList`, ...) and no `context.Context`. Third-party security assessments, and their limits, are covered in the [threat model](/docs/threat-model). ## The tunnel permission The operating-system consent, and the tunnel itself, belong to your app. The SDK begins at the packet layer: - On **Android**, the `VpnService` is yours: your app declares it, obtains VPN consent with `VpnService.prepare()`, and calls `establish()`. The SDK takes over at that file descriptor. - On **Apple platforms**, the split is Apple's requirement, not the SDK's: packet tunnels run in a separate NetworkExtension with tight memory limits, so the tunnel provider owns the device while your app process attaches to it remotely. - In a **browser**, a page cannot own a network interface, so there is no permission to ask, and nothing in the JavaScript layer tunnels the page's own traffic. Both JavaScript device models drive a device on the platform instead. The URnetwork extension covers browser tabs; a native app covers the whole machine. For what URnetwork records about connections, read the [threat model](/docs/threat-model). ## Connect A new device starts on the network defaults, and those leave the client-provider session unsealed. A device has no performance profile until you set one, so `PostQuantumEncryption`, the flag behind the apps' "Post Quantum Encryption" control, starts off, and the client opens no session to the provider: traffic takes the standard relayed path, where the operator can read the packets it relays. Set the flag with `setPerformanceProfile` to seal. Every current provider build enables the responder side, and with the flag on the client is fail-closed: it will not carry application data in the clear, and it skips a provider it cannot seal to rather than using it unsealed. `AllowDirect` is off by default; it is the opt-in speed setting that removes the anonymizing hop and hands that provider your user's real IP, the apps surface it inverted as "Strong Anonymization", and hosted device profiles force it off. Leak protection is yours to wire: the kill switch is the primitive `setRouteLocal`, a device starts with local routing allowed, and `setRouteLocal(false)` makes traffic stop rather than fall back when the tunnel is down. The SDK embeds no analytics or crash reporting; its only connections are the platform endpoints and the relays and providers the device uses. ### Android Bootstrap order: create a `NetworkSpaceManager` pointed at app-private storage (the directory holds local state, including credentials), create the network space, then set the account JWT on its API client. The key is a host name plus an environment name; production is `("ur.network", "main")`, and `updateNetworkSpace` is what creates one, while `getNetworkSpace` only reads back a space that exists, so it returns null on a fresh install. URLs derive from the key (`https://api.`, `wss://connect.`; a non-`main` env prefixes the service), but the derivation prefers `migrationHostName`, which production sets to `bringyour.com`: the shipping apps reach `api.bringyour.com`, and `api.ur.network` does not resolve. Then create the device and hand it the tunnel's file descriptor: ```kotlin import com.bringyour.sdk.Sdk val manager = Sdk.newNetworkSpaceManager(context.filesDir.absolutePath) val key = Sdk.newNetworkSpaceKey("ur.network", "main") val networkSpace = manager.updateNetworkSpace(key) { it.migrationHostName = "bringyour.com" } networkSpace.api.setByJwt(byJwt) val device = Sdk.newDeviceLocalWithMemoryTarget( networkSpace, byJwt, deviceDescription, // free-form, shown in the account's device list deviceSpec, // e.g. Build.MODEL appVersion, Sdk.newId(), // instanceId; persist and reuse per install /* enableRpc */ false, keyMaterial, // persisted DeviceLocalKeyMaterial, or null for ephemeral memoryTargetByteCount, ) // inside your VpnService, after establish(): val detachedFd = pfd.detachFd() // ParcelFileDescriptor -> raw fd val ioLoop = Sdk.newIoLoop(device, detachedFd) { /* done callback */ } ``` `newIoLoop` takes ownership of the detached fd and pumps packets in both directions until you close it. Do not touch the fd again from Java after detaching. Three constructor arguments deserve care. `instanceId`: generate one `Sdk.newId()` on first run, persist it, and reuse it for the life of the install (one live device per process); a fresh id every launch adds a phantom entry to the account's device list. `keyMaterial`: null is fine for a pure client, but if the device will ever provide capacity, persist `getKeyMaterial()` in platform secure storage. It is the device's provider identity, and losing it resets the provider's reliability history. `memoryTargetByteCount`: a byte budget the device sizes its buffers and GC pacing against; pick one that fits your process's real ceiling (see the [tour](/docs/tour-sdk)). `DeviceLocal` is in-process: if your process dies the tunnel dies with it, so run the `VpnService` as a foreground service and recreate the device on restart with the same `instanceId` and key material. ### iOS / macOS The `NEPacketTunnelProvider` owns the `SdkDeviceLocal` and packet flow, while the app process attaches to it as a remote device over loopback: ```swift // in the packet tunnel provider (owns the device): var err: NSError? let device = SdkNewDeviceLocalWithMemoryTarget( networkSpace, byJwt, deviceDescription, deviceSpec, appVersion, instanceId, /* enableRpc */ true, keyMaterial, memoryTarget, &err) // in the app process (attaches to it): let remote = SdkNewDeviceRemoteWithDefaults(networkSpace, byJwt, instanceId, &err) try remote?.setRpcServer(clientPem, serverCertPem: serverCertPem, hostPort: hostPort) ``` The app mints the key material and RPC PEMs (`SdkGenerateDeviceRpcKeyMaterial`) and hands them to the extension in the `NETunnelProviderProtocol` provider configuration; the extension reads `rpc_server_pem`, `rpc_client_pem`, and `rpc_listen_hostport` from there. There is no app group on this path. See the [tour](/docs/tour-sdk) for why the split exists and how reconnection works. ### cgo (Windows, Linux) The ABI contract, in short: - Objects are **opaque `uint64_t` handles**. `urnet_release(h)` frees the handle without stopping the object, so call its `*_close`/`*_stop` first where one exists. - Returned `char*` strings are caller-owned; free them with `urnet_free_string`. - Structured data crosses the boundary as **UTF-8 JSON** strings; ids are UUID strings, times are Unix epoch milliseconds (`0` = none). - Callbacks fire on **arbitrary Go-managed threads**; marshal to your own thread. Their strings and buffers live only for the call, and handles they hand you are yours to release. - Fallible calls take a `char** out_error`; on failure it is set to a message you free with `urnet_free_string`. Pass `NULL` to ignore the text. The header carries one platform split: `urnet_new_io_loop`, the fd pump the Linux app uses, sits inside `#if !defined(_WIN32)` and is absent from the Windows `.def`. On Windows you move packets with `urnet_device_local_send_packet` and `urnet_device_local_add_receive_packet`. A working end-to-end example lives at `cgo/smoke`; `make smoke_hpp` in `sdk/cgo` builds the C++ wrapper smoke test against a host build and runs it. ### JavaScript (wasm/web) ```js import { URNetwork } from "@urnetwork/sdk"; const sdk = await URNetwork.init({ wasmUrl: "/wasm/sdk.wasm", wasmExecUrl: "/wasm/wasm_exec.js", }); ``` The wasm registers its exports on `globalThis`, so run one module instance per page. `init` is idempotent within a module (a second call returns the same instance), but two copies of the loader, say two bundles or two frames sharing a realm, race over the same globals. Initialize once in a module-level singleton, never inside a component lifecycle. The socket examples use `sdk.createPlatformDeviceRemote({...})`, a `DeviceRemote` speaking device-RPC to a hosted Device over a WebSocket. Obtain the connection configuration and that hosted Device's actual instance ID from your hosting service: ```js const device = sdk.createPlatformDeviceRemote({ apiUrl: "api.bringyour.com", platformUrl: "connect.bringyour.com", byJwt, proxyUrl, signedProxyId, // HMAC auth token, not the JWT — see the tour instanceId, // the actual hosted Device instance, not a fresh UUID }); const unsub = device.addConnectLocationChangeListener((loc) => { console.log("location:", loc?.name); }); device.setConnectLocation({ bestAvailable: true }); ``` `createPlatformDeviceRemote` throws if the loaded wasm predates the `DeviceRemote` binding; that is the symptom of an old npm tag. ## Confirm it works Bring the device up and check the exit: any "what is my IP" check through the tunnel should now report a provider's address, not the machine's. The same state is visible in code and in the account: listeners fire as the connection changes (the JavaScript snippet above logs each location change as it lands), and the device appears in the account's device list under the `deviceDescription` you passed. On the C ABI, `urnet_live_handle_count()` reports live handles; assert it returns to baseline in leak tests. ## If something fails Support is the open channels: issues on the repos ([github.com/urnetwork](https://github.com/urnetwork)), product feedback at [feedback.ur.io](https://feedback.ur.io), and security reports to security@ur.io (disclosure policy at [ur.io/vdp](https://ur.io/vdp)). There is no paid SDK support tier today. Two stalls have easy explanations: a transfer stall on a working tunnel is usually an account out of data, and a JavaScript loader with nothing to load is the `latest` npm tag. The [tour](/docs/tour-sdk) covers the failure modes to know before you ship. ## What next - **Take the [SDK tour](/docs/tour-sdk).** The architecture behind each binding: process splits, threading, auth, reconnection, and sizing the memory target. - **Tell your users what they are joining.** If your app routes traffic through URnetwork, the [overview](/docs/overview) is the canonical account of the path and what each party can see, and the [threat model](/docs/threat-model) is the full record behind it. - **See the finished apps** for the experience your users will get: [Android](/docs/getting-started-android), [iOS](/docs/getting-started-ios), [macOS](/docs/getting-started-macos), [Windows](/docs/getting-started-windows), [Linux](/docs/getting-started-linux), and the [browser](/docs/getting-started-browser). --- # Install the SDK Choose your language's native package manager. Go, JavaScript and C/C++ use the base Go, JS/WASM and CGo SDKs directly. The other language packages wrap those same implementations. ![One SDK core, many packages: the Go module, JS/WASM runtime, CGo runtime and mobile frameworks it is delivered through, and the language packages that use or wrap them](/docs-assets/diagram-dev-install-sdk.svg) **Release availability:** two packages install today from their public registries: the Go module (through Go's module proxy) and `@urnetwork/sdk` for JavaScript and TypeScript (npm). The other language packages are awaiting publication; their commands below are the installation contract for that release, and each language guide also explains local package builds. Socket examples need a release containing the new socket API. | Language | Native installation | Available today | Guide | | --- | --- | --- | --- | | C | `vcpkg add port urnetwork-sdk` | Not yet published | [C guide](/docs/examples/c) | | C++ | `vcpkg add port urnetwork-sdk` | Not yet published | [C++ guide](/docs/examples/cpp) | | C# | `dotnet add package URnetwork.SDK` | Not yet published | [C# guide](/docs/examples/csharp) | | Go | `go get github.com/urnetwork/sdk/v2026@latest` | Yes | [Go guide](/docs/examples/go) | | Java | `implementation("io.ur:urnetwork-sdk:")` | Not yet published | [Java guide](/docs/examples/java) | | JavaScript | `npm install @urnetwork/sdk` | Yes | [JavaScript guide](/docs/examples/javascript) | | Kotlin | `implementation("io.ur:urnetwork-sdk:")` | Not yet published | [Kotlin guide](/docs/examples/kotlin) | | Python | `pip install urnetwork-sdk` | Not yet published | [Python guide](/docs/examples/python) | | Ruby | `gem install urnetwork-sdk` | Not yet published | [Ruby guide](/docs/examples/ruby) | | Rust | `cargo add urnetwork-sdk` | Not yet published | [Rust guide](/docs/examples/rust) | | Swift | `.package(url: "https://github.com/urnetwork/sdk-swift", exact: "")` | Not yet published | [Swift guide](/docs/examples/swift) | | TypeScript | `npm install @urnetwork/sdk` | Yes | [TypeScript guide](/docs/examples/typescript) | These unqualified commands select default/stable releases. For previews, use `npm install @urnetwork/sdk@nightly`, `pip install --pre urnetwork-sdk`, `dotnet add package URnetwork.SDK --prerelease`, or `gem install urnetwork-sdk --pre`. Cargo, Maven and SwiftPM can pin the exact preview version. Preview package names are the same as stable package names. ## Java and Kotlin on Android Use `io.ur:urnetwork-sdk-android:` instead of the desktop JVM coordinate. The Android AAR is built with gomobile; desktop Java/Kotlin use JNA over the CGo runtime. Swift uses the existing Apple XCFramework. ## Package contents Python wheels, Ruby gems, NuGet packages and desktop JVM packages include their supported native libraries. The Rust crate downloads a version-pinned, checksum-verified native asset at build time and embeds it in the executable. Consumers need no Go compiler or manual DLL download. Support is limited to the platforms included in that release; Linux packages state their libc floor. The npm package contains its paired Go/WASM runtime and TypeScript declarations, with runnable Node and browser examples. Both use a configured hosted Device. The browser's native fetch API has no custom socket factory; see the language's HTTP integration guide for its Axios request adapter and Direct Sockets example. ## Examples and socket behavior Open the [Examples browser](/docs/examples) for each language's installation README, `socket/README.md` run guide, and executable source files. Read [Socket](/docs/socket) for the difference between a kernel socket and a Device socket, including possible duplicate delivery when UDP races the first datagram across IPv4 and IPv6. For source installation, version pinning and alternative package managers, use the language guides above. C/C++ recipes are published to a configured first-party Conan remote or vcpkg Git registry; add that remote/registry once before the commands above. Inclusion in the upstream public collections requires their maintainers' acceptance. The language guides include this setup and local CMake archive installation. --- # Developers Three things to build on URnetwork, and three different credentials. Picking the right one is the first decision, and the difference is not cosmetic. | You are building | Start with | Credential | | --- | --- | --- | | An app or device that connects to URnetwork | [SDK](/docs/getting-started-sdk), then the [SDK tour](/docs/tour-sdk) | An account JWT, exchanged for one carrying a `clientId` | | An application client using TCP, UDP, TLS/DTLS, or Direct Sockets through a Device | [Socket](/docs/socket) | An initialized Device with an available connection path | | An app that runs a URnetwork provider and earns to one Bittensor wallet | [Integrate Provider](/docs/integrate-provider) | Your backend's root JWT, which provisions each installation's client JWT | | Automation over your own network | [Operator API](/docs/api) | Your network JWT or `urn_` API key | | A product people sign in to, admitting it to their network | [Sign in with URnetwork](/docs/sign-in-with-urnetwork) | An OAuth `client_id` issued to you | The line that matters is **whose network you are acting on**. The SDK and the Operator API are you acting on your own, with a credential you hold and control. Sign in with URnetwork is a person admitting your software to *theirs* — you never hold that credential, they grant it and they can withdraw it. ![Three surfaces, two credential systems — the SDK, the Operator API and Sign in with URnetwork with the credential each takes, your network and theirs divided by disjoint key sets, and the one exchange crossing between them](/docs-assets/diagram-dev-developers.svg) ## The SDK Start with [Install](/docs/install-sdk), then use the [Examples](/docs/examples) browser for executable programs in twelve languages. Each language has an installation guide and a socket directory with runnable HTTP client integrations. The Go SDK, JS/WASM SDK and CGo ABI share one networking engine. Desktop language packages wrap the CGo module; Android uses the gomobile AAR and Swift uses the Apple XCFramework. JavaScript includes both Node and browser examples using a hosted Device. [Socket](/docs/socket) explains how to use a Device's user-space TCP, UDP, TLS/DTLS and Direct Sockets connections. Applications can use these sockets without installing a system VPN. A browser's DeviceRemote uses its hosted Device's packet path; it does not require a browser-owned TUN interface. [Which binding to pick](/docs/getting-started-sdk#which-binding) lays out the trade-offs side by side. Take that decision before you write code: it settles your process model, not just your syntax. ## Operator API The HTTP API behind URnetwork. It bootstraps the `connect` protocol, issues the JWTs clients authenticate with, and exposes the match-making transactions the network runs on. Every route and schema is at [/docs/api](/docs/api), generated from the specification. It is scoped to **your** network. The name invites the reading that it operates on the network generally; it does not. One step trips nearly everyone: the `/auth` routes return a JWT **without** a `clientId`, and the `connect` protocol requires one **with** it. Use the `/network` routes to exchange it. A network is a globally unique subnet (`xyz.ur.network`); a `clientId` is a 16-byte address, equivalent to an IPv6 address and expressed as a UDID. ## Sign in with URnetwork Lets people admit your app or agent to their private network, so it can coordinate with everything else they have running there. This is in development and not yet live — see the [page itself](/docs/sign-in-with-urnetwork) for what exists today. The [MCP server](/agents) is not a fourth category. It is one resource server reachable with a Sign in with URnetwork token, and a worked example of the pattern. ## Token boundaries The two credential systems are signed with **disjoint key sets**. That is a security boundary rather than a convention: a Sign in with URnetwork token is not a platform credential, and presenting one where a platform JWT is expected fails by construction. OAuth access tokens are also audience-bound — each one verifies for exactly one resource and is rejected everywhere else. There is one sanctioned crossing, and it is a bridge rather than a bypass: an admitted app exchanges its OAuth token for a platform JWT carrying a `clientId`, scoped to the network it was admitted to. The exchange is an authorization decision made server-side; no single token verifies in two places. If you are holding two credentials and one of them is not working, this is usually why.