RomM Server Setup

RomM server setup

LodorOS is a client for a RomM server you host. This page covers exposing that server privately so your handhelds can reach it without putting your library on the open internet. Set up whichever transport you plan to use; you only need one, but Tailscale + Cloudflare Access side-by-side lets capable devices use Tailscale and low-RAM devices use Cloudflare.

Placeholder hostnames below (romm.example.com, *.ts.net) — substitute your own.

Tailscale (preferred)

Run Tailscale on the host (or a sidecar container that shares RomM's network namespace) and expose RomM over the tailnet with tailscale serve:

tailscale serve --bg http://127.0.0.1:8080

This publishes RomM at https://<node>.<tailnet>.ts.net tailnet-only, with an automatic Let's Encrypt certificate. Nothing is exposed to the public internet. Note the *.ts.net hostname — that's what you enter on the device.

• Serve routes by hostname/SNI, so devices must use the *.ts.net name, not the node's 100.x IP.
• The device resolves that name through Tailscale's own DNS over the tunnel — no extra DNS config needed on the handheld.

Cloudflare Access

For devices that can't run Tailscale (the Miyoo Mini Plus), expose RomM through a Cloudflare Tunnel and gate it with Cloudflare Access + a service token.

1. Tunnel. Run cloudflared (a container is easiest) and add an ingress rule mapping a hostname to RomM: romm.example.com → http://<romm-host>:8080. Point the DNS record at the tunnel.

2. Access application. In the Zero Trust dashboard, create an Access application for romm.example.com (whole host, so /api/* is covered).

3. Service token. Zero Trust → Access → Service Auth → Service Tokens → Create. Copy the Client ID and Client Secret (the secret is shown only once). Choose a duration and note the expiry.

4. Service-Auth policy. On the application, add a policy with Action = Service Auth (⚠️ not "Allow" — an Allow policy redirects the tokenless device to a login page) and Include → Service Token → (your token). Keep your normal human-login policy alongside it; Access evaluates Service Auth first.

5. (Optional) Clean failures. Enable the app setting that returns HTTP 401 instead of the HTML login page on a bad/expired token, so the device gets a machine-readable error.

The device then sends CF-Access-Client-Id / CF-Access-Client-Secret on every request. Cloudflare validates them at its edge and forwards to RomM; RomM authenticates the request with its own token independently (the two live in different headers and don't collide).

Rotation: service tokens default to a 1-year life. To rotate without bricking a deployed device, create a second token, add it to the policy, push it to the device, verify, then revoke the old one.

Home network (LAN)

If you want the simple IP:port path, RomM must actually be reachable on your LAN — publish its port on the host (e.g. -p 8080:8080) and confirm the backend binds 0.0.0.0, not just loopback. Many private setups deliberately keep RomM off the LAN and use only Tailscale/Cloudflare; if so, the "Home network" onboarding option won't reach it.

Pairing tokens

Regardless of transport, each device pairs to RomM with a client token / pair code you generate in RomM's web UI. Treat these — and the Cloudflare service secret — as passwords. See RomM's docs for token management and revocation.