Mokatai 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, a NUC, or any always-on Linux box works. A Raspberry Pi (3 / 4 / 5 / Zero 2 W) works too.
  • 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 a window on your screen (or in mesh tui over SSH, if your coord is headless).

1. Install the coordinator

Pick whichever install path matches your setup:

Option A — Quick install, one line (any Linux)

curl -fsSL https://mesh.mokatai.io/install.sh | sudo bash -s -- --coord

The script sniffs your CPU (amd64 / arm64 / armv7), picks the matching tarball, sha256-verifies it, and runs the bundled installer. It auto-picks the headless variant on a Pi or any host without a desktop session.

Option B — Manual install (download tarball)

Download the matching variant from the download page, then:

# Replace <suffix> with one of: amd64, amd64-headless, arm64, armv7.
tar -xzf mokatai-mesh-vX.Y.Z-coord-linux-<suffix>.tar.gz
cd mokatai-mesh-coordinator-linux-<suffix>
sudo ./install.sh

The installer handles everything — picks up any missing system pieces, sets things up, starts the service. On a desktop host it opens the Mokatai Mesh Admin window automatically. On a headless host it prints a URL like http://<your-ip>:8080/ui/ you can open from any browser on the LAN.

First launch — pick a path

Either way, the first time you open the admin UI you see a chooser:

  • Create a new network — this is the first coord. You provide the public host:port peers will dial (the coord auto-detects a private IPv4 if you leave it blank for a LAN-only setup). A lone coord leads its own cluster of one.
  • Join an existing network — this coord joins an existing mesh as another equal hub. You’ll need a coordinator invite from any current coord, created with its top-bar Invite button (pick Coordinator as the type). The invite carries everything the joining coord needs — paste its link or short code into this wizard. It syncs state, joins the cluster, and from then on takes part in the leader election. (See Run a second coordinator for redundancy under “What’s next” for the full walkthrough.)

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 Mokatai Mesh 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. Invite your first peer

The Admin window opened to the Dashboard. Click Invite in the top bar — the Invite to your mesh slide-over opens.

  1. Choose Person or device (the other type, Coordinator, is for adding a second hub — see “What’s next”).
  2. Give it a friendly name (e.g. my-laptop).
  3. Leave the role as user (the default).
  4. Optionally set an expiry and whether the invite is reusable (single-use by default). Click Create invite.

You get a shareable invite: a link, a QR code, and a short code. Send any one of these to whoever (or whatever) is joining — no token to copy, no separate URL to hand out. The invite is single-use and expires (24h by default) unless you marked it reusable.

4. Connect from the peer

Open the invite link on the device you’re joining (or have someone open it there). The coordinator serves an OS-aware join page that shows the right path automatically:

Desktop / laptop (Linux) — install Mokatai Mesh:

The page shows a single one-liner. Copy it, paste it into a terminal on the peer machine, and run it:

curl -fsSL <coord>/join/<code>/install.sh | sudo bash

That downloads the agent, installs it as a service that survives reboots, and auto-enrolls using the invite — no further UI steps. This gets you the full feature set: auto-failover, status monitoring, direct peer-to-peer connections. (A Windows installer is coming soon; for now the one-liner is Linux-only.)

Phone / tablet (iOS, Android) — stock WireGuard (coming soon):

The join page has a slot for a WireGuard QR code, but that path is still being wired up. For now, onboard phones another way (e.g. install on a desktop with the one-liner above).

Already have Mokatai Mesh installed on the peer?

No need to reinstall. Either click the invite link to fire the mokatai-mesh://join/<code> deep link (opens the client straight into the join flow), or open the client’s Join a mesh screen and paste the link or short code there.

CLI / legacy path. The old one-shot enrollment token still works for scripting and back-compat: mesh add-peer on the coord mints a token, and the agent enrolls with --enroll --token <token> (or the coord’s POST /enroll {token}). The invite flow above is the recommended path; reach for the token only when you’re automating.

5. Verify the connection

Back in the Admin window, the Peers page shows your new peer the moment the invite is redeemed — first as pending, then flipping to Online with a recent handshake time once it connects.

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.

Headless? Use mesh tui

If your coord runs on a Pi or a server without a desktop, the same admin operations are available in a terminal:

sudo mesh tui

Auto-detects whether the host is a coord or an agent. Coord screens: Status / Peers (add, edit, delete) / Enroll / Logs. Agent screens: Status / Peers / Logs / Join-or-leave. Quit with q, cycle screens with Tab, ? shows keybindings.

The same web UI on http://<host>:8080/ui/ is reachable from any browser on the LAN — both surfaces stay in sync.

What’s next

  • Add more peers — click Invite again, pick Person or device. Same process. One peer per device on your mesh.
  • Invite other people — hand someone the invite link, QR, or short code, and they’re on. No signup, no account creation, no SaaS in the middle. Mark an invite reusable to onboard a whole batch from one link.
  • 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 more coordinators for redundancy — install another coord on a different box (same install flow above). On any current coord, click Invite, pick Coordinator as the type, and create the invite (these are short-lived — 30 min by default). On the new box’s first launch, pick Join an existing network and paste the invite’s link or short code. The new coord syncs state and joins the cluster as an equal member — it can serve reads/tunnels and stand for leader. If the current leader dies, a new one is auto-elected and writes resume (no manual promotion). One caveat: deciding writes needs a majority, so run three or more coords for write high-availability — a 2-coord cluster keeps serving reads and tunnels if one is down but pauses writes until the other returns. Push to mesh drives updates to every coord AND every agent from one click.
  • Going deeper? — see ARCHITECTURE.md for the technical details: how peers find each other, how endpoint probing works, self-update plumbing, the mesh CLI + TUI, manifest schema, and full troubleshooting.

When something goes wrong

The install command can’t find a package — your Linux distro is older than Mokatai Mesh 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 installer refuses with “this tarball is for X but this host is Y” — you downloaded the wrong architecture. Re-run the curl one-liner (which sniffs uname -m automatically) or grab the matching <suffix> tarball from the download page.

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. On a headless install, this is the expected flow — there’s no Admin window, only the web UI.

mesh tui says “this coordinator hasn’t finished first-run setup” — the coord booted but you haven’t picked create new or join existing yet. Open the web UI at http://localhost:8080/ui/ and finish the wizard, then re-run mesh tui.

“Join an existing network” says the invite was rejected — you pasted the wrong invite type, or it expired. The coord-join wizard needs a Coordinator invite from a current coord (top-bar Invite → Coordinator), and those are short-lived (30 min by default) — mint a fresh one if it’s stale. A Person or device invite won’t work here; it’s a different invite type.

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 host:port (shown on the Settings page) is what the invite link points at — that’s the address peers dial.

“Push to mesh” didn’t update the replica coords — both ends need to be on v0.17.2 or newer (that’s when the cluster-wide push RPCs were added). Bring each replica forward once manually with the curl installer, and from then on the primary’s push reaches them automatically.

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