Skip to content

Config File Reference

Jump to bottom
lodordev edited this page Jul 1, 2026 · 2 revisions

The config file (config.json) — full reference

LodorOS keeps its entire connection setup in one JSON file. The onboarding wizard writes it for you, but you can also hand-edit it — that's the flexible path for setups the wizard doesn't cover yet (chiefly Cloudflare Access), for pre-configuring a card before first boot, or for cloning a working setup onto more cards.

This file holds secrets — a RomM token and (if used) your Cloudflare service-token secret. Keep it private; never commit it or post it anywhere.

Where it lives

<SD card>/Tools/<platform>/Lodor.pak/config.json

<platform> is your device's platform code — e.g. miyoomini (Miyoo Mini / Mini Plus), my355 (Mini Flip), rg35xxplus (Anbernic H700 family), rgb30. Each platform pak has its own copy; if a card is used in only one device you only need that one.

Minimal shape

{
  "hosts": [
    {
      "root_uri": "https://romm.example.com",
      "token": "<romm-client-token>",
      "device_id": "<registered-device-id>"
    }
  ],
  "api_timeout": 30,
  "download_timeout": 3600
}

The launcher treats a card as already connected (skips onboarding, boots to the library) only when hosts[0] has root_uri AND token AND device_id all present and non-empty. Omit any of those and the wizard runs so you can fill them in on the device.

Top-level fields

Field Type Meaning
hosts array Connection targets. hosts[0] is the one used. (The array shape leaves room for multi-tier / fallback.)
api_timeout int (s) Per-request timeout for API calls. Default 30.
download_timeout int (s) Timeout for a ROM download. Default 3600.
directory_mappings object Optional, advanced. Override where a platform's ROMs live on-card. Most setups omit it.

hosts[0] fields

You set these:

Field Type Meaning
root_uri string Your RomM's base URL, scheme://host (e.g. https://romm.example.com). Use the name, not a bare Tailscale 100.x IP — tailscale serve routes by hostname.
port int Optional non-standard port. 0/omitted = default for the scheme.
token string A RomM client token (see pairing / scopes).
device_id string The id of a registered device (RomM assigns it). Must be a real registered device or save uploads are rejected.
device_name string Friendly name shown in RomM's device list.
insecure_skip_verify bool Skip TLS certificate verification. Leave false unless you're on a private CA / self-signed cert you trust.
tier int Route hint: 1 = Tailscale (SOCKS5), 2 = public/Cloudflare. Optional; the engine also probes reachability.
cf_access object Cloudflare Access service token — see below.
socks5_proxy string Tailscale SOCKS5 address (e.g. localhost:1055). Set by the Tailscale onboarding path; you rarely write this by hand.

The engine manages these (written after pairing — leave them out when hand-authoring; they'll be filled in):

username, token_name, token_expires_at, scopes.

Cloudflare Access — the cf_access block

For a RomM behind Cloudflare Access, add a service-token pair. The engine then sends CF-Access-Client-Id / CF-Access-Client-Secret on every request (independent of the RomM token — they live in different headers and don't collide):

{
  "hosts": [
    {
      "root_uri": "https://romm.example.com",
      "token": "<romm-client-token>",
      "device_id": "<registered-device-id>",
      "device_name": "My Handheld",
      "tier": 2,
      "cf_access": {
        "client_id": "<CF-Access-Client-Id>",
        "client_secret": "<CF-Access-Client-Secret>"
      }
    }
  ],
  "api_timeout": 30,
  "download_timeout": 3600
}

Your Cloudflare Access application must have a policy with Action = "Service Auth" (not "Allow") that includes this service token — see RomM server setup → Cloudflare Access. Without it, the device gets bounced to a login page and never reaches RomM.

Getting a token (and the scopes it needs)

The device authenticates to RomM with a client token. Create one in RomM's web UI (or via the onboarding pair step). Whatever way you get it, the token must carry the scopes LodorOS uses, or the connection check fails:

  • platforms.read — the reachability/auth check reads /api/platforms; without this it returns 403 and the card reads as "not connected."
  • assets.read, assets.write — save & cover sync.
  • devices.read, devices.write — device registration / attribution.
  • Also useful: me.read, me.write, roms.read, roms.user.read, roms.user.write, collections.read.

Wi-Fi — wifi.txt (separate file)

Wi-Fi credentials are not in config.json. They live in a plain file at the card root:

<SD card>/wifi.txt

Format is one network per line as SSID:password (the : is the delimiter, so SSIDs may contain spaces; # lines are comments):

MyHomeNetwork:mywifipassword

Pre-configured cards: if you pre-fill config.json so the card is already connected, onboarding is skipped entirely — including the Wi-Fi step. So a fully-pre-configured card needs a wifi.txt too, or it will boot straight to the library with no way onto the network.

Editing safely (FAT32)

The SD card is FAT32. When you edit config.json on a computer, write it fully and eject cleanly (don't yank the card mid-write) — a half-written FAT32 file can leave the card unbootable. On device, the engine writes config atomically for you.

Cloning to more cards

To set up several cards the same way: flash LodorOS to each, then drop the same wifi.txt and a config.json onto each. Give each card its own registered device + token (don't share one token across many physical devices) so RomM's per-device tracking stays clean.

Clone this wiki locally