# 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 also encrypt traffic to the provider by default. 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).