Reaching Your RomM Server

Reaching your RomM server

Lodor-NextUI never requires exposing RomM on the open internet. It supports three paths:

Path	Best for	How
Home network / public URL	RomM reachable by IP/hostname on the same Wi-Fi (or an endpoint you already publish)	Enter the address in onboarding
Tailscale	Remote access over your own private network — no ports opened, no public endpoint	Built into onboarding: sign in by scanning a QR code
Cloudflare Access	A public endpoint protected by a machine (service) token	Pre-seed a cf_access block, then onboard

Whichever path, your RomM must be 4.8.0 or newer (device pairing shipped in stock RomM at 4.8.0).

---

Option A — Home network / public URL

If RomM is reachable at a host IP:port from the device's Wi-Fi, this is the simplest path.

1. Connect the device to the same Wi-Fi (NextUI Settings).
2. In onboarding, choose Home network / public URL, pick http (or https if the endpoint has TLS), enter the address — e.g. host 192.168.1.50, port 8080 — and pair.

A LAN address only works on the same network, and requires RomM to actually be reachable there.

---

Option B — Tailscale (built in, QR sign-in)

The pak bundles its own userspace Tailscale client — no root, no kernel module, no store pak, and still no NextUI modification. Your RomM server sits on your private Tailscale network; the handheld joins it and reaches RomM through the tunnel.

1. In onboarding, at "How will you reach RomM?", choose Tailscale (sign in with QR).
2. The device shows a QR code (and the raw sign-in URL as a fallback). Scan it with your phone, sign in to your Tailscale account, and approve the new device.
3. When the tunnel is up, the wizard continues to the server address. Enter your RomM node's Tailscale name.

tailscale serve is HTTPS-only. If your RomM is published with tailscale serve, the server must be entered as https://romm.your-tailnet.ts.net — pick https at the protocol step. Plain http:// to a tailscale serve host is refused by Tailscale and shows up as a network error at pairing.

After onboarding, the tunnel comes up automatically whenever Lodor syncs — you don't manage it. Three maintenance entries live in the Lodor menu:

• Tailscale status — is the tunnel connected right now.
• Tailscale: Reconnect — restarts the tunnel using your saved sign-in; the first thing to try if the tunnel is wedged.
• Tailscale: Reset & forget — wipes the saved Tailscale login for a clean re-sign-in (the device also disappears from your Tailscale admin's device list once you remove it there).

The sign-in is interactive and yours: no auth-key files on the card, and the device appears in your Tailscale admin console like any other machine, where you can revoke it.

---

Option C — Cloudflare Access (service token)

Your RomM sits behind a Cloudflare Tunnel at a public hostname, protected by Cloudflare Access. The device authenticates non-interactively with a service token — two headers on every request — so there's no browser login.

You'll need from your Cloudflare Zero Trust setup:

• your public RomM URL, e.g. https://romm.example.com
• a service-token Client ID and Client Secret

The onboarding wizard has no service-token field (a Cloudflare-gated endpoint would just show the login page to a plain URL). So for CF Access you pre-seed the cf_access block before onboarding. The wizard's server + pairing steps preserve any cf_access you've already written — so pairing then flows through Cloudflare correctly.

On the card, create .userdata/shared/Lodor/config.json (make the folders if absent) with:

{
  "hosts": [
    {
      "root_uri": "https://romm.example.com",
      "cf_access": {
        "client_id": "<CF-Access-Client-Id>",
        "client_secret": "<CF-Access-Client-Secret>"
      }
    }
  ]
}

Then boot, connect Wi-Fi, and open Tools → Lodor (choose Home network / public URL at the reach step):

• At the server step, enter the same https://romm.example.com (the wizard rewrites root_uri but keeps your cf_access intact — it'll tell you: "Cloudflare Access config found — pairing will use it").
• Enter a RomM pairing code. The pairing request goes through Cloudflare — Lodor sends CF-Access-Client-Id / CF-Access-Client-Secret on every request; Cloudflare validates them and forwards to RomM, which still authenticates with its own paired token independently (different headers, no collision).

Keep this config.json private — the client secret and the RomM token are credentials. Lodor stores them here at rest and never prints them.

Two auth layers (Cloudflare path)

1. Transport auth — the Cloudflare service token proves the device may reach the endpoint.
2. RomM auth — the RomM token you pair proves the device to RomM itself.

Both live on the card and are treated as secrets. See Troubleshooting if pairing or sync fails.