Unified Tactical Mesh

Quickstart

Set up your first private network in about ten minutes. No prior networking experience needed.

What you’ll need

  • One Linux machine that other devices can reach over the internet. This will be your coordinator — the brain of the network. A small cloud VM, a home server, or any always-on Linux box works.
  • One other device (Windows, Mac, phone, anything) to join the network as a peer.

You’ll touch the terminal once — to run the install command. After that, everything happens in an app window on your screen.

1. Install the coordinator

Download the coordinator from the download page. Open a terminal on your Linux machine, then:

tar -xzf UTM-vX.Y.Z-coord-linux.tar.gz
cd UTM-coordinator-linux-amd64/
sudo ./install.sh

The installer handles everything — it picks up any missing system pieces, sets things up, starts the service, and opens the UTM Admin window already signed in. From here on, the terminal is done.

2. Make the coordinator reachable

If your coordinator is a cloud server with a public IP, skip this step — it’s already reachable.

If it’s a machine at home or behind an office router, you need to tell the router to forward incoming traffic on UDP port 51820 to the coordinator. This is the one piece of network setup UTM can’t do for you, because it lives on your router, not on the machine.

  1. Open your router’s admin page. It’s usually at http://192.168.1.1 or http://10.0.0.1 — check the sticker on the bottom of the router.
  2. Find the Port Forwarding section. Different routers call it NAT, Virtual Servers, or Pinholes.
  3. Add a rule:
    • Protocol: UDP
    • External port: 51820
    • Internal port: 51820
    • Internal IP: the local IP of your coordinator machine (visible in the Admin window’s Settings page, or in your router’s “connected devices” list).
  4. Save. Reboot the router if it asks.

Some ISPs block port 51820 specifically. If you suspect that, the Admin window’s Settings page lets you change the port to anything between 49152 and 65535 — forward that one instead.

3. Add your first peer

The Admin window opened to the Peers page. Click Add Peer in the top right.

  1. Give it a friendly name (e.g. my-laptop).
  2. Leave the role as user (the default).
  3. Click Create.

A window pops up with two ways to connect this device:

  • Install UTM on the peer (recommended for laptops and desktops) — full feature set: auto-failover, status monitoring, direct peer-to-peer connections. Available for Linux and Windows.
  • Use stock WireGuard (quickest, works on anything) — scan a QR code or import a .conf file into the regular WireGuard app. Works on Mac, iOS, Android, and any Linux or Windows machine you don’t want to install UTM on.

Pick whichever fits the device. You can mix the two across your peers — some with UTM, some just using WireGuard.

4. Connect from the peer

If installing UTM (Linux or Windows):

The enrollment window shows a one-line command. Copy it, paste it into a terminal on the peer machine, and run it.

For a permanent install that survives reboots, download the agent tarball from the download page and run its install.sh the same way you installed the coordinator. The installer asks for the URL and token from the enrollment window, then sets everything up as a background service.

If using stock WireGuard:

  • Phone: open the WireGuard app, tap the +, scan the QR code in your Admin window, and slide to activate.
  • Computer: in your Admin window, click Download .conf, then import that file into the WireGuard app on the peer machine.

5. Verify the connection

Back in the Admin window, the Peers page should show your new peer as Online, with a recent handshake time.

That’s it — you have a working private network. The peer device can now reach the coordinator at 10.77.0.1, and any other peer you add can reach this one the same way.

What’s next

  • Add more peers — click Add Peer again. Same process. One peer per device on your mesh.
  • Invite other people — give someone a peer name and the QR code from the enrollment window, and they’re on. No signup, no account creation, no SaaS in the middle.
  • Lock down who can talk to whom — by default every peer can reach every other peer (the mesh is open until you say otherwise). When you want to restrict that, the Admin window’s ACL Rules page lets you set role-based rules. Adding even one rule switches the whole mesh to default-deny. Optional — leave it alone until you need it.
  • Run a second coordinator for redundancy — if you want the network to keep working when one coordinator is down, you can run more than one. See the Cluster page in the Admin window.
  • Going deeper? — see ARCHITECTURE.md for the technical details: how peers find each other, how endpoint probing works, self-update plumbing, the utmctl CLI, and full troubleshooting.

When something goes wrong

The install command can’t find a package — your Linux distro is older than UTM expects, or the package mirrors are unreachable. Either install the missing package manually with your distro’s package manager (the installer prints which one was missing), or try a newer Linux machine.

The Admin window doesn’t appear — the service is probably still running fine; the desktop window just didn’t pop up. Open a browser to http://localhost:8080. The Admin window is just a wrapper around that URL, so the UI works either way.

The peer shows “Offline” — the peer’s device can’t reach your coordinator over UDP 51820. The most common cause is the port-forwarding step (Section 2) not being set up, or being set up against the wrong internal IP. Double-check both: that UDP 51820 is forwarded, and that the coordinator’s public IP (shown in the enrollment window) is what you’re handing out to peers.

Anything else — see ARCHITECTURE.md’s “Failure modes + debugging” section for the full reference.