URnetwork
•••
Getting started

Getting started on Linux

5 min readView as markdown ↗

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.

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 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.

1. Install the daemon

Use the .deb on Debian, Ubuntu, and derivatives:

sudo apt install ./urnetwork-daemon_<version>_<arch>.deb

or the install tarball on distributions without dpkg:

tar xf urnetwork-daemon-<version>-<arch>.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-<version>-<arch>.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.

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, 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.

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.

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 explains the path your traffic takes. The tour 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 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 reaches the team, and the FAQ answers common questions.

What next

  • Take the tour. 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 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 does the same job: urnetwork auth with a code from any app, then urnetwork provide. Providers participate in the UR protocol; ur.xyz documents how rewards work.
  • Try another platform: Android, iOS, macOS, Windows, and the browser.