### Index

---
title: Introduction
description: Your beautiful, powerful, self-hosted ROM manager and player
hide:
    - toc
---



<img src="./resources/romm/isotipo.svg" height="200px" width="200px" alt="RomM logo">
<img src="./resources/romm/logotipo.png" height="250px" width="250px" alt="RomM word type" style="margin-top: 10px;">
/// caption
Welcome to the **RomM Project**, the premier self-hosted, open source ROM manager.
///

<div style="text-align: center">
<a href="https://romm.app" target="_blank">Website</a> · <a href="https://demo.romm.app" target="_blank" >Demo</a> · <a href="https://discord.gg/romm" target="_blank">Discord</a>
</div>

RomM (ROM Manager) lets you scan, enrich, organise, and play your game collection from a clean web UI, with metadata from IGDB, ScreenScraper, MobyGames, RetroAchievements, Hasheous, LaunchBox, and more. In-browser play via EmulatorJS and Ruffle, companion apps for Android, handhelds, and desktop, and a first-class multi-user experience with OIDC SSO.

## Where do you want to go?

<div class="grid cards" markdown>

- :material-rocket-launch-outline: **I'm new, get me running**

    ***

    15 minute Docker Compose walkthrough to a working instance.

    [Quick Start →](getting-started/quick-start.md)

- :material-cog-outline: **I'm running RomM for my family/friends**

    ***

    Users, roles, OIDC, scheduled tasks, backups, reverse-proxy recipes.

    [Administration →](administration/index.md)

- :material-controller-classic-outline: **I just want to play**

    ***

    Library, collections, saves & states, ROM Patcher, Netplay.

    [Using RomM →](using/index.md)

- :material-api: **I'm building on top of RomM**

    ***

    API reference, WebSockets, device sync protocol, client tokens.

    [Developers →](developers/index.md)

</div>

## Philosophy

RomM is built for its users, not for shareholders: self-hosted, open-source, no tracking, no upsells. The core app is licensed under [GNU AGPLv3](https://choosealicense.com/licenses/agpl-3.0/), and other projects in the umbrella use permissive licenses ([GPLv3](https://choosealicense.com/licenses/gpl-3.0/) for software, [CC0](https://choosealicense.com/licenses/cc0-1.0/) for documentation).

**RomM is and will always be free and open-source software.**

## Community

Join us on Discord to ask questions, share your setup, request features, or help other users. Code, issues, and releases live on [GitHub](https://github.com/rommapp/romm).

<div style="text-align: center">
    <a href="https://discord.gg/romm" target="_blank">
        <img src="https://invidget.switchblade.xyz/romm" alt="Join our Discord" class="skip-lightbox">
    </a>
</div>

---

### About/Brand Guidelines

---
title: Brand Guidelines
description: How to use the name, logo, and colors
---



# Brand Guidelines

In this context, "RomM", "The RomM Project", "the project", "we", "us", and "our" refer to the RomM project and organization.

## The logo

<div align="center">
  <img src="../../resources/romm/isotipo.svg" width="180px" height="auto" alt="RomM logo">
  <br />
  <br />
</div>

The logo should always be used in its standard colors:

<div align="center">
  <table>
    <tr>
      <th>Color</th>
      <th>Hex</th>
    </tr>
    <tr>
      <td><img src="../../resources/romm/brand_guidelines/371f69.png" height="16" width="16" alt="#371f69"></td>
      <td><code>#371f69</code></td>
    </tr>
    <tr>
      <td><img src="../../resources/romm/brand_guidelines/553e98.png" height="16" width="16" alt="#553e98"></td>
      <td><code>#553e98</code></td>
    </tr>
    <tr>
      <td><img src="../../resources/romm/brand_guidelines/ede5f8.png" height="16" width="16" alt="#ede5f8"></td>
      <td><code>#ede5f8</code></td>
    </tr>
    <tr>
      <td><img src="../../resources/romm/brand_guidelines/bea4e1.png" height="16" width="16" alt="#bea4e1"></td>
      <td><code>#bea4e1</code></td>
    </tr>
    <tr>
      <td><img src="../../resources/romm/brand_guidelines/e6c7a7.png" height="16" width="16" alt="#e6c7a7"></td>
      <td><code>#e6c7a7</code></td>
    </tr>
    <tr>
      <td><img src="../../resources/romm/brand_guidelines/e1a38d.png" height="16" width="16" alt="#e1a38d"></td>
      <td><code>#e1a38d</code></td>
    </tr>
  </table>
</div>



## Do these things

- Use our logo to link to any page or site operated by the project.
- Use our logo in a blog post or news article about the project.
- Use our logo to inform others that your project integrates with RomM.
- Always use our logo in the colors provided.
- Always use our name in a way that makes clear you are not affiliated with the project.

If you're building something that integrates with RomM and would like to use/remix the logo, **please reach out first** via [Discord](https://discord.gg/romm). We'd love to hear about it.

## Please don't

- Use our name or logo in any way that suggests you are us, are endorsed by us, or are part of the project.
- Use our name or logo in a way that implies partnership, sponsorship, or endorsement.
- Use our name or logo as the name or logo for your project, product, service, social media account, company, or website.
- Use our name or logo to promote, advertise, or sell any private business, closed-source software, commercial product, or paid service.

## Downloadables

The logo assets live at [rommapp/romm/tree/master/frontend/assets/](https://github.com/rommapp/romm/tree/master/frontend/assets/):

- `isotipo.svg`/`isotipo.png`: the mark (circular logo)
- `logotipo.svg`/`logotipo.png`: the wordmark
- `social_preview.png`: GitHub social preview

## Questions

Ask on [Discord](https://discord.gg/romm) or open an issue.

---

### About/Credits

---
title: Credits
description: The humans, projects, and services that make RomM possible.
---

# Credits

This project exists because a lot of people contributed code, designs, translations, ideas, and, most importantly, running bug reports back to the project. Thanks to every one of them.

## Contributors

[Every contributor](https://github.com/rommapp/romm/graphs/contributors) to [rommapp/romm](https://github.com/rommapp/romm), plus contributors to the surrounding repos:

- [rommapp/argosy-launcher](https://github.com/rommapp/argosy-launcher/graphs/contributors)
- [rommapp/grout](https://github.com/rommapp/grout/graphs/contributors)
- [rommapp/playnite-plugin](https://github.com/rommapp/playnite-plugin/graphs/contributors)
- [rommapp/docs](https://github.com/rommapp/docs/graphs/contributors)

## Translators

The 19 locales exist because individual community members took the time to translate the UI. See each locale folder's commit history at [rommapp/romm/tree/master/frontend/src/locales](https://github.com/rommapp/romm/tree/master/frontend/src/locales) for per-locale credit.

## Community apps

Built by the community, not the RomM team. Full list in the [Community section in the RomM README](https://github.com/rommapp/romm/#community).

## Financial supporters

Donors via [Open Collective](https://opencollective.com/romm) make continued development possible. The project wouldn't exist without you. Thank you! ❤️

## Upstream projects

This stack stands on an enormous amount of open-source work. In rough order of "how visible they are to users":

### In-browser emulation

- [EmulatorJS](https://emulatorjs.org/)
- [Ruffle](https://ruffle.rs/)
- [dosbox-pure](https://github.com/schellingb/dosbox-pure)

### Metadata sources

- [IGDB](https://www.igdb.com/)
- [ScreenScraper](https://screenscraper.fr/)
- [MobyGames](https://www.mobygames.com/)
- [RetroAchievements](https://retroachievements.org/)
- [SteamGridDB](https://www.steamgriddb.com/)
- [Hasheous](https://hasheous.org/)
- [Playmatch](https://github.com/RetroRealm/playmatch)
- [LaunchBox Games Database](https://gamesdb.launchbox-app.com/)
- [TheGamesDB](https://thegamesdb.net/)
- [Flashpoint Archive](https://flashpointproject.github.io/flashpoint-database/)
- [HowLongToBeat](https://howlongtobeat.com/)
- [Libretro](https://www.libretro.com/)

### Backend stack

- [FastAPI](https://fastapi.tiangolo.com/) + [Starlette](https://www.starlette.io/)
- [SQLAlchemy](https://www.sqlalchemy.org/) + [Alembic](https://alembic.sqlalchemy.org/)
- [RQ](https://python-rq.org/)
- [MariaDB](https://mariadb.org/)/[PostgreSQL](https://www.postgresql.org/)/[MySQL](https://www.mysql.com/)
- [Redis](https://redis.io/)/[Valkey](https://valkey.io/)
- [nginx](https://nginx.org/) with [`mod_zip`](https://github.com/evanmiller/mod_zip)
- [uv](https://docs.astral.sh/uv/)

### Frontend stack

- [Vue 3](https://vuejs.org/)
- [Vuetify](https://vuetifyjs.com/)
- [Pinia](https://pinia.vuejs.org/)
- [Vite](https://vitejs.dev/)
- [socket.io](https://socket.io/)
- [vue-i18n](https://vue-i18n.intlify.dev/)
- [rom-patcher-js](https://www.marcrobledo.com/RomPatcher.js/)
- [vite-plugin-pwa](https://vite-pwa-org.netlify.app/)

### Docs stack

- [MkDocs](https://www.mkdocs.org/) + [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
- [mike](https://github.com/jimporter/mike) for docs versioning
- [asciinema](https://asciinema.org/) for terminal recordings

## Missing?

Open a PR against this page. Credit is cheap, and we want to give it where it's due.

## See also

- [License](license.md)
- [Contributing](../developers/contributing.md)

---

### About/Faqs

---
title: FAQs
description: Answers to the questions users most often ask
---

# FAQs

## What is RomM?

RomM (ROM Manager) allows you to scan your library, pull metadata, browse a clean UI, play in the browser, sync to handhelds, and run it all on your own hardware.


!!! note "RomM is server software you run on a homelab box or NAS"
    It is not a desktop app, and there's no `.exe` or `.appimage`. You'll need basic Linux + Docker skills to set it up. **Games and copyrighted material aren't provided.**

## Is it free?

Yes! Licensed under [AGPL-3.0](license.md), the core will always be free. Other repos under our umbrella use equally permissive licenses, and there's no tracking or upsells.

## How does it compare to [X other manager]?

The emphasis here is self-hosted + multi-user + in-browser-play + the companion-app ecosystem. If those matter, try it, but if you just want a local Windows app that scans a folder, tools like LaunchBox may fit better.

## Do I need metadata API keys?

It runs without any but games won't match against a metadata source, so you won't get covers, descriptions, or ratings.

## Is RomM legal?

The software is legal but what you put in it depends on your jurisdiction. **We don't ship ROMs or firmware, don't help you find them, and can't give legal advice.**

## Can I run RomM on [X]?

Probably! Supported deployment paths:

- Docker Compose (Linux, macOS, Windows with WSL2)
- Unraid/Synology/TrueNAS SCALE
- Kubernetes

See [Install & Deploy](../install/index.md).

Not supported:

- Bare metal without containers (undocumented but _should_ work)
- TrueNAS CORE (FreeBSD)
- Windows without WSL

## How much RAM/CPU does it need?

- **Minimum** (small library, 1 user): 512 MB RAM, any modest CPU
- **Comfortable** (thousands of ROMs, a few users, occasional scans): 2 GB RAM, 2 cores

Heaviest CPU usage is during scans, as hashing and network-bound metadata calls may cause spikes.

## How do I update?

```sh
docker compose pull rommapp/romm
docker compose up -d romm
```

Read the [upstream release notes](https://github.com/rommapp/romm/releases) before minor or major version upgrades.

## Why can't I see a specific platform?

The platform folder name probably doesn't match a known slug. Check [Supported Platforms](../platforms/supported-platforms.md), and fix it by either renaming the folder or updating the [`system.platforms`](../reference/configuration-file.md#systemplatforms) binding in `config.yml`.

## Why are my ROMs unmatched after a scan?

Most common reasons:

- No metadata providers configured
- Filename too generic (no tags, unusual naming)
- Wrong platform detection

Full troubleshooting steps can be found in [Scanning Troubleshooting](../troubleshooting/scanning.md).

## My scan finds platforms but no games inside them

This is almost always a mount-depth issue. The scanner expects the _parent_ of your `roms/` folder mounted to `/romm/library`, not the `roms/` folder itself. If your files live at `/opt/romm/library/roms/gbc/game.gbc`, mount `/opt/romm/library` to `/romm/library`, then re-scan.

See [Folder Structure](../getting-started/folder-structure.md) and [Scanning Troubleshooting](../troubleshooting/scanning.md) for the full layout and common mount mistakes.

## Why is my metadata wrong or incomplete?

Metadata isn't owned, only pulled from third parties like IGDB and ScreenScraper. If a field is missing or wrong, the fix has to happen upstream on the provider's site. Cross-check against another provider if one is consistently off for your library.

## Why am I getting a "Configuration file not Mounted!" error?

A `config.yml` is read from `/config` at startup. If the mount/file is missing or unreadable, startup bails with this error (see [Configuration File](../reference/configuration-file.md) for the schema and an example you can drop in).

## Can I play PS3 or newer consoles in the browser?

**No.** In-browser emulation handles 4th-gen and earlier systems well. Saturn, PS1, and N64 are hit-or-miss. PSP and newer are mostly unplayable. Browser play is a bonus, as this is a library manager first, and standalone emulators remain the right tool for modern systems (see [Supported Platforms](../platforms/supported-platforms.md) for the current list).

## Why is browser emulation laggy or not loading?

A few common causes:

- **Browser**: use a Chromium-based browser (Chrome, Edge, Brave). Firefox and Safari might run EmulatorJS poorly.
- **HTTPS**: PSP and DOS cores require the site served over `https://`. Accessing by IP won't work, so you need a [Reverse Proxy](../install/reverse-proxy.md) with TLS.
- **Hardware**: EmulatorJS runs entirely in the browser, so CPU-heavy cores need a capable (modern) browser.

Full troubleshooting steps can be found in [In-Browser Play](../troubleshooting/in-browser-play.md).

## Can I share my library with friends?

Add them as users via the invite flow, then either:

- Expose your instance publicly behind a [Reverse Proxy](../install/reverse-proxy.md) with TLS.
- Keep it private and share access over a VPN or Tailscale.

See [Invitations & Registration](../administration/invitations-and-registration.md).

## Can guests browse without an account?

Absolutely, just set `KIOSK_MODE=true` in your environment variables and anonymous visitors get read-only access (see [Authentication → Kiosk mode](../administration/authentication.md#kiosk-mode)).

## How do I back up?

`mysqldump` the DB + rsync the `/romm/assets` and `/romm/config` volumes nightly. Full procedure and test-restore protocol in [Backup & Restore](../install/backup-and-restore.md).

## Can I use RomM without the internet?

You need internet for:

- First-time scan with metadata providers (they're online APIs)
- Pulling the Docker image on install or upgrade
- OIDC login (if you use a cloud IdP)

After the initial setup, browsing and playing can work offline. In-browser play downloads the emulator bundle on first launch, then caches it.

## Why is scan X slow?

Several possibilities, in rough order of likelihood:

1. Hashing large files on spinning disks.
2. Metadata providers rate-limiting (mostly ScreenScraper).
3. Many files on a network mount with high latency.

[Scanning Troubleshooting → Hash calculations are slow](../troubleshooting/scanning.md#hash-calculations-are-slow).

## When will [feature X] be added?

We don't give ETAs on individual features. Open (or upvote) an issue at [rommapp/romm](https://github.com/rommapp/romm/issues) to make the interest visible.

## I found a bug, or I need help

For bugs, open an issue at [rommapp/romm](https://github.com/rommapp/romm/issues). For questions, ask in `#romm-support` on [Discord](https://discord.gg/romm). Either way, include:

- RomM version
- Deployment (Docker Compose/Unraid/K8s/etc.)
- Your `docker-compose.yml` with credentials and API keys redacted
- Container logs (`docker logs romm`)
- Exact reproduction steps

## Who runs RomM?

A small team of maintainers plus a chunk of active community contributors. Support the project via [Open Collective](https://opencollective.com/romm) if you'd like!

## Where's can I find you?

- **Discord**: [discord.gg/romm](https://discord.gg/romm)
- **GitHub**: [rommapp/romm](https://github.com/rommapp/romm)
- **Website**: [romm.app](https://romm.app/)
- **Demo**: [demo.romm.app](https://demo.romm.app/)

## See also

- [Glossary](../reference/glossary.md) if the vocabulary is new
- [Troubleshooting](../troubleshooting/index.md) if something's broken

---

### About/License

---
title: License
description: How RomM is licensed, and what that means for you.
---

# License

## Core app: AGPLv3

The main [RomM application](https://github.com/rommapp/romm) is licensed under the [GNU Affero General Public License v3.0](https://choosealicense.com/licenses/AGPLv3/). In short, AGPLv3 says:

- **You can** use RomM privately, commercially, or at any scale.
- **You can** modify the source code however you want.
- **You must** make your modifications available under AGPLv3 if you distribute them _or_ run them as a network-accessible service for others.
- **You must** preserve copyright and license notices.

If you host a modified RomM and other people use it over the network, you owe them the source. This prevents the "hosted SaaS fork without upstream contributions" failure mode that's common with plain GPL. For most self-hosters this has zero practical effect, since you're running an unmodified version for yourself and the license doesn't constrain you. For companies thinking about shipping a modified RomM commercially, understand the AGPL obligations first.

Full license text: [rommapp/romm/blob/master/LICENSE](https://github.com/rommapp/romm/blob/master/LICENSE).

## Companion apps: varies

The RomM umbrella hosts several projects under different licenses:

| Project                                                               | License |
| --------------------------------------------------------------------- | ------- |
| [rommapp/romm](https://github.com/rommapp/romm)                       | AGPLv3  |
| [rommapp/argosy-launcher](https://github.com/rommapp/argosy-launcher) | AGPLv3  |
| [rommapp/grout](https://github.com/rommapp/grout)                     | MIT     |
| [rommapp/playnite-plugin](https://github.com/rommapp/playnite-plugin) | AGPLv3  |
| [rommapp/docs](https://github.com/rommapp/docs) (what you're reading) | CC0     |

Companion repos use more permissive licenses AGPLv3 or MIT because they're smaller, more-replaceable, and don't host the library. The AGPL network-service clause doesn't offer the same protection benefits there.

## Third-party components

Several third-party components ship with their own licenses: [EmulatorJS](https://emulatorjs.org/), [Ruffle](https://ruffle.rs/), Vue, FastAPI, and a long list of smaller dependencies. Their licenses apply to their respective code, and none of them override AGPLv3 on the RomM code itself. View the full list via `uv tree` in the backend and `npm ls` in the frontend. Redistribution respects each upstream's terms.

## FAQ

### Can I use RomM at work/for my company's gaming night?

Yes. AGPL doesn't restrict private or commercial use.

### Can I fork RomM and relicense my fork?

No. AGPL is a strong copyleft, so forks remain AGPL, and while you can add your own changes under AGPL you can't relicense the original code.

### Can I charge money for RomM-as-a-service?

In the spirit of the project, we'd prefer if you didn't charge for access to your instance. That being said, it is permitted under our license, but you owe your users the source, so you can't run a modified closed-source hosted RomM for paying customers. We also ask that you make a donation to the project if you do run a paid service, as it helps us cover our costs.

### Can I sell ROMs through RomM?

No, as the sale of ROMs is not permitted in most jurisdictions.

### Is there a commercial/dual-license option?

Please reach out to us if you're interested in commercial licensing. We may be open to dual-licensing arrangements for certain use cases!

## See also

- [Credits](credits.md)
- [AGPLv3 overview](https://choosealicense.com/licenses/agpl-3.0/)
- Full license text: [LICENSE](https://github.com/rommapp/romm/blob/master/LICENSE)

---

### Administration/Oidc/Authelia

---
title: OIDC with Authelia
description: Wire up SSO to Authelia
---

# OIDC with Authelia

[Authelia](https://www.authelia.com/) is a lightweight open-source authentication and authorisation server with two-factor auth and SSO. Before starting, read the [OIDC Setup overview](index.md), as it covers the RomM-side settings common to every provider.

## 1. Prerequisites

Authelia installed and running, with its OIDC provider enabled:

- [Authelia getting started](https://www.authelia.com/integration/prologue/get-started/)
- [OIDC provider configuration](https://www.authelia.com/configuration/identity-providers/openid-connect/provider/)

## 2. Add a claims policy

In Authelia's `configuration.yml` under `identity_providers.oidc.claims_policies`, add a policy that emits the claims RomM needs (name it whatever you like):

```yaml
identity_providers:
    oidc:
        claims_policies:
            with_email:
                id_token:
                    - email
                    - email_verified
                    - groups
                    - alt_emails
                    - preferred_username
                    - name
```

Background on why this is needed: [Authelia claims parameter restoration](https://www.authelia.com/integration/openid-connect/openid-connect-1.0-claims/#restore-functionality-prior-to-claims-parameter).

## 3. Register the RomM client

Under `identity_providers.oidc.clients`, add:

```yaml
identity_providers:
    oidc:
        clients:
            - client_id: "<random>" # see note below
              client_name: "RomM"
              client_secret: "$pbkdf2-sha512$<random>" # see note below
              public: false
              authorization_policy: "two_factor" # or one_factor
              grant_types:
                  - authorization_code
              redirect_uris:
                  - "https://demo.romm.app/api/oauth/openid"
              claims_policy: "with_email" # must match the policy name above
              scopes:
                  - openid
                  - email
                  - profile
                  - groups
              userinfo_signed_response_alg: "none"
              token_endpoint_auth_method: "client_secret_basic"
```

To generate IDs and secrets, see [Authelia's FAQ](https://www.authelia.com/integration/openid-connect/frequently-asked-questions/#how-do-i-generate-a-client-identifier-or-client-secret). The full client schema is available in the [Authelia clients reference](https://www.authelia.com/configuration/identity-providers/openid-connect/clients/).

## 4. Configure RomM

In the `romm` service environment:

```yaml
environment:
    - OIDC_ENABLED=true
    - OIDC_PROVIDER=authelia
    - OIDC_CLIENT_ID=<the client_id you picked>
    - OIDC_CLIENT_SECRET=<the plaintext client secret>
    - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid
    - OIDC_SERVER_APPLICATION_URL=https://auth.example.com
    - ROMM_BASE_URL=https://demo.romm.app
```

`OIDC_REDIRECT_URI` must match what you put in `redirect_uris` exactly (scheme, host, path, no trailing slash). For role mapping from Authelia groups, see [OIDC Setup → Role mapping](index.md#role-mapping).

## 5. Set your email

In RomM → **Profile** → set your email to exactly the same address Authelia has for you. RomM matches OIDC users to existing accounts by email.



## 6. Test

Restart, navigate to `/login` and click the **Login with OIDC** button. You're redirected to Authelia → authenticate → bounced back and signed in!



If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).

---

### Administration/Oidc/Authentik

---
title: OIDC with Authentik
description: Wire up SSO to Authentik
---

# OIDC with Authentik

[Authentik](https://goauthentik.io/) is a full-featured open-source IdP with MFA, flows, and a sizeable audit/admin surface. Before starting, read the [OIDC Setup overview](index.md), as it covers the RomM-side settings common to every provider.

## 1. Prerequisites

Authentik installed and running via their [install guide](https://docs.goauthentik.io/docs/install-config/install/docker-compose).

Log in as admin and open **Admin Interface**.



## 2. Create a property mapping (Authentik 2025.10+)


!!! important "Authentik 2025.10 breaking change"
    In version 2025.10, Authentik changed the default of `email_verified` from `true` to `false`. A verified email is required, so without this property mapping, authentication silently fails.

In **Customization → Property Mappings → Create → Scope Mapping**:

- **Name**: `RomM Email Verification`
- **Scope name**: `email`
- **Expression**:

```py
return {
    "email": user.email,
    "email_verified": True,
}
```



Click **Create**. Upstream reference: [Authentik scope mappings](https://version-2025-10.goauthentik.io/add-secure-apps/providers/property-mappings/#scope-mappings-with-oauth2).

## 3. Create a provider

**Admin → Providers → Create**.



Choose **OAuth2/OpenID Provider**.



Configure:

- **Name**: `RomM OIDC Provider`
- **Authorization flow**: implicit consent
- **Redirect URIs**: `https://demo.romm.app/api/oauth/openid`
- **Scopes**: Under "Advanced protocol settings", move the property mapping you created above from "Available Scopes" to "Selected Scopes". You'll also need to make sure any existing mappings of `email` or `email_verified` are disabled. Authentik has an `email` mapping by default, so make sure to check for this and remove it if it's present.

Copy the generated **Client ID** and **Client Secret**. You'll use them as `OIDC_CLIENT_ID`/`OIDC_CLIENT_SECRET` on the app side.



Click **Create**.

## 4. Register the application

**Admin → Applications → Create**.



- **Name**: `RomM`
- **Slug**: `romm`
- **Provider**: the `RomM OIDC Provider` you just made



Click **Create**.

## 5. Configure

```yaml
environment:
    - OIDC_ENABLED=true
    - OIDC_PROVIDER=authentik
    - OIDC_CLIENT_ID=<from Authentik>
    - OIDC_CLIENT_SECRET=<from Authentik>
    - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid
    - OIDC_SERVER_APPLICATION_URL=https://auth.example.com/application/o/romm
    - ROMM_BASE_URL=https://demo.romm.app
```

Note that `OIDC_SERVER_APPLICATION_URL` points at the per-application URL (`/application/o/<slug>`), not the Authentik root.

For role mapping from Authentik groups, see [OIDC Setup → Role mapping](index.md#role-mapping).

## 6. Set your email

In **Profile** → set your email to exactly the same address Authentik has for you.



## 7. Test

Restart, navigate to `/login` and click the **Login with OIDC** button. You're redirected to Authentik → authenticate → bounced back and signed in!



If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).

---

### Administration/Oidc/Index

---
title: OIDC Setup
description: Wire up to an OpenID Connect provider for SSO and centralised user management
---

# OIDC Setup

OpenID Connect (OIDC) lets users sign in through an external identity provider: Authelia, Authentik, Keycloak, PocketID, Zitadel, Okta, Auth0, VoidAuth, or anything standards-compliant. Single sign-on across your homelab, no app-specific password to manage, centralised MFA, and map OIDC groups/claims to roles.


!!! note "OIDC is optional"
    The local user system works fine without OIDC. Enable OIDC when you already run an IdP and want auth to follow suit, or when you want to unify user management across multiple apps.

## How it works

1. User clicks the OIDC login button on `/login`.
2. They're redirected to your provider.
3. They authenticate (password, passkey, MFA, whatever your provider enforces).
4. Provider redirects back to `{ROMM_BASE_URL}/api/oauth/openid` with an authorisation code.
5. The code is exchanged for an ID token, the user's email and role claims are read, and either a matching local user is created on the fly (unless you've [turned off registration](#auto-provisioning)), or an existing one is logged in.

## Provider guides

Pick your provider and follow the step-by-step instructions. They all end with the same set of app-side env vars. The guides just differ on how to register the app and where to find the client ID/secret.

- [Authelia](authelia.md)
- [Authentik](authentik.md)
- [Keycloak](keycloak.md)
- [PocketID](pocketid.md)
- [Zitadel](zitadel.md)
- [VoidAuth](voidauth.md)

Not listed? Most standards-compliant OIDC providers work: Okta, Auth0, Google Workspace, Microsoft Entra, etc. Use one of the above as a template and consult your provider's docs for the registration side.

## Minimum config

Whichever provider you pick, set these in the `romm` service's environment:

```yaml
environment:
    - OIDC_ENABLED=true
    - OIDC_PROVIDER=<authelia|authentik|keycloak|pocket-id|zitadel|voidauth|generic>
    - OIDC_CLIENT_ID=<from your provider>
    - OIDC_CLIENT_SECRET=<from your provider>
    - OIDC_SERVER_APPLICATION_URL=https://auth.example.com
    - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid
    - ROMM_BASE_URL=https://demo.romm.app # must match your reverse-proxy URL
```

`OIDC_REDIRECT_URI` must exactly match what you register at the provider (same scheme, host, path, no trailing slash).

## Auto-provisioning

By default, the first successful OIDC login for an email that has no matching account **creates** a local account automatically. To require accounts to exist beforehand (so only pre-provisioned users can sign in via OIDC), turn registration off:

```yaml
environment:
    - OIDC_ALLOW_REGISTRATION=false # default: true
```

With it disabled, an unknown user is rejected at login instead of getting a fresh account. New accounts land in the [default permission group](../users-and-roles.md#permission-groups) unless a role claim maps them to Admin.

## Role mapping

RomM has only two roles: **User** and **Admin** (see [Users & Roles](../users-and-roles.md#roles)). New OIDC users are provisioned as **Users**. To let your IdP promote someone to **Admin** based on group membership, set:

```yaml
environment:
    - OIDC_CLAIM_ROLES=groups # which claim to read
    - OIDC_ROLE_ADMIN=romm-admin,platform-admins # group values → Admin
```

On every login, the claim named by `OIDC_CLAIM_ROLES` is read (often `groups`, sometimes `realm_access.roles` on Keycloak, check your provider's token output). If a value matches `OIDC_ROLE_ADMIN`, the user becomes an Admin.

Roles are re-evaluated on **every login**, so demoting someone on the IdP side takes effect the next time they sign in.



!!! warning "Once `OIDC_CLAIM_ROLES` is set, users must match a mapped group"
    As soon as `OIDC_CLAIM_ROLES` is configured, RomM expects every user to match at least one mapped role group. A user whose claim matches **none** of the configured groups is rejected at login with:

    ```json
    {"detail":"User has not been granted any roles for this application."}
    ```

    To let non-admin users in, map their group to the **User** role with `OIDC_ROLE_VIEWER` (or `OIDC_ROLE_EDITOR`):

    ```yaml
    environment:
        - OIDC_CLAIM_ROLES=groups
        - OIDC_ROLE_ADMIN=romm-admin,platform-admins # → Admin
        - OIDC_ROLE_VIEWER=platform-users # non-admins → User (grants access)
    ```

    `OIDC_ROLE_VIEWER` and `OIDC_ROLE_EDITOR` no longer map to distinct roles — matching users all resolve to **User** — but they're still how you grant those users access when role claims are enabled. Point them at a group that all your non-admin users belong to. Use [permission groups](../users-and-roles.md#permission-groups) for finer-grained access; only `OIDC_ROLE_ADMIN` changes the role.

    If you *don't* set `OIDC_CLAIM_ROLES` at all, role mapping is skipped entirely and everyone is provisioned as a **User** in the default permission group.



## Autologin

To bypass the login page entirely and redirect straight to the IdP:

```yaml
environment:
    - OIDC_AUTOLOGIN=true
```

Useful when you want this to feel like a native part of your SSO stack. Combine with `DISABLE_USERPASS_LOGIN=true` to lock out local accounts entirely.


!!! warning "Keep one local admin"
    Don't set `DISABLE_USERPASS_LOGIN=true` without first confirming an admin account exists on the IdP side and can log in. If OIDC breaks and you've disabled local login, you're locked out until you fix the container env.

## RP-Initiated Logout

When set, hitting "Sign out" in RomM also signs the user out at the IdP:

```yaml
environment:
    - OIDC_RP_INITIATED_LOGOUT=true
    - OIDC_END_SESSION_ENDPOINT=https://auth.example.com/application/o/end-session/
```

The endpoint URL is provider-specific, check the per-provider guides or your IdP's docs.

## Username source

By default the local part of the email (the bit before `@`) becomes the username, but you can override it with:

```yaml
environment:
    - OIDC_USERNAME_ATTRIBUTE=preferred_username
```

## Important notes

- **Email must match** between OIDC and any existing local account, otherwise OIDC creates a new account alongside the old one.
- **HTTPS is required** in production, as OIDC will refuse to redirect to a plain-HTTP `ROMM_BASE_URL`.
- Large drift between the RomM host and IdP will lead to **clock skew** and cause ID-token validation to fail.

## Troubleshooting

Common failures and fixes live in [Authentication Troubleshooting](../../troubleshooting/authentication.md). Two of the usual suspects:

- `redirect_uri_mismatch`: `OIDC_REDIRECT_URI` differs from what's registered at the provider. Even a trailing slash can matter!
- User created but not made Admin: check `OIDC_CLAIM_ROLES` points at a claim that actually exists in the token, and that the group values match `OIDC_ROLE_ADMIN` exactly (case-sensitive).

---

### Administration/Oidc/Keycloak

---
title: OIDC with Keycloak
description: Wire up SSO to Keycloak
---

# OIDC with Keycloak

[Keycloak](https://www.keycloak.org/) is the heavyweight open-source IAM standard. Before starting, read the [OIDC Setup overview](index.md), as it covers the RomM-side settings common to every provider.

## 1. Prerequisites

Keycloak installed and running via their [getting started guide](https://www.keycloak.org/getting-started).

Log into the **Admin Console** and either create a new realm for the app or reuse an existing one.

## 2. Add a client

In the Admin Console, select your realm → **Clients** → **Create client**.

1. **Client type**: `OpenID Connect`.
2. **Client ID**: `romm` (or something unique).
3. Click **Next**.
4. On the capability page:
    - Enable **Client authentication**
    - Leave only **Standard flow** enabled
    - Click **Next**
5. Set URLs:
    - **Root URL**: `https://demo.romm.app`
    - **Valid Redirect URIs**: `https://demo.romm.app/api/oauth/openid`
    - **Web origins**: `https://demo.romm.app`
6. Save, then head to the **Credentials** tab and copy the **Client Secret**.

## 3. Configure

```yaml
environment:
    - OIDC_ENABLED=true
    - OIDC_PROVIDER=keycloak
    - OIDC_CLIENT_ID=romm
    - OIDC_CLIENT_SECRET=<from Keycloak Credentials tab>
    - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid
    - OIDC_SERVER_APPLICATION_URL=https://keycloak.example.com/realms/<realm-name>
    - ROMM_BASE_URL=https://demo.romm.app
```

`OIDC_SERVER_APPLICATION_URL` must include the realm (`.../realms/<realm-name>`), not just the Keycloak root.

## 4. Set email + verify in Keycloak

In **Profile** → set your email to the same address Keycloak has for you.

On the Keycloak side, go to **Admin Console → Users** and mark each user's email as **verified**. Users with unverified emails will be rejected on login.

## 5. Test

Restart, navigate to `/login` and click the **Login with OIDC** button. You're redirected to Keycloak → authenticate → bounced back and signed in!

If a local user already exists with a matching email, they're signed into that account. Otherwise a new account is created as a regular User in the default permission group.

If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).

## 6. (Optional) Disable local password logins

Force users through Keycloak:

```yaml
environment:
    - DISABLE_USERPASS_LOGIN=true
```


!!! warning
    Before flipping this, confirm at least one Admin account can sign in via OIDC, otherwise a broken OIDC flow locks you out.

## 7. (Optional) Role mapping

By default, new OIDC users come in as regular Users. To let Keycloak promote someone to **Admin** based on a role/group:

```yaml
environment:
    - OIDC_CLAIM_ROLES=groups # or realm_access.roles, depending on your token
    - OIDC_ROLE_ADMIN=romm-admin
```

Configure Keycloak's client to include the role/group claim in the ID token (usually via a **Group Membership** or **Realm Role** client scope mapper). Values in the claim are compared against `OIDC_ROLE_ADMIN` on every login, so demoting in Keycloak takes effect on the user's next sign-in.

See [OIDC Setup → Role mapping](index.md#role-mapping) for the generic version.

---

### Administration/Oidc/Pocketid

---
title: OIDC with PocketID
description: Wire up SSO to PocketID
---

# OIDC with PocketID

[PocketID](https://github.com/stonith404/pocket-id) is a minimalist OIDC provider that **only** supports passkey authentication, with no passwords. Before starting, read the [OIDC Setup overview](index.md), as it covers the RomM-side settings common to every provider.

## 1. Prerequisites

PocketID installed, running, and your admin passkey already registered via their [PocketID setup guide](https://github.com/stonith404/pocket-id#setup).

## 2. Add the client

In PocketID admin:

1. **Application Configuration**: make sure **Emails Verified** is ticked as we now require verified emails.
2. Go to **OIDC Client** → **Add OIDC Client**.
3. Fill in:
    - **Name**: `RomM`
    - **Callback URLs**: `https://demo.romm.app/api/oauth/openid`
4. **Save**. Stay on this page as the client secret only displays **once**.
5. Copy both the Client ID and Client Secret now.

## 3. Configure RomM

```yaml
environment:
    - OIDC_ENABLED=true
    - OIDC_PROVIDER=pocket-id
    - OIDC_CLIENT_ID=<from PocketID>
    - OIDC_CLIENT_SECRET=<from PocketID>
    - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid
    - OIDC_SERVER_APPLICATION_URL=https://id.example.com
    - ROMM_BASE_URL=https://demo.romm.app
```

`OIDC_SERVER_APPLICATION_URL` is the root URL of your PocketID instance.

## 4. Set your email

RomM → **Profile** → set your email to exactly the same address PocketID has for you.

## 5. Test

Restart, navigate to `/login` and click the **Login with OIDC** button. You're redirected to PocketID → authenticate → bounced back and signed in!



If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).

---

### Administration/Oidc/Voidauth

---
title: OIDC with VoidAuth
description: Wire up SSO to VoidAuth
---

# OIDC with VoidAuth

[VoidAuth](https://voidauth.app/) is an open-source SSO authentication and user management provider that stands guard in front of your self-hosted application. Before starting, read the [OIDC Setup overview](index.md), as it covers the RomM-side settings common to every provider.

## 1. Prerequisites

VoidAuth installed and running via their [self-hosted deployment docs](https://voidauth.app/#/?id=quick-start). We'll use the `APP_URL` from the example `compose.yml` in those docs as `https://auth.example.com`.
Your RomM instance will be referenced as `https://demo.romm.app`.

## 2. Create a new app

Log in as an admin in the VoidAuth web interface. Create a new OIDC app (e.g. `RomM`).

- **Name**: `RomM`
- **Home Page URL**: `https://demo.romm.app`
- **Logo URL**: `https://docs.romm.app/resources/romm/isotipo.png`
- **Group**: You could add a group that the user must belong to get access to your RomM instance. If left empty, any user created in your VoidAuth instance will be allowed.
- **Skip Consent** and **MFA Required**: These options can be enabled or left disabled as you prefer.
- **Client ID**: Generate an ID using the button.
- **Auth Method**: `Client Secret Basic`
- **Client Secret**: Generate a secret using the button.
- **Redirect URLs**: add `https://demo.romm.app/api/oauth/openid`
- **Response Types**: check `code`
- **Grant Types**: check `authorization_code` and `refresh_token`
- **Post Logout URL**: `https://demo.romm.app/`

Don't forget to click the `Create` button to validate your app.

## 3. Configure

```yaml
environment:
    - OIDC_ENABLED=true
    - OIDC_PROVIDER=voidauth
    - OIDC_CLIENT_ID=<from VoidAuth>
    - OIDC_CLIENT_SECRET=<from VoidAuth>
    - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid
    - OIDC_SERVER_APPLICATION_URL=https://auth.example.com
    - OIDC_SERVER_METADATA_URL=https://auth.example.com/oidc/.well-known/openid-configuration
    - ROMM_BASE_URL=https://demo.romm.app
```

VoidAuth's OIDC discovery URL can be found at the top of your OIDC App page, by clicking on OIDC Endpoints.

For role mapping from VoidAuth, see [OIDC Setup → Role mapping](index.md#role-mapping).

## 4. Test

Restart, navigate to `/login` and click the **Login with VoidAuth** button. You're redirected to VoidAuth → authenticate → bounced back and signed in!

If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).

---

### Administration/Oidc/Zitadel

---
title: OIDC with Zitadel
description: Wire up SSO to Zitadel
---

# OIDC with Zitadel

[Zitadel](https://zitadel.com/) is an enterprise-grade open-source IAM platform supporting OAuth2, OIDC, SAML, and passwordless. Before starting, read the [OIDC Setup overview](index.md), as it covers the RomM-side settings common to every provider.

## 1. Prerequisites

Zitadel installed and running via their [self-hosted deployment docs](https://zitadel.com/docs/self-hosting/deploy/overview). Change the default organization password before you go further!

## 2. Create a project

Create a new project (e.g. `RomM`). This holds the client and its auth settings. On the **General** tab, **Check authorization on Authentication** is recommended. If turned off, anyone who can register in Zitadel can sign into RomM (as a regular User). Turn this on if Zitadel registration is open.

### 2.5 (Optional) Grant users to the project

If you enabled **Check authorization on Authentication**:

1. **Authorization** tab → **New**.
2. Select user(s) → **Continue**.
3. "No role has been created yet" is fine, just **Save**.
4. The user appears in the authorization list with no roles.

## 3. Create the application

On the project's **General** tab, under **Applications**, click **New**. Tick **I'm a pro. Skip this wizard** for the fast path.

- **Name**: `RomM`
- **Application Type**: `Web`
- **Grant Types**: `Authorization Code`
- **Response Types**: `Code`
- **Authentication Method**: `Basic`
- **Redirect URIs**: `https://demo.romm.app/api/oauth/openid`
- **Post Logout URIs**: `https://demo.romm.app/`

Click **Create**. The **client secret is shown once**, copy it now!

## 4. Enable claims in the ID Token

Without this, RomM throws "Email is missing from token" on login. Open the application's **Token Settings** tab → tick **User Info inside ID Token** → **Save**.

## 5. Configure

```yaml
environment:
    - OIDC_ENABLED=true
    - OIDC_PROVIDER=zitadel
    - OIDC_CLIENT_ID=<from Zitadel>
    - OIDC_CLIENT_SECRET=<from Zitadel>
    - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid
    - OIDC_SERVER_APPLICATION_URL=https://zitadel.example.com
    - ROMM_BASE_URL=https://demo.romm.app
```

Zitadel's OIDC discovery URL is at `<OIDC_SERVER_APPLICATION_URL>/.well-known/openid-configuration`, which is handy for debugging.

For role mapping from Zitadel, see [OIDC Setup → Role mapping](index.md#role-mapping).

## 6. Set email + Zitadel

In RomM → **Profile** → set your email to exactly the same address your Zitadel user has.

## 7. Test

Restart, navigate to `/login` and click the **Login with OIDC** button. You're redirected to Zitadel → authenticate → bounced back and signed in!

If it doesn't work, head to [Authentication Troubleshooting](../../troubleshooting/authentication.md).

---

### Administration/Authentication

---
title: Authentication
description: Configure how users sign in.
---

# Authentication

This page is the **operator-side** authentication reference, the knobs you turn on the server to control how people sign in. The **client-side** reference ("how do I actually authenticate an API call?") is in [API Authentication](../developers/api-authentication.md).

Authentication flows RomM supports:

- **Username + password** (default): local account, bcrypt-hashed, stored in the DB
- **OIDC**: single sign-on via an external IdP
- **Client API Tokens**: long-lived per-user tokens for companion apps and scripts
- **Device pairing**: short codes for bootstrapping a token onto a handheld
- **Kiosk mode**: unauthenticated read-only access, handy for public demos

## Session config

Sessions are cookie-based and stored in Redis. Relevant env vars:

| Variable                             | Default        | What it controls                                                                                                                                                                                    |
| ------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ROMM_AUTH_SECRET_KEY`               | _(required)_   | HS256 signing key for session tokens and JWTs. Generate with `openssl rand -hex 32`. **Never rotate this casually**, because it invalidates every active session and every outstanding invite link. |
| `ROMM_AUTH_SECRET_KEY_FILE`          |                | Read the secret from a file (e.g. via Docker secrets) instead of an env var.                                                                                                                        |
| `SESSION_MAX_AGE_SECONDS`            | 86400 (24 h)   | How long a session cookie lives before the user has to sign in again.                                                                                                                               |
| `OAUTH_ACCESS_TOKEN_EXPIRE_SECONDS`  | 900 (15 min)   | Short-lived OAuth2 access token TTL.                                                                                                                                                                |
| `OAUTH_REFRESH_TOKEN_EXPIRE_SECONDS` | 2592000 (30 d) | Refresh token TTL for OAuth2.                                                                                                                                                                       |
| `DISABLE_CSRF_PROTECTION`            | `false`        | Disable CSRF middleware. Only do this behind a trusted reverse proxy that strips unwanted cross-origin traffic.                                                                                     |

## Local (username + password)

Local accounts are created via [invitations, registration, admin setup, or the Setup Wizard](invitations-and-registration.md), and passwords are bcrypt-hashed.

**Disable local password login entirely** (force OIDC-only):

```yaml
environment:
    - DISABLE_USERPASS_LOGIN=true
```


!!! warning "Keep a way in"
    Before setting `DISABLE_USERPASS_LOGIN=true`, confirm that at least one Admin account can sign in via OIDC. If OIDC breaks and you've already disabled local login, your only way in is editing the container env.

### Admin-triggered password reset

Until email-based self-serve reset lands, admins set passwords manually for any user. The next login on that account will use the new password but existing sessions remain valid until they expire.

## OIDC

See [OIDC Setup](oidc/index.md) for the full walkthrough. One-liner config sketch:

```yaml
environment:
    - OIDC_ENABLED=true
    - OIDC_PROVIDER=keycloak
    - OIDC_CLIENT_ID=...
    - OIDC_CLIENT_SECRET=...
    - OIDC_SERVER_APPLICATION_URL=https://auth.example.com
    - OIDC_REDIRECT_URI=https://demo.romm.app/api/oauth/openid
```

When OIDC is configured, an OIDC sign-in option is offered alongside username/password. Set `OIDC_AUTOLOGIN=true` to redirect straight to the IdP without the user having to choose. By default the first login for an unknown email auto-creates an account; set `OIDC_ALLOW_REGISTRATION=false` to allow only pre-provisioned users in (see [OIDC Setup](oidc/index.md) for role mapping and auto-provisioning).

## Client API Tokens

For anything long-lived (a companion app, a cron job, a script) use **Client API Tokens** instead of storing a password. Each token:

- Belongs to a specific user
- Carries a **subset** of that user's scopes (you choose which at creation time)
- Has an optional expiry (no expiry = never expires until manually revoked)
- Can be "paired" to a device via a short code

Each user gets up to 25 active tokens. The API side ("how do I send this thing in a request?") lives in [API Authentication](../developers/api-authentication.md).

## Kiosk mode

Grants unauthenticated, read-only access to nearly every GET endpoint. Anyone reaching the instance can browse but only a logged-in admin can write, scan, upload, or manage users.

```yaml
environment:
    - KIOSK_MODE=true
```

Appropriate for:

- Shared-terminal demos
- Public-facing "display" instances
- `demo.romm.app`

Authenticated users (when you do sign in) will still see the full UI with all actions available to their role and [permission group](users-and-roles.md#permission-groups).

## Download-endpoint auth bypass

```yaml
environment:
    - DISABLE_DOWNLOAD_ENDPOINT_AUTH=true
```

Skips auth on `GET /api/roms/{id}/content/…` and the firmware download endpoint. Exists so third-party apps that can't carry a bearer header (like dumb emulators loading a ROM by URL) can still pull files. **Only enable this when the public internet can't reach RomM directly**, i.e. there's auth or an IP allowlist at the reverse-proxy layer. Otherwise you've just made your library world-downloadable.

## Revoking access

To fully cut a user off, an admin needs to:

1. Revoke all of the user's Client API Tokens.
2. Disable or delete the user account.

Disabling preserves the account row (useful for audit/future re-enable). Deletion removes the user record and personal data, with the caveats covered in [Users & Roles → Editing and deleting users](users-and-roles.md#editing-and-deleting-users).

---

### Administration/Firmware Management

---
title: Firmware Management
description: Upload, associate, and serve BIOS/firmware files for emulation.
---

# Firmware Management

Many emulated platforms require BIOS or firmware to boot, or to reach a certain level of stability. RomM tracks firmware files **per platform**, stores them on disk, and serves them to in-browser players (EmulatorJS/Ruffle) and companion apps that request them.

Firmware is **not** ROM. Keep the two separate:

- `/romm/library/roms/`: game ROMs, homebrew, demos, etc.
- `/romm/library/bios/`: system firmware


!!! important "Legality varies by jurisdiction"
RomM does not ship games or firmware, and the team cannot help you obtain BIOS files. Always check your local laws and the emulator's documentation for guidance on what you can legally use.

## Ingesting firmware

1. Put the file in the right `bios/` folder (see [Folder Structure](../getting-started/folder-structure.md))
2. Run a scan → Firmware is picked up alongside ROMs
3. Navigate to the platform's gallery and click the `CPU` icon in the top left
4. Firmware files will display at the bottom of the page

## Platform-specific firmware

Every emulator has its own requirements: which files it needs, specific hashes, naming conventions. The [Supported Platforms](../platforms/supported-platforms.md) table flags which platforms need firmware for EmulatorJS playback.

Common examples:

| Platform          | Typical firmware file                             | Where to put it |
| ----------------- | ------------------------------------------------- | --------------- |
| PlayStation (PSX) | `scph1001.bin`, `scph5501.bin`, `scph5502.bin`    | `bios/ps/`      |
| Game Boy Advance  | `gba_bios.bin`                                    | `bios/gba/`     |
| Sega CD           | `bios_CD_U.bin`, `bios_CD_E.bin`, `bios_CD_J.bin` | `bios/segacd/`  |
| Saturn            | `saturn_bios.bin`, `mpr-17933.bin`                | `bios/saturn/`  |
| Nintendo DS       | `firmware.bin`, `bios9.bin`, `bios7.bin`          | `bios/nds/`     |

File naming matters as emulators look for specific filenames. Double-check against the emulator core's documentation if something won't boot.

## Integration with companion apps

Handheld syncers (Grout, Argosy, DeckRommSync) can pull firmware alongside ROMs. They use the same Client API Token auth as for ROMs, so scope the token to include `firmware.read`.

## Backups

Firmware files are user-owned data, so back them up! If you're backing up the `/romm/library` volume, firmware is already covered (see [Backup & Restore](../install/backup-and-restore.md)).

---

### Administration/Index

---
title: Administration
description: Running RomM for yourself and others.
---

# Administration

Administration is everything you do **as the operator** of a RomM instance: managing accounts, controlling access, configuring metadata sources, scheduling scans, watching the library for changes, monitoring the server, and keeping data safe.

The end-user equivalent (how to actually play the games, build collections, upload saves) lives in [Using RomM](../using/index.md).

## Where things live

### Users & access

- **[Users & Roles](users-and-roles.md)**: roles, permission groups, per-user overrides, and hidden entities
- **[Invitations & Registration](invitations-and-registration.md)**: invite links, public signup, first-user setup
- **[Authentication](authentication.md)**: session config, password reset, Client API Tokens for devices
- **[OIDC Setup](oidc/index.md)**: Authelia, Authentik, Keycloak, PocketID, Zitadel, VoidAuth, SSO + role mapping

### Content & library

- **[Metadata Providers](../getting-started/metadata-providers.md)**: all providers, credentials, priority ordering
- **[Scanning & Watcher](scanning-and-watcher.md)**: how scans work, scan modes, filesystem watcher
- **[Firmware Management](firmware-management.md)**: BIOS/firmware uploads for emulation

### Operations

- **[Scheduled Tasks](scheduled-tasks.md)**: what runs in the background and how to tune it
- **[Server Stats](server-stats.md)**: the stats page and what its numbers mean
- **[Observability](observability.md)**: logs, Sentry, OpenTelemetry, `/heartbeat`

### Configuration

- **[Environment Variables](../reference/environment-variables.md)**: every env var, grouped by area
- **[Configuration File](../reference/configuration-file.md)**: the `config.yml` schema

### Keeping data safe

- **[Backup & Restore](../install/backup-and-restore.md)**: routine backups, restore drill, host migration

---

### Administration/Invitations And Registration

---
title: Invitations & Registration
description: Inviting users, the first-user flow, and role assignment.
---

# Invitations & Registration

There are three ways a new account ends up on a RomM instance:

1. **First-admin setup**: the person who completes the Setup Wizard.
2. **Invite link**: an admin generates a one-shot link carrying a pre-assigned role.
3. **OIDC auto-provisioning**: first login through your IdP creates a matching account, unless you set `OIDC_ALLOW_REGISTRATION=false` (covered in [OIDC Setup](oidc/index.md)).

## First-admin setup

When a fresh RomM container starts against an empty database, hitting any page redirects to the **Setup Wizard**. The wizard collects a username, email, and password. The resulting account is **always an Admin**, regardless of any env var.

To skip the wizard (e.g. when provisioning via automation and you'll create users through the API), set:

```yaml
environment:
    - DISABLE_SETUP_WIZARD=true
```

You'll then need to create the first admin via the API or by injecting a database row at deploy time, because the UI won't offer a setup flow.

## Invite links

The recommended way to add users, because it avoids you ever touching their password.

1. **Administration → Users → Invite.** Pick a role (User or Admin).
2. RomM generates a single-use URL → copy it and send it to the invitee.
3. When they open it, they pick their own username and password.
4. RomM creates the account with the role you chose and logs them straight in.

Invite tokens are **single-use** and **time-limited**. Defaults:

| Setting | Default    | Env var                       |
| ------- | ---------- | ----------------------------- |
| Expiry  | 600 (10 m) | `INVITE_TOKEN_EXPIRY_SECONDS` |

Expired links return a clear error on the `/register` page. Generate a new one from the Users panel.

## Role assignment at sign-up

| Sign-up method          | Role assigned                                                                    |
| ----------------------- | -------------------------------------------------------------------------------- |
| First-user Setup Wizard | Admin (always)                                                                   |
| Invite link             | Whatever role the admin picked when generating the link                          |
| OIDC first login        | User (in the default permission group), or Admin if mapped via `OIDC_ROLE_ADMIN` |

Changing a user's role afterwards is a normal admin action (see [Users & Roles](users-and-roles.md)).

## Password reset

Admins can reset passwords manually in **Administration → Users → Edit → New password**. A temporary password will be printed to the container's logs.

---

### Administration/Observability

---
title: Observability
description: Logs, error tracking and telemetry
---

# Observability

It's often handy to know what's happening under the hood, especially when debugging a scan or task. the observability stack includes:

- **Container logs**: always available, the first stop
- **`/api/heartbeat`** endpoint: health + config summary for uptime monitors
- **Sentry**: opt-in error tracking with stack traces
- **OpenTelemetry**: opt-in distributed tracing + metrics

## Logs

```yaml
environment:
    - LOGLEVEL=INFO # DEBUG | INFO | WARNING | ERROR
    - FORCE_COLOR=0 # 1 to force colour even when not a TTY
    - NO_COLOR=1 # 1 to disable colour entirely
```

`INFO` is the default and the sane choice for production. Drop to `DEBUG` only while debugging a specific issue, because `DEBUG` is chatty.

### Reading logs

Log lines are prefixed with module + timestamp:

```text
INFO:     [RomM][scan_handler][2026-04-18 11:37:40]   Identified as PlayStation 🎮
ERROR:    [RomM][ra_handler][2026-04-18 11:48:55]    Invalid RetroAchievements API key
WARNING:  [RomM][config_manager][2026-04-18 12:01:12] config.yml not found, using defaults
```

Some useful grep commands:

```sh
docker logs romm 2>&1 | grep ERROR
docker logs romm 2>&1 | grep -iE 'auth|oidc|oauth'
docker logs romm 2>&1 | grep -iE 'scan_handler.*Identified'
```

### In-app logs viewer

RomM also tails the server log live in the UI, with a filter by module (scan handler, auth, config manager, etc.), so you can watch a scan or debug an auth issue without shelling into the container. Access is gated on the `logs.read` scope.

To turn it off for everyone (admins included), set:

```yaml
environment:
    - DISABLE_LOGS_VIEWER=true
```

This also disables the `GET /api/logs` endpoint that backs it. The container logs above are unaffected.

## `/api/heartbeat`

A single-request endpoint to fetch health and config information. Works when not logged in, though some fields only appear for authenticated callers.

```http
GET /api/heartbeat
```

Wire this to your uptime monitor. A failure here means that the process is down or the DB/Valkey is unreachable.

```bash
# Basic uptime check
curl -fsS https://demo.romm.app/api/heartbeat > /dev/null \
  && echo "up" \
  || echo "down"
```

Per-metadata provider health:

```http
GET /api/heartbeat/metadata/[igdb/ss/ra/...]
```

Useful when a scan is matching poorly and you want to know whether a provider is down on their side or misconfigured on yours.

## Sentry

Opt-in error tracking:

```yaml
environment:
    - SENTRY_DSN=https://abc123@sentry.example.com/42
```

What's sent:

- Stack traces for unhandled exceptions
- Per-request timing on slow endpoints
- Redacted URL parameters (secrets stripped)

What's not sent: ROM filenames, user credentials, metadata provider API keys. Sensitive parameters are filtered before reporting.

## OpenTelemetry

If you're already using OpenTelemetry with your other apps and want unified observability:

```yaml
environment:
    - OTEL_ENABLED=true
    - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
    - OTEL_SERVICE_NAME=romm
    - OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod
```

Standard [OTEL env vars](https://opentelemetry.io/docs/specs/otel/protocol/exporter/) apply. The app emits:

- **Traces**: HTTP request spans, DB query spans, RQ job spans
- **Metrics**: request counts, durations, queue depth, scan progress
- **Logs**: structured log correlation with trace IDs

Exporters:

- OTLP gRPC (default, port `4317`)
- OTLP HTTP (port `4318`): set `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`.

Send to an OpenTelemetry Collector, then fan out to Tempo/Jaeger/Honeycomb/Datadog/Grafana/whatever you run.

## Task status

Live task state is also exposed programmatically:

```http
GET /api/tasks/status
Authorization: Bearer <token-with-tasks.run>
```

Returns an array of every scheduled/manual/watcher task with current status (`idle`, `queued`, `running`, `failed`) and last run time. Scrape this into your monitoring to alert on "Folder Scan hasn't run in 48 hours", which usually means RQ workers are dead.

## Anti-patterns

- **Don't parse unstructured log lines** for metrics (use OTEL instead)
- **Don't log at DEBUG in production** as the volume is real and scans will drown in it
- **Don't scrape HTML pages for health checks**; HTML changes between versions while the API endpoint is stable

## Minimum recommended stack

- Default `INFO` logs into the container logs → forwarded to Loki/Promtail/whatever you already run
- `/api/heartbeat` hit every 60 seconds from Uptime Kuma/Gatus

---

### Administration/Scanning And Watcher

---
title: Scanning & Watcher
description: Scanning your library, scan modes, and the filesystem watcher
---

# Scanning & Watcher

RomM keeps its catalogue in sync with your filesystem through three mechanisms:

1. **Manual scans** you trigger through the web UI
2. **Scheduled scans** (default: nightly) run by the task runner
3. **The filesystem watcher** reacting to files landing in or leaving your library

All three share the same scan engine and the same set of **scan modes**.

## Scan modes

Every scan picks one mode. Modes differ in what they touch, so use the most-targeted mode that accomplishes what you want.

| Mode              | What it does                                                               | When to use                                                                               |
| ----------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **New Platforms** | Only scans platform folders not already in the DB.                         | After mounting a new ROM set (very fast).                                                 |
| **Quick**         | Skips files that already exist in the DB, with no metadata refresh.        | Default for scheduled runs and the watcher.                                               |
| **Unmatched**     | Re-runs metadata matching against ROMs currently missing external IDs.     | After adding a new metadata provider, or when some titles didn't match on the first scan. |
| **Update**        | Re-fetches metadata for all already-matched ROMs.                          | When metadata providers have meaningfully changed (e.g. IGDB restructured).               |
| **Hashes**        | Recalculates CRC/MD5/SHA1 hashes.                                          | After upgrading from a version that didn't hash or when you suspect file corruption.      |
| **Complete**      | Full rescan, recalculating hashes and re-fetching metadata for everything. | Rarely, since it takes a long time.                                                       |

You can further scope a scan to specific **platforms** and specific **metadata providers**, useful when only one provider has changed (e.g. just enabled Hasheous → Unmatched scan, Hasheous selected, on all platforms).

## Manual scans

A manual scan can be scoped to specific platforms and a chosen subset of metadata providers, and hashing can be skipped (helpful on low-power hosts). A running scan survives browser refreshes, and the log streams over a websocket so multiple users can watch the same scan in progress.

## Scheduled scans

Configured via env vars (full table in [Scheduled Tasks](scheduled-tasks.md)):

| Variable             | Default     | Purpose                                                                                                      |
| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
| `SCAN_INTERVAL_CRON` | `0 0 * * *` | Cron expression for the scheduled library scan. Runs a **Quick** scan by default.                            |
| `SCAN_TIMEOUT`       | `14400`     | Hard cap in seconds: scans that exceed this are killed and logged.                                           |
| `SCAN_WORKERS`       | `1`         | Concurrent worker processes for scanning; leave as auto unless you're tuning.                                |
| `SEVEN_ZIP_TIMEOUT`  | `60`        | Per-archive timeout in seconds for `.7z` extraction during scan; raise if scanning huge compressed ROM sets. |

To disable scheduled scans entirely, either unset the cron or set it to something unreachable (`SCAN_INTERVAL_CRON=0 0 31 2 *`).

## Filesystem watcher

The watcher tails your library folder and schedules scans in response to file events (files added, moved, or deleted). It's off by default, so enable it with:

```yaml
environment:
    - ENABLE_RESCAN_ON_FILESYSTEM_CHANGE=true
    - RESCAN_ON_FILESYSTEM_CHANGE_DELAY=5 # minutes before acting on an event
```

Behaviour:

- Watches `/romm/library` (and everything under it) recursively
- Debounces bursts of events: the delay (default 10 seconds) lets a large `cp` or `rsync` settle before scanning.
- Batches scans intelligently: many events → a single consolidated scan, not one scan per file
- Ignores content modifications and metadata-only changes, caring only about files appearing or disappearing (not `chmod`)
- Skips OS noise (`.DS_Store`, `Thumbs.db`, `.tmp`, etc.)
- If a whole new platform folder appears, switches to a **New Platforms** scan to pick it up cleanly

### When **not** to enable the watcher

- **Slow/high-latency filesystems** (SMB mounts, rclone mounts, anything not local disk): the watcher reacts to every event, flaky mounts generate a lot of them, so use scheduled scans instead.
- **Libraries under active write load from other tools** (e.g. IGIR constantly tagging files): the watcher will re-scan on every change, at best noisy and at worst a scan loop.

### Watcher vs scheduled scan

|                              | Watcher                 | Scheduled scan           |
| ---------------------------- | ----------------------- | ------------------------ |
| Latency                      | Seconds                 | Up to your cron interval |
| CPU cost                     | Only when files change  | Constant cadence         |
| Works over SMB/NFS           | Flakily                 | Reliably                 |
| Catches renames              | Yes                     | Yes                      |
| Survives a container restart | Yes, re-arms on startup | Yes                      |

You can run both, where the watcher handles day-to-day additions, and the scheduled scan is a safety net.

## What gets excluded

Scans respect the `exclude:` tree in [`config.yml`](../reference/configuration-file.md):

```yaml
exclude:
    platforms:
        - steam # skip entire platform folder
    roms:
        single_file:
            extensions: [nfo, txt, bak] # single files with these exts
            names: ["*.sample.*"] # Unix glob patterns
        multi_file:
            names: [extras] # folder names to skip
            parts:
                names: [thumb.png] # files inside multi-file dirs
                extensions: [nfo]
```

Full schema in [Configuration File](../reference/configuration-file.md).

## Region and language preference

Also in `config.yml`:

```yaml
scan:
    priority:
        region: [us, wor, ss, eu, jp]
        language: [en, fr]
```

When a metadata provider returns multiple regional variants (Japanese cover, US cover, European cover…), we pick according to this order, and the same goes for localised titles.

## Metadata source priority

Who wins when two providers disagree is covered in [Metadata Providers](../getting-started/metadata-providers.md#priority-and-conflict-resolution), though the short version is `scan.priority.metadata` and `scan.priority.artwork` in `config.yml`.

## Troubleshooting

Scans that hang, miss files, or match weirdly: [Scanning Troubleshooting](../troubleshooting/scanning.md).

---

### Administration/Scheduled Tasks

---
title: Scheduled Tasks
description: Runs tasks in the background, reschedule and trigger them on demand
---

# Scheduled Tasks

RomM runs background work through **RQ** (Redis Queue). Tasks fall into four categories:

- **Scheduled**: cron-driven, run on their own
- **Watcher**: triggered by filesystem events
- **Manual**: user-triggered from the UI or API
- **Enqueued**: side effects of user actions (a scan on the `/scan` page, a metadata refresh on a ROM edit, etc.)

## The full table

--8<-- "scheduled-tasks.md"

## Configuring cadence

Every scheduled task takes a standard 5-field cron expression:

- `0 3 * * *`: 3 AM daily
- `0 */6 * * *`: every 6 hours, on the hour
- `*/30 * * * *`: every 30 minutes
- `0 2 * * 0`: 2 AM every Sunday

Set the env var and restart the container; the scheduler picks up the new schedule the moment RomM comes back up.

## Enabling a scheduled task

Each task has an `ENABLE_*` environment variable, like `ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA=true` which enables the LaunchBox sync. Check the [env var reference](../reference/environment-variables.md) for the full list. Some tasks are enabled by default, others aren't.

## Triggering a task manually

### From the Administration page

**Administration → Tasks** shows every task with a "Run" button. Admins (anyone with `tasks.run` scope) can trigger:

### From the API

```http
POST /api/tasks/run/{task_name}
Authorization: Bearer <token-with-tasks.run>
```

## Monitoring tasks

- **Live**: Administration → Tasks page shows every task's current status (queued, running, idle, failed).
- **API**: `GET /api/tasks/status` for a JSON summary. Wire this to an uptime monitor if you want alerts.
- **Logs**: `docker logs romm` → look for `rq.worker` lines.

A task that's been "running" for hours is usually a scan that hit `SCAN_TIMEOUT`, and the logs will say so. Tasks that fail leave a stack trace in the container logs, and the RQ `failed` queue retains the last few for inspection.

## Tuning for small hosts

On a Raspberry Pi or NAS with 2 GB of RAM and/or a single CPU core:

- Raise the cron intervals (daily → weekly) for the nightlies
- Set `SCAN_WORKERS=1` to avoid concurrent scan processes
- Enable the watcher but raise `RESCAN_ON_FILESYSTEM_CHANGE_DELAY` to 30+ minutes
- Disable image conversion if you don't care about WebP (`ENABLE_SCHEDULED_CONVERT_IMAGES_TO_WEBP=false`).

---

### Administration/Server Stats

---
title: Server Stats
description: "The numbers Mason! What do they mean?"
---

# Server Stats

**Administration → Server Stats** is an admin-only page that reports what's on disk and in the catalogue.

## What's shown

### Top-line counts

| Metric           | What it counts                                                                    |
| ---------------- | --------------------------------------------------------------------------------- |
| **Platforms**    | Every platform RomM has seen at least one ROM for. Deleted platforms don't count. |
| **Games**        | Total ROM entries. A multi-file game (folder with multiple files) counts as 1.    |
| **Saves**        | User save files across all users.                                                 |
| **States**       | Emulator save states across all users.                                            |
| **Screenshots**  | User-uploaded screenshots. Provider-fetched screenshots aren't counted here.      |
| **Size on disk** | Total disk usage of all ROMs, saves, states, and screenshots.                     |

### Per-platform breakdown

Under the summary, it's a table sorted by name, size or game count. For each platform, you can see:

- Game count
- Size on disk (in bytes and by percentage of total)
- Region distribution (how many games tagged USA, Japan, Europe, World, etc.)
- Metadata coverage (how many games have metadata from each provider)

When you want to know "which platform is eating my disk?" or "which platform has the worst match rate?"

## API

The same data is available programmatically:

```http
GET /api/stats
GET /api/stats?include_platform_stats=true
Authorization: Bearer <token>
```

Wire to your monitoring stack via the API rather than scraping the HTML page (see the [API Reference](../developers/api-reference.md)).

## Troubleshooting

- **Numbers look stale**: stats are computed on page load, not cached
- **Disk sizes look wrong**: if your compose mounts a path that's smaller than the host dataset (e.g. you mounted a sub-directory), it will only see that subset
- **"Platform stats couldn't load"**: the DB query timed out on a very large library

For anything else, see [Troubleshooting](../troubleshooting/index.md).

---

### Administration/Users And Roles

---
title: Users & Roles
description: User management, roles, and the permission-group model
---

# Users & Roles

The first user created during Setup is always an **Admin**, and everyone after that is a regular **User** whose access is governed by the [permission group](#permission-groups) you assign.

## Roles

There are only two roles:

| Role      | Who it's for                     | Access                                                                             |
| --------- | -------------------------------- | ---------------------------------------------------------------------------------- |
| **Admin** | You, and anyone you fully trust. | Admins **bypass permission groups** entirely, including user management and tasks. |
| **User**  | Everyone else                    | Whatever their assigned permission group grants, plus any per-user overrides.      |

## Permission groups

Each User belongs to a **permission group**: a named template of capabilities that you manage in the new UI (**Administration → Permissions**). A group is a **grant matrix** over entity types and actions:

| Entity        | `read`                        | `write`                          | `delete`         |
| ------------- | ----------------------------- | -------------------------------- | ---------------- |
| `platforms`   | Browse platforms              | Edit/create platforms            | Delete platforms |
| `roms`        | Browse ROMs                   | Edit ROM metadata                | Delete ROMs      |
| `collections` | Browse collections            | Create/edit                      | Delete           |
| `firmware`    | List firmware                 | Upload firmware                  | Delete firmware  |
| `assets`      | View saves/states/screenshots | Upload/replace                   | Delete           |
| `devices`     | View paired devices           | Pair/manage devices              | Unpair devices   |
| `users`       | List users                    | Create/edit users                | Delete users     |
| `tasks`       | View task status              | Trigger tasks (scan, cleanup, …) | —                |
| `logs`        | View server logs              | —                                | —                |

Rules of the model:

- **A missing grant means denied.** A group only allows what it explicitly lists.
- **`own_only`** narrows a grant to entities the user owns. For example, `assets.write` with `own_only` lets a user manage their own saves/states/screenshots but not anyone else's.
- **Default group**: exactly one group is marked as the server-wide default and is applied automatically to every new User (invite sign-up, OIDC first login, admin-created accounts without an explicit group).

### Per-user overrides

On top of the group, you can **add or revoke individual capabilities** for one user without creating a whole new group:

- **Grant** an override to give a user something their group lacks.
- **Revoke** an override to take away something their group provides.

Use overrides for one-offs ("this one user can also delete ROMs"), and use groups for anything you'd apply to more than one person.

### Hidden entities

Beyond allow/deny, you can **hide specific platforms or ROMs** from a user or from an entire group. A hidden entity simply doesn't appear for that principal, regardless of read grants. Firmware visibility isn't hidden directly, as it cascades from the platform it belongs to.

## Creating users

Three paths:

- **Admin page**: set username, email, password, role, and a permission group. The account is usable immediately.
- **Invite link**: when you don't want to handle someone else's password. The admin generates a single-use link, and the recipient picks their own credentials. New Users land in the default permission group. Invite links expire after 600 seconds by default, configurable via [`INVITE_TOKEN_EXPIRY_SECONDS`](../reference/environment-variables.md).
- **OIDC**: if you've wired up OIDC, new identities can be provisioned on first login. Whether that happens is controlled by `OIDC_ALLOW_REGISTRATION`, and Admin mapping from OIDC claims is covered in [OIDC Setup](oidc/index.md).

## Editing and deleting users

Admins can change any user's role, move them between permission groups, add per-user overrides, reset their password, or delete the account. Role and permission changes take effect on next login. You can't delete the last admin or delete yourself while signed in.

Deleting a user keeps their contributions (collections they made public, ROM metadata edits) but removes their personal data from the database (per-ROM ratings, saves, states, play sessions, paired devices, API tokens). It does not delete any files from disk.

## OAuth scopes

The permission groups above are the source of truth for the UI. For the **API**, RomM derives a flat set of OAuth **scopes** from a user's effective grants (group + overrides). Each `(entity, action)` grant maps to the scope of the same name, e.g. `roms` + `write` → `roms.write`. Client API Tokens and OIDC sessions carry a **subset** of the owning user's scopes, and every endpoint declares which scopes it requires.

The full scope list (grouped by resource):

| Resource    | Scopes                                                         |
| ----------- | -------------------------------------------------------------- |
| Profile     | `me.read`, `me.write`                                          |
| ROMs        | `roms.read`, `roms.write`, `roms.user.read`, `roms.user.write` |
| Platforms   | `platforms.read`, `platforms.write`                            |
| Assets      | `assets.read`, `assets.write`                                  |
| Collections | `collections.read`, `collections.write`                        |
| Firmware    | `firmware.read`, `firmware.write`                              |
| Devices     | `devices.read`, `devices.write`                                |
| Users       | `users.read`, `users.write`                                    |
| Tasks       | `tasks.run`                                                    |
| Logs        | `logs.read`                                                    |

## API tokens (advanced)

Each user can issue up to 25 **Client API Tokens**. A token carries a subset of the owning user's scopes (see above), whichever you pick at creation time. Tokens are the right way to authenticate companion apps (Argosy, Grout, Playnite, custom scripts). The pairing flow for devices is covered in [Client API Tokens](../developers/client-api-tokens.md), and the API side is in [API Authentication](../developers/api-authentication.md).

---

### Developers/Api Authentication

---
title: API Authentication
description: How to authenticate to the API
---

# API Authentication

The API accepts multiple authentication modes:

| Mode                 | Who it's for                                             | How the credential is carried                    |
| -------------------- | -------------------------------------------------------- | ------------------------------------------------ |
| **Session cookie**   | Browser UI                                               | `Cookie: session=…` after `POST /api/auth/login` |
| **HTTP Basic**       | Quick scripts, curl one-liners                           | `Authorization: Basic <base64(user:pass)>`       |
| **OAuth2 Bearer**    | Automation, CI, third-party apps                         | `Authorization: Bearer <jwt>`                    |
| **Client API Token** | Companion apps (Argosy, Grout, Playnite, custom scripts) | `Authorization: Bearer rmm_<token>`              |

All of them resolve to the same scope model. See the [OAuth scopes in Users & Roles](../administration/users-and-roles.md#oauth-scopes). A request is allowed if the active identity holds all scopes the endpoint requires.

## Base URL

```text
https://<your-instance>/api
```

When the app is behind a reverse proxy (as it should be when hosted in public), that's your public URL. When running locally without a proxy, the container listens on port `80`.

## Session login (browsers)

```http
POST /api/auth/login
Content-Type: application/x-www-form-urlencoded

username=alice&password=s3cret
```

Response sets a `romm_session` cookie, and subsequent requests from the same browser are authenticated automatically.

Log out:

```http
POST /api/auth/logout
```

For OIDC logins, hitting `/api/auth/logout` also triggers RP-Initiated Logout if your OIDC provider supports it (configured via `OIDC_END_SESSION_ENDPOINT`).

## HTTP Basic

```bash
curl -u alice:s3cret https://demo.romm.app/api/roms
```

```python
import requests
from requests.auth import HTTPBasicAuth
r = requests.get("https://demo.romm.app/api/roms",
                 auth=HTTPBasicAuth("alice", "s3cret"))
```

## OAuth2 Bearer token

The RomM backend implements the OAuth2 password grant, where you exchange credentials for a short-lived access token and a refresh token. Access and refresh token expiry times are configurable via `OAUTH_ACCESS_TOKEN_EXPIRE_SECONDS` and `OAUTH_REFRESH_TOKEN_EXPIRE_SECONDS`.

```http
POST /api/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=alice&password=s3cret&scope=roms.read%20roms.write
```

```json
{
    "access_token": "eyJhbGciOi...",
    "refresh_token": "eyJhbGciOi...",
    "token_type": "bearer",
    "expires": 1800,
    "refresh_expires": 604800
}
```

Access tokens are HS256-signed JWTs valid for `OAUTH_ACCESS_TOKEN_EXPIRE_SECONDS` seconds. Send them as:

```http
Authorization: Bearer eyJhbGciOi...
```

Refresh before expiry:

```http
POST /api/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=eyJhbGciOi...
```

Request only the scopes you need and RomM will issue a token with the intersection of what you asked for and what the user has.

## Client API tokens (for companion apps)

For anything long-lived (a running companion app, a cron job, a CI integration), use **Client API Tokens** instead of OAuth2. They're issued per-user from **Administration → Client API Tokens**, carry a subset of the user's scopes, and don't expire unless you set an expiry.

Token format: `rmm_` + 64 hex chars. Use it as a bearer:

```bash
curl -H "Authorization: Bearer rmm_abcdef0123456789..." \
     https://demo.romm.app/api/roms
```

Each user gets up to 25 active tokens. Tokens can be paired with a device via the [pairing flow](client-api-tokens.md), useful when you don't want to type a long token on a handheld.

## OIDC

Users signing in through an OIDC provider get a regular RomM session, same as username/password login. For the API side this means you can't use an OIDC access token directly. Authenticate the user through the browser first (they'll be redirected to the OIDC provider, then back to RomM), then use the resulting session cookie, **or** mint a Client API Token for programmatic use.

OIDC provider setup lives in [Administration → OIDC](../administration/oidc/index.md).

## Which scopes do I need?

Every endpoint in the [API Reference](api-reference.md) lists its required scopes. The short version:

- **Read**-ish endpoints want the matching `*.read` scope.
- **Write**-ish endpoints want `*.write`.
- **Admin**-ish endpoints want `users.read`, `users.write`, or `tasks.run`.

## Errors

| HTTP               | Meaning                                                                 |
| ------------------ | ----------------------------------------------------------------------- |
| `401 Unauthorized` | No credential, expired credential, bad credential.                      |
| `403 Forbidden`    | Authenticated but the identity lacks a required scope.                  |
| `404 Not Found`    | The resource doesn't exist, or, for privacy, the identity can't see it. |

When debugging a 403, check:

1. The **user's role** in Administration → Users.
2. The **token's scopes** (for OAuth2/Client API Tokens). Scopes are narrower than the user's role by default.
3. The endpoint's scope requirements in the [API Reference](api-reference.md).

## OpenAPI

The full machine-readable schema is served at `/openapi.json`. It's the source of truth for generated clients, Postman collections, and the in-docs [API Reference](api-reference.md).

```bash
curl https://demo.romm.app/openapi.json > romm-openapi.json
```

See [Consuming OpenAPI](openapi.md) for codegen tips.

---

### Developers/Api Reference

---
title: API Reference
description: Catalogue of the API. Authoritative interactive docs live on each instance.
---

## Interactive docs

Every RomM instance hosts two renderings of its own spec:

- **Swagger UI** at `{romm_url}/api/docs`: explore + try endpoints inline
- **ReDoc** at `{romm_url}/api/redoc`: cleaner reading layout

The raw spec:

```text
{romm_url}/openapi.json
```

For code generation, see [Consuming OpenAPI](openapi.md).

## WebSockets

REST isn't the only surface. Two socket.io endpoints cover live-update and coordination use cases: [WebSockets](websockets.md).

## Versioning

The API follows SemVer along with the rest of RomM:

- **Breaking changes only in major versions.** Endpoint removal, required-parameter changes, incompatible response-schema shifts
- **Minor versions add** endpoints, optional parameters, optional response fields.
- **Patch versions fix** bugs without schema changes.

## See also

- [API Authentication](api-authentication.md): auth modes in detail
- [Consuming OpenAPI](openapi.md): codegen + schema validation
- [WebSockets](websockets.md): socket.io endpoints
- [Client API Tokens](client-api-tokens.md): recommended companion-app auth
- [Device Sync Protocol](device-sync-protocol.md): sync endpoints in depth

---

### Developers/Architecture

---
title: Architecture
description: High-level walkthrough of the codebase
---

# Architecture

What you need to know to find your way around `rommapp/romm` before you start changing things. The exhaustive deep-dives live alongside the code at [`docs/BACKEND_ARCHITECTURE.md`](https://github.com/rommapp/romm/blob/main/docs/BACKEND_ARCHITECTURE.md) and [`docs/FRONTEND_ARCHITECTURE.md`](https://github.com/rommapp/romm/blob/main/docs/FRONTEND_ARCHITECTURE.md). This page is the orientation pass.

## Repo layout

```text
rommapp/romm
├── backend/              # Python FastAPI application
│   ├── endpoints/        # Route handlers + socket.io under sockets/
│   ├── handler/          # Business logic: database/, metadata/, filesystem/, auth/
│   ├── adapters/services/# External API clients (IGDB, Moby, SS, SGDB, RA, ...)
│   ├── models/           # SQLAlchemy ORM
│   ├── tasks/            # RQ jobs: scheduled/ and manual/
│   ├── alembic/          # 80+ DB migrations
│   └── config/           # Env vars + YAML config.json manager
├── frontend/             # Vue 3 + Vuetify SPA (main UI + alternate UI)
│   └── src/
│       ├── views/        # Page-level components
│       ├── components/   # ~168 components, organised by feature
│       ├── console/      # Alternate UI SPA (own router, layout, input bus)
│       ├── stores/       # 18 Pinia stores
│       ├── services/     # Axios API modules + socket.io + browser cache
│       └── __generated__/# TS types generated from the backend OpenAPI spec
├── docker/               # nginx config, entrypoint, Dockerfiles
└── examples/             # Reference docker-compose.yml and config.yml
```

## Runtime topology

A running RomM container hosts several cooperating processes:

```ascii
┌─────────────────────────────────────────────────────────┐
│ docker container                                        │
│                                                         │
│  ┌───────┐   HTTP   ┌──────────┐  python  ┌──────────┐  │
│  │ nginx │─────────→│ gunicorn │─────────→│ FastAPI  │  │
│  │ :8080 │          │  :5000   │          │ backend  │──┐
│  └───┬───┘          └──────────┘          └──────────┘  │ SQL
│      │   static files (SPA, EmulatorJS, Ruffle)         ↓
│      │                                           ┌──────────┐
│      │                                           │ MariaDB  │
│      ↓                                           │ (or PG/│
│  /library /assets /resources                     │  MySQL)  │
│  (host bind mounts)                              └──────────┘
│                                                         │
│  ┌──────────┐         ┌──────────────────────┐          │
│  │ RQ       │←───────→│ Valkey               │          │
│  │ workers  │  jobs   │ (embedded or external)│          │
│  └──────────┘         └──────────────────────┘          │
└─────────────────────────────────────────────────────────┘
```

## Request lifecycle

Every request runs the middleware stack in order, CORS → CSRF → authentication → Valkey-backed session → context vars (aiohttp + httpx clients), before FastAPI dispatches to the endpoint. Handlers do the actual work and Pydantic schemas serialise the response.

## Backend

### Layers

The backend follows a fairly conventional layering. Endpoints handle request validation and response serialisation, while the actual business logic lives in handlers organised by concern: `handler/database/` for per-entity CRUD, `handler/metadata/` for provider-specific normalisation, `handler/filesystem/` for I/O, and `handler/auth/` for the multi-method auth backend. Models are SQLAlchemy ORM, and adapters wrap the external APIs.

### Authentication

`HybridAuthBackend` walks methods in order of session cookie (looked up in Valkey), HTTP Basic (bcrypt), OAuth2 Bearer JWT (HS256), Client API Token (`rmm_...`, SHA-256 lookup), OIDC, kiosk mode if enabled. Token plaintext is never stored as we hash on creation and compare hashes on every request.

### Metadata providers

Each provider has a handler under `handler/metadata/` that normalises responses into a common shape. Priority is configurable in `config.yml` (`scan.priority.metadata`), where first match wins per field, with manual overrides on top.

Hashing can be platform-aware: `.chd` files pull their SHA1 values straight from the file header, PICO-8 cartridges (`.p8.png`) get a special-cased extractor, and the RetroAchievements per-platform algorithm runs through `rahasher.py`. Switch and PS3/4/5 skip hashing entirely, since those ROMs aren't reasonably hashable in the first place and have no TOSEC/No-Intro entries.

### Configuration

Environment variables (100+ of them, all listed in `env.template`) cover infrastructure concerns, while `config.yml` covers everything to do with the library, scanning, and emulator behaviour. The config is read, validated, and written back through the singleton `ConfigManager`.

### Background jobs

RQ workers run scheduled jobs (rescans, Switch TitleDB refresh, LaunchBox refresh, image-to-WebP conversion, RA progress sync, netplay cleanup) and manual tasks (`cleanup_missing_roms`, `cleanup_orphaned_resources`, `sync_folder_scan`). Each scheduled task is gated by an `ENABLE_SCHEDULED_*` env var and tunable via the matching `*_CRON`. Operator-side detail in [Scheduled Tasks](../administration/scheduled-tasks.md).

## Frontend

### Stack

The frontend is a Vue 3 SPA written in TypeScriptusing the Composition API and `<script setup>` syntax, bundled by Vite which gives HMR in development. The UI layer is Vuetify 3 (Material Design) topped with Tailwind CSS 4 for utility classes, and state lives in Pinia stores. Vue Router covers named routes across three layouts, while vue-i18n supplies translations for language packs. Live updates flow through `socket.io-client` for scan progress and netplay, and Mitt sits in the middle as a loose event bus, which is handy for triggering dialogs from anywhere in the component tree without having to thread refs through props.

### Generated types

TypeScript interfaces in `src/__generated__/` are produced from the backend OpenAPI spec by running `npm run generate`, and the stores and API services consume them directly, giving you type-safe end-to-end communication. Re-run the generator after any backend route or schema change so the frontend types stay in sync.

### Persistence

UI preferences live in localStorage and sync to `user.ui_settings` on the backend through the `useUISettings` composable, so a user's settings follow them across devices and browsers. Session data sits in Pinia in memory, and the Browser Cache API holds API responses when the _experimental_ opt-in cache layer is enabled.

### Layouts

Three layouts cover the routes:

- **Auth** (public): setup, login, password reset, register
- **Main** (authenticated): home, gallery, game details, scan, patcher, settings, admin
- **Console** (authenticated, gamepad/TV): `/console/*`

Permission-protected routes follow the scope model from [Users & Roles](../administration/users-and-roles.md): `/scan` and `/library-management` require `platforms.write`, `/client-api-tokens` requires `me.write`, and `/administration` requires `users.write`.

### Alternate TV and gamepad UI

A second SPA bundle aimed at TVs and gamepads is kept under `frontend/src/console/`. The input system is a stack-based bus with grid-based spatial navigation, gamepad polling runs in `requestAnimationFrame`, and the sound effects are synthesised on the fly through the Web Audio API rather than shipped as audio assets.

## Real-time

Two socket.io servers run side by side, both Valkey-backed so they horizontally scale across multiple replicas. `/ws` carries scan progress (`scan:update_stats`, `scan:log`, `scan:stop`) and general notifications, while `/netplay` handles room creation, joining, and peer message relay. The wire-level reference is in [WebSockets](websockets.md).

## Filesystem layout

```text
{ROMM_BASE_PATH}/                # Default: /romm
├── library/{platform_slug}/     # ROMs (roms/) and BIOS (bios/)
├── resources/roms/{rom_id}/     # Cached cover art + screenshots
├── assets/users/{user_id}/      # User saves, states, screenshots
└── config/config.yml            # YAML configuration
```

Production serves files via nginx `X-Accel-Redirect`. Dev mode (`DEV_MODE=true`) falls back to FastAPI's `FileResponse`, slower but no nginx in the loop.

## Observability

Sentry (opt-in via `SENTRY_DSN`) captures unhandled exceptions, tagged with `romm@{version}`. OpenTelemetry (opt-in) ships traces, metrics, and logs over OTLP. `GET /api/heartbeat` returns an aggregated health snapshot, safe to scrape from uptime monitors. Setup details in [Observability](../administration/observability.md).

## Where to start

If you're picking up your first issue, the patterns to mimic live in `backend/handler/` for backend work and in `frontend/src/components/` plus the relevant Pinia store for frontend work. Match the surrounding style. The hardest part of contributing isn't writing the change, it's threading it through the existing layers cleanly (see [Contributing](contributing.md) for process and [Development Setup](development-setup.md) to get a local env running).

---

### Developers/Client Api Tokens

---
title: Client API Tokens
description: Long-lived bearer tokens for companion apps
---

# Client API Tokens

A **Client API Token** is a long-lived credential that a companion app (or script, or CI job) uses to authenticate against RomM on behalf of a specific user. Think "personal access token" on GitHub. Tokens are **per-user** and **per-scope-subset**: a token can hold any subset of the owning user's scopes, scoped narrower than the user's role. You get up to **25 active tokens per user**.

## Why not just store a password?

- Passwords grant full access to the account but tokens can be scope-narrowed.
- Tokens are one-click revocable without changing your password.
- Tokens are safer to type (or paste) into a companion app's config file than a password.

## Token format

64 hex characters prefixed with `rmm_`:

```text
rmm_abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
```

Send as a bearer token on any authenticated API call:

```http
Authorization: Bearer rmm_abcdef...
```

## Creating a token

A token is created with three params:

- **Token name**: descriptive (e.g. "Grout on RG35XX")
- **Expiration**: optional, blank = never expires until revoked
- **Permissions**: default to read-only, and don't grant every token `users.write`.

The token is shown **exactly once** at creation time. Copy it then, because if you lose it you'll need to revoke and regenerate.

## Device pairing

Typing a 68-character token into a handheld thumbstick isn't realistic. Instead:

### Flow

```ascii
┌───────────┐                                 ┌───────────┐
│  Device   │                                 │   RomM    │
└─────┬─────┘                                 └─────┬─────┘
      │                                             │
      │ 1. POST /api/client-tokens/{id}/pair        │
      │ (from the web UI, by the token's owner)     │
      │<── generates short code (8 digits) ─────────│
      │                                             │
      │ 2. Device user types the 8-digit code       │
      │    into the companion app                   │
      │                                             │
      │ 3. Device: POST /api/client-tokens/exchange │
      │     body: { "code": "12345678" }            │
      │──────────────────────────────────────────→  │
      │                                             │
      │<── full token (rmm_...) ────────────────────│
      │                                             │
      │ 4. Device stores the token, uses it from    │
      │    now on.                                  │
      │                                             │
```

### Timing

- Pairing codes are valid for **5 minutes** after creation
- Once a device exchanges the code, it's invalid for anyone else (single-use)
- Re-create it if the user doesn't complete the flow within the time window

### Who generates the code

The user who owns the token from a device already signed into RomM (web UI, usually). The handheld/companion device then enters or scans the code.

### What "pairing" gives you

The companion app stores the token and uses it on every subsequent API call. From RomM's side, it looks like any other token, and there's no special treatment beyond the fact that pairing is how the token got there.

## Scoping tokens properly

A token can only hold scopes the owning user _also_ holds, and a user's scopes come from their [permission group](../administration/users-and-roles.md#permission-groups) plus any overrides (Admins hold everything). For example, a token can't carry `users.write` unless its owner is an Admin. Default to read-only, and only grant write scopes the app actually needs.

## What happens on permission change

If the owning user's permissions are narrowed so they no longer hold what a token needs, the token continues to exist but fails at request time with **403 Forbidden**. It's the user's decision to revoke it. However if the user is deleted, all their tokens are revoked immediately.

## Anti-patterns

- **Sharing a token between users.** If two people need access, give them each an account and each creates their own token.
- **Embedding a token in public source.** Obvious but worth saying, if you accidentally commit one, revoke it immediately.
- **A single token for every app.** Name and scope per-app, so revoking one doesn't kill the others.
- **Infinite-expiry tokens in untrusted locations.** If a device might be lost/handed off, set an expiry.

## See also

- [Device Sync Protocol](device-sync-protocol.md): how the synced content flows after pairing
- [API Authentication](api-authentication.md): all RomM auth modes side-by-side
- [Users & Roles → OAuth scopes](../administration/users-and-roles.md#oauth-scopes): the full scope taxonomy

---

### Developers/Contributing

---
title: Contributing
description: How to contribute to RomM and its documentation
---

# Contributing to the documentation

Thank you for considering contributing to the documentation! This document outlines some guidelines to help you get started with your contributions.

**If you're looking to implement a large feature or make significant changes to the project, it's best to open an issue first AND join the Discord to discuss your ideas with the maintainers.**

## Code of Conduct

Please note that this project adheres to the Contributor Covenant [code of conduct](https://github.com/rommapp/docs/blob/main/CODE_OF_CONDUCT.md). By participating in this project, you are expected to uphold this code.

## Setting up the linter

We use [Trunk](https://trunk.io) for linting, which combines multiple linters with sensible defaults and a single configuration file. You'll need to install the Trunk CLI to use it.

### Install the Trunk CLI

```sh
curl https://get.trunk.io -fsSL | bash
```

Alternative installation methods can be found [here](https://docs.trunk.io/check/usage#install-the-cli). On commit, the linter will run automatically. To run it manually, use the following commands:

```sh
trunk fmt
trunk check
```

## Building the documentation

We use `uv` to build the documentation. To install it, run:

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

And activate it:

```sh
uv venv
source .venv/bin/activate
```

Then install python and the required dependencies:

```sh
uv python install
uv sync --all-extras --dev
```

Finally run the following command to serve the documentation from a local server:

```sh
uv run mkdocs serve [-a ip:port] --livereload
```

## Deploy

We use [mike](https://github.com/jimporter/mike) to build and deploy documentation versions. Manually deploy a version needs to update and push the specific version (or a new one if creating a new version) with the following command:

```sh
uv run mike deploy --push --update-aliases <version> [alias]
```

This will update the `gh-pages` branch and automatically deploys the version with the fix/update to <https://docs.romm.app>.

## Pull Request Guidelines

- Make sure your code follows the project's coding standards.
- Test your changes locally before opening a pull request.
- Update the documentation if necessary.
- Ensure all existing tests pass, and add new tests for new functionality.
- Use clear and descriptive titles and descriptions for your pull requests.

## Issue Reporting

If you encounter any bugs or have suggestions for improvements, please [create an issue](https://github.com/rommapp/docs/issues) on GitHub. Provide as much detail as possible, including steps to reproduce the issue if applicable.

## Licensing

By contributing to the documentation, you agree that your contributions will be licensed under the project's [LICENSE](https://github.com/rommapp/docs/blob/main/LICENSE).

Thank you for contributing to the documentation! Your help is greatly appreciated.

---

### Developers/Development Setup

---
title: Development Setup
description: Run RomM locally for development
---



# Setting up RomM for development

## Option 1: Using Docker

If you prefer to use Docker for development, you can set up RomM using the provided Docker Compose configuration. This method simplifies the setup process by encapsulating all dependencies within Docker containers.

### Environment setup

#### Create the mock structure with at least one ROM and empty config for manual testing

```sh
mkdir -p romm_mock/library/roms/switch
touch romm_mock/library/roms/switch/metroid.xci
mkdir -p romm_mock/resources
mkdir -p romm_mock/assets
mkdir -p romm_mock/config
touch romm_mock/config/config.yml
```

#### Copy env.template to .env and fill the variables

```sh
cp env.template .env
```

```dotenv
ROMM_BASE_PATH=/app/romm
DEV_MODE=true
```

#### Build the image

```sh
docker compose build  # or `docker compose build --no-cache` to rebuild from scratch
```

#### Spin up the Docker containers

```sh
docker compose up -d
```

And you're done! You can access the app at `http://localhost:3000`. Any changes made to the code will be automatically reflected in the app thanks to the volume mounts.

## Option 2: Manual setup

### Environment setup

#### Create the mock structure with at least one ROM and empty config for manual testing

```sh
mkdir -p romm_mock/library/roms/switch
touch romm_mock/library/roms/switch/metroid.xci
mkdir -p romm_mock/resources
mkdir -p romm_mock/assets
mkdir -p romm_mock/config
touch romm_mock/config/config.yml
```

#### Copy env.template to .env and fill the variables

```sh
cp env.template .env
```

#### Install system dependencies

```sh
# https://mariadb.com/docs/skysql-previous-release/connect/programming-languages/c/install/#Installation_via_Package_Repository_(Linux):
sudo apt install libmariadb3 libmariadb-dev libpq-dev

# Build and configure RAHasher (optional)
# This is only required to calculate RA hashes
# Users on macOS can skip this step as RAHasher is not supported
git clone --recursive https://github.com/RetroAchievements/RALibretro.git
cd ./RALibretro
git checkout 1.8.3
git submodule update --init --recursive
make HAVE_CHD=1 -f ./Makefile.RAHasher
cp ./bin64/RAHasher /usr/bin/RAHasher
```

#### Install python dependencies

You'll need uv installed

<https://docs.astral.sh/uv/getting-started/installation/>

```sh
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Then create the virtual environment and install the dependencies using uv:

```sh
uv venv
source .venv/bin/activate
uv sync --all-extras --dev
```

#### Spin up the database and other services

```sh
docker compose up -d
```

#### Run the backend

_Migrations will be run automatically when running the backend._

```sh
cd backend
uv run python3 main.py
```

### Setting up the frontend

#### Install node.js dependencies

```sh
cd frontend
# npm version >= 9 needed
npm install
```

#### Create symlink to library and resources

```sh
mkdir assets/romm
ln -s ../romm_mock/resources assets/romm/resources
ln -s ../romm_mock/assets assets/romm/assets
```

#### Run the frontend

```sh
npm run dev
```

## Setting up the linter

We use [Trunk](https://trunk.io) for linting, which combines multiple linters and formatters with sensible defaults and a single configuration file. You'll need to install the Trunk CLI to use it.

### Install the Trunk CLI

```sh
curl https://get.trunk.io -fsSL | bash
```

Alternative installation methods can be found [in their docs](https://docs.trunk.io/check/usage#install-the-cli). On commit, the linter will run automatically. To run it manually, use the following commands:

```sh
trunk fmt
trunk check
```

**Failing to install and run the linter will result in a failed CI check, which won't allow us to merge your PR.**

## Test setup

### Create the test user and database with root user

```sh
docker exec -i romm-db-dev mariadb -uroot -p<root password> < backend/romm_test/setup.sql
```

### Run tests

_Migrations will be run automatically when running the tests._

```sh
cd backend
# path or test file can be passed as argument to test only a subset
uv run pytest [path/file]
# or run the following command to run all tests
# the -vv switch increases the verbosity of the output, providing more detailed information during test execution.
uv run pytest -vv
```

---

### Developers/Device Sync Protocol

---
title: Device Sync Protocol
description: Wire-level reference for save/state/play-session sync
---

# Device Sync Protocol

This is a reference for the protocol RomM uses for bidirectional sync with companion apps. End-user view in [Saves & States](../using/saves-and-states.md), with operator-side SSH transport in [SSH Sync](ssh-sync.md).

## Primitives

- **Device**: a registered endpoint, bound to a [Client API Token](client-api-tokens.md).
- **Sync session**: one atomic bidirectional run (pull, push, conflict reconcile, play-session ingest).
- **Play session**: per-ROM playtime record, posted standalone or batched at sync end.

## Authentication

Every call: `Authorization: Bearer rmm_...`. Required scopes:

| Endpoint family              | Scope                                                         |
| ---------------------------- | ------------------------------------------------------------- |
| `/devices/*`                 | `devices.read`, `devices.write`                               |
| `/sync/*`                    | `assets.read`, `assets.write`, `devices.write`                |
| `/play-sessions/*`           | `me.read`, `me.write` (read own), `users.read` (read others') |
| `/assets/*` (save/state I/O) | `assets.read`, `assets.write`                                 |

## Registering a device

After [pairing](client-api-tokens.md#device-pairing):

```http
POST /api/devices
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "RG35XX - Living Room",
  "platform": "muos",
  "hostname": "rg35xx-livingroom.local",
  "mac": "aa:bb:cc:dd:ee:ff",
  "sync_mode": "push_pull",
  "paths": { "roms": "/roms", "saves": "/saves", "states": "/saves/states" }
}
```

Response includes `id`, which the device caches for subsequent calls. `sync_mode` can be `pull_only` (server → device), `push_only` (device → server), or `push_pull` (bidirectional, default).

## Sync negotiation

The device sends what it has and RomM returns what to do:

```http
POST /api/sync/negotiate
{
  "device_id": 17,
  "roms": [
    {
      "rom_id": 1234,
      "saves": [
        { "file": "mario.srm",   "mtime": "2026-04-18T09:42:01Z", "sha1": "abc..." },
        { "file": "mario.state", "mtime": "2026-04-18T09:45:00Z", "sha1": "def..." }
      ]
    }
  ]
}
```

Response is a list of operations:

```json
{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "operations": [
        {
            "type": "upload",
            "rom_id": 1234,
            "file": "mario.srm",
            "destination": "/api/saves"
        },
        {
            "type": "download",
            "rom_id": 5678,
            "file": "zelda.srm",
            "source": "/api/saves/42/content",
            "dest_path": "/saves/zelda.srm"
        },
        {
            "type": "conflict",
            "rom_id": 9999,
            "file": "tetris.srm",
            "resolution": "keep_both"
        },
        { "type": "noop", "rom_id": 1111, "file": "goldeneye.srm" }
    ]
}
```

| Op         | Meaning                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `upload`   | Device `POST`s the file to `destination`.                                                          |
| `download` | Device `GET`s `source` and writes to `dest_path`.                                                  |
| `conflict` | Both sides newer, `resolution` must be one of `keep_both` (default), `server_wins`, `device_wins`. |
| `noop`     | Hashes match, nothing to do.                                                                       |

Upload (`POST /api/saves`, multipart) and download (`GET /api/saves/{id}/content`) both require the bearer token.

## Completing a session

```http
POST /api/sync/sessions/{session_id}/complete
{
  "operations_completed": 15,
  "operations_failed": 1,
  "play_sessions": [
    { "rom_id": 1234, "start": "2026-04-18T09:00:00Z", "end": "2026-04-18T09:45:00Z", "duration_seconds": 2700 }
  ]
}
```

Closes the session and ingests batched play sessions in one call.

## Rate limits and polling

- Sync once per session, not per save
- Don't poll `/api/sync/negotiate` tightly
- No push channel yet, so polling is the only model

## See also

- [Client API Tokens](client-api-tokens.md): auth and pairing
- [API Authentication](api-authentication.md): general auth primer
- [API Reference](api-reference.md): full endpoint catalogue
- [SSH Sync](ssh-sync.md): alternative transport
- [Argosy](../ecosystem/first-party-apps.md#argosy-launcher), [Grout](../ecosystem/first-party-apps.md#grout): reference client implementations

---

### Developers/I18n

---
title: Translations (i18n)
description: Contributor guide for adding or improving translations
---

# Translations (i18n)

This page is for **contributors** adding or improving translations. Picking a language as an end user? See [Languages](../using/languages.md) instead.

## What's translated

- **The app UI** is translated. 19 locales currently ship
- **The docs** (what you're reading right now) are currently English-only
- **Game metadata** comes from metadata providers (IGDB, ScreenScraper) and their localisation varies per title

## Tech stack

- **Library**: [vue-i18n](https://vue-i18n.intlify.dev/)
- **Format**: JSON, one file per feature per locale
- **Location**: `frontend/src/locales/<locale>/`

`en_US/` is the reference, and other locales must always be kept complete and current, which is validated by CI. When in doubt, copy the English key and change the value.

## Adding keys to an existing locale

If the English UI has a string that isn't translated in your locale, fill it in:

1. Fork [rommapp/romm](https://github.com/rommapp/romm)
2. Open `frontend/src/locales/en_US/*.json` and find the untranslated key
3. Open the corresponding file in `frontend/src/locales/<your-locale>/*.json`
4. Add the key with your translation
5. Open a pull request

### Example

`en_US/common.json`:

```json
{
    "scan": "Scan",
    "continue_playing": "Continue Playing"
}
```

`fr_FR/common.json` before:

```json
{
    "scan": "Analyser"
}
```

After your contribution:

```json
{
    "scan": "Analyser",
    "continue_playing": "Continuer à jouer"
}
```

## Adding a new locale

If the language you want isn't in the dropdown yet:

1. Pick the locale code in [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) form (`de_DE`, `pt_BR`, `zh_TW`)
2. Copy `frontend/src/locales/en_US/` to `frontend/src/locales/<your-locale>/`
3. Start translating the most-visible strings (menu, navigation, home dashboard), and work your way through the rest as you have time
4. Register the locale in the index file (look in `frontend/src/locales/index.ts`)
5. Verify your locale appears in the in-app language picker.
6. Open a pull request


!!! tip
    AI is excellent at scaffolding a new locale, but be sure to review and edit the output for accuracy and style.

## Style guidance

### Tone

Match the source tone:

- **Conversational but not too casual.** "Let's scan your library" is fine, but "Yo, scan your ROMs dude" isn't.
- **Active voice.** "Scanning the library" reads better than "The library is being scanned".
- **Consistent formality.** Pick `tu`/`vous`, formal/informal `you`, and so on, then stick with that choice across the entire locale.

### Consistency

Use the same word for the same concept throughout. If you translate "Collection" one way at the top of a file, don't translate it differently three screens later.

### Interpolations

vue-i18n uses `{placeholder}` syntax. **Don't translate placeholder names.**

```json
{
    "hello_user": "Hello, {username}!",
    "n_games_found": "Found {count} games"
}
```

Pluralisation:

```json
{
    "n_games_found": "No games found | {count} game found | {count} games found"
}
```

Pipe-separated forms: zero | one | more. Not every language has three, and `vue-i18n`'s pluralisation docs cover per-language rules.

### What not to translate

- Proper nouns (RomM, IGDB, ScreenScraper, RetroAchievements)
- Technical identifiers (env var names, config keys, URLs)
- Code samples and filenames

## Testing your translation

```sh
cd frontend && npm install && npm run dev
```

Open `http://localhost:3000`, pick your locale, and walk through the app to confirm strings appear correctly across major flows (browse, detail, admin, settings).

## Tooling

We don't use a translation-management platform (Weblate, Crowdin, etc.), but we may add one if interest grows, so open an issue if you'd prefer that!

---

### Developers/Index

---
title: API & Development
description: Build on top of RomM or contribute to it
---

# API & Development

Everything you need to **build on top of RomM** (third-party apps, scripts, integrations) or **contribute to it** (code, translations, docs). End-user content lives in [Using RomM](../using/index.md). Operator content lives in [Administration](../administration/index.md).

## Calling the API

- **[API Reference](api-reference.md)**: every endpoint, OpenAPI-driven
- **[API Authentication](api-authentication.md)**: all five auth modes (session, Basic, OAuth2, Client API Token, OIDC)
- **[Consuming OpenAPI](openapi.md)**: codegen, Postman imports, schema validation
- **[WebSockets](websockets.md)**: socket.io endpoints for live updates and Netplay

## Building companion apps

- **[Client API Tokens](client-api-tokens.md)**: how companion apps authenticate, including the device-pairing flow
- **[Device Sync Protocol](device-sync-protocol.md)**: wire-level reference for save/state/play-session sync
- **[Argosy](../ecosystem/first-party-apps.md#argosy-launcher), [Grout](../ecosystem/first-party-apps.md#grout)**: reference implementations to crib from

## Contributing to RomM itself

- **[Development Setup](development-setup.md)**: get a local env running
- **[Architecture](architecture.md)**: high-level codebase walkthrough
- **[Contributing](contributing.md)**: process, style, AI-assistance disclosure
- **[Translations (i18n)](i18n.md)**: add or improve a locale

## Reference

- **[Environment Variables](../reference/environment-variables.md)**: every env var, grouped by area
- **[Configuration File](../reference/configuration-file.md)**: `config.yml` schema
- **[Exports](../reference/exports.md)**: gamelist.xml/Pegasus export formats
- **[Glossary](../reference/glossary.md)**: canonical terminology

---

### Developers/Openapi

---
title: Consuming OpenAPI
description: Use the OpenAPI spec for code generation
---

# Consuming OpenAPI

RomM ships its entire API as an OpenAPI 3.0 spec, which includes every endpoint, every request and response schema, and every parameter.

## Where the spec lives

Every instance serves it at `{romm_url}/openapi.json`. It's public and doesn't require auth, so you can fetch it from any running instance, including `https://demo.romm.app/openapi.json`.

For human-readable renderings, see [API Reference](api-reference.md).

## Versioning

The spec is versioned alongside the app, so you can snapshot the spec at a specific version when your client needs reproducible builds:

```sh
curl https://demo.romm.app/openapi.json > openapi-5.0.0.json
```

The docs site embeds a rendered version of the spec at [API Reference](api-reference.md), built at docs-publish time from a pinned snapshot. If the rendered docs lag behind the live API, fetch the live spec from your instance directly.

## Importing into tools

- **Postman**: File → Import → paste the `openapi.json` URL
- **Insomnia**: Create → Import From → URL
- **Bruno**: Import Collection → OpenAPI

## Spec quirks

A few known rough edges to be aware of:

- **Some `additionalProperties` are loose.** Certain responses include fields that aren't declared in the schema, so treat the spec as "everything here is always present, more may follow" rather than an exact response guarantee.
- **socket.io isn't in the spec.** WebSocket endpoints are documented separately in [WebSockets](websockets.md).
- **Pagination defaults vary per endpoint.** Some endpoints paginate by default and some don't, so check the spec for each one before assuming.

---

### Developers/Ssh Sync

---
title: SSH Sync
description: Configure SSH key-based push/pull sync
---

# SSH Sync


!!! warning "Coming soon"
    SSH-based push/pull sync is a work in progress. The env var surface, key layout, and device-registration flow are still being finalised. This page will be filled in once the feature stabilises.

The plan is for the Push-Pull Device Sync task to push saves/states to registered devices and pull them back after a session, over SSH, using keys that RomM holds. Until that lands, sync via HTTPS + [Client API Tokens](client-api-tokens.md), which is what Argosy, Playnite, and most companion apps already use.

For the wire-level protocol, see [Device Sync Protocol](device-sync-protocol.md).

---

### Developers/Websockets

---
title: WebSockets
description: Endpoints for live updates
---

# WebSockets

RomM uses **socket.io** for real-time communication, with two endpoints serving distinct purposes:

| Endpoint             | Purpose                                                                       |
| -------------------- | ----------------------------------------------------------------------------- |
| `/ws/socket.io`      | Live updates (scan progress, task status, ROM mutations, admin notifications) |
| `/netplay/socket.io` | Netplay session coordination (room discovery, join/leave, lifecycle)          |

## Authentication

socket.io connections inherit the HTTP session, so if your `Cookie` header carries a session cookie, the WebSocket connection authenticates as that user. Programmatic clients pass the credential via the handshake `auth` field:

```javascript
const socket = io("https://demo.romm.app", {
    path: "/ws/socket.io",
    auth: {
        token: "rmm_...",
    },
});
```

A failed handshake closes the connection with an error event.

## Reverse-proxy requirements

Every reverse-proxy setup must forward the WebSocket upgrade. The recipes in [Reverse Proxy](../install/reverse-proxy.md) all keep WebSockets on by default.

Common breakages:

- Nginx without `proxy_set_header Upgrade $http_upgrade` and `Connection "upgrade"`
- Cloudflare with WebSockets disabled in Network settings
- Traefik without the default passthrough middlewares

A broken WS typically shows up as HTTP 400 on the upgrade request plus a flood of `WebSocket connection failed` errors in the browser console. [Authentication Troubleshooting → WebSockets](../troubleshooting/authentication.md#400-bad-request-on-the-websocket-endpoint) covers the diagnosis.

---

### Ecosystem/Feed Clients

---
title: Feed Clients
description: URL feeds homebrew installers and frontends
---




# Feed Clients

RomM exposes URL feeds for several homebrew installers and frontends. Point the client at a feed URL and it browses (and installs from) your library over a network. This page collects setup instructions for each supported client.

| Client              | Target hardware            | File format   |
| ------------------- | -------------------------- | ------------- |
| [Tinfoil](#tinfoil) | Nintendo Switch (homebrew) | `.nsp`/`.xci` |
| [pkgj](#pkgj)       | PS Vita/PSP                | `.pkg`        |
| [pkgi](#pkgi)       | PS3/PS Vita/PSP            | `.pkg`        |
| [fpkgi](#fpkgi)     | PS4/PS5 (CFW)              | `.pkg`        |
| [Kekatsu](#kekatsu) | Nintendo DS                | `.nds`        |

## Authentication applies to every feed

Two endpoints are involved on every install: the **feed** (the listing the client fetches) and the **download endpoint** (the per-ROM URLs the feed points at). Both default to requiring basic auth.

- **pkgj and fpkgi** send basic auth on both feed and download requests, so they work with the default `DISABLE_DOWNLOAD_ENDPOINT_AUTH=false`.
- **Tinfoil** authenticates the feed fetch but does _not_ propagate credentials to the download URLs returned in the feed. So the download endpoint has to be opened with `DISABLE_DOWNLOAD_ENDPOINT_AUTH=true`. **Only enable this when RomM isn't directly exposed to the public internet** (see [Download-endpoint auth bypass](../administration/authentication.md#download-endpoint-auth-bypass) for the full security discussion).

## Tinfoil

<div align="center">
    <img src="../../resources/romm/integrations/tinfoil.svg" height="200px" width="200px" alt="RomM Tinfoil logo">
</div>

[Tinfoil](https://tinfoil.io) is Nintendo Switch homebrew for installing software from custom feed URLs. Point it at the Tinfoil feed endpoint, and your Switch library becomes installable from the Switch itself over Wi-Fi.

### Prerequisites

- **`DISABLE_DOWNLOAD_ENDPOINT_AUTH=true`** on your instance, with a container restart applied. Tinfoil sends basic auth to the feed but not to the per-ROM download URLs the feed returns, so the download endpoint has to be open.
- **Valid credentials** for the user whose library you want exposed.
- **Tinfoil installed on the Switch** by following Tinfoil's own docs.
- **A Switch that can reach the server over the network.** Remote reachability requires reverse proxy + cert that the Switch accepts.

### Feed URL

```text
{romm_url}/api/feeds/tinfoil
```

Tinfoil sends your username/password as basic auth to fetch this feed. The download URLs it returns are the part that needs `DISABLE_DOWNLOAD_ENDPOINT_AUTH=true` to be reachable.

### Configuration

1. Launch Tinfoil on the Switch → **File Browser**.
2. Scroll to the file-server list → press `-` (minus) to add a new one.
3. Enter:
    - **Protocol:** `http` or `https` (depending on your reverse-proxy setup)
    - **Host:** hostname or IP
    - **Port:** usually 80 or 443
    - **Path:** `/api/feeds/tinfoil`
    - **Username:** your username
    - **Password:** your password
    - **Title:** anything (e.g. `My Switch`)
    - **Enabled:** yes
4. Press `X` to save.
5. Restart Tinfoil to trigger TitleID scanning and feed parsing.

On reopen, you should see a custom message of the day: `RomM Switch Library`. If you do, it's working!



### Using it

- **New Games** tab in Tinfoil: browseable list of your Switch ROMs
- **File Browser**: pick a file to install directly.

Tinfoil downloads the file (`.nsp`, `.xci`, `.nsz`, `.xcz`, and `.nro` are served), installs to eMMC or SD, and cleans up, just like any homebrew installer.

### Filename requirements

Tinfoil needs **Switch title IDs** in the filenames to parse and categorise games:

```text
Super Mario Odyssey [0100000000010000][v0].nsp
```

The bracketed `[0100000000010000]` is the title ID. Without it, Tinfoil shows the file but doesn't parse it into the New Games tab or match against Switch metadata.



#### Finding title IDs

- [No-Intro](https://datomatic.no-intro.org/) lists them per title
- [tinfoildb.com](https://tinfoildb.com/) and similar databases are searchable
- Pre-organised ROM sets ship with title IDs in filenames already

### Troubleshooting

- **"can't get list: list is empty".** Either your library has no `.nsp`/`.xci` files that Tinfoil recognises, or filenames lack title IDs.
- **Tinfoil connects but nothing in New Games.** Title IDs missing from filenames.
- **Tinfoil can't connect at all.** LAN reachability issue, or wrong port in the feed setup. Try `http://<ip>:<port>/api/feeds/tinfoil` in a browser to view the raw JSON.
- **Downloads fail with 401.** `DISABLE_DOWNLOAD_ENDPOINT_AUTH=true` isn't set, or you forgot to restart the container after setting it.

## pkgj

[pkgj](https://github.com/blastrock/pkgj) is PS Vita homebrew for installing `.pkg`-format games and DLC. Default config points at well-known community URLs but you can point it at feed endpoints instead and install from your library over Wi-Fi.

### Prerequisites

- **PS Vita** with [pkgj](https://github.com/blastrock/pkgj) installed
- A way to edit files on the Vita ([VitaShell](https://github.com/TheOfficialFloW/VitaShell) works well)
- **Reachable from the Vita** (HTTP or HTTPS both work)
- Your games stored as `.pkg` files (it won't work with `.iso` or other formats)

### Feed URLs

| Content       | URL                                      |
| ------------- | ---------------------------------------- |
| PS Vita games | `{romm_url}/api/feeds/pkgj/psvita/games` |
| PS Vita DLCs  | `{romm_url}/api/feeds/pkgj/psvita/dlc`   |
| PSP games     | `{romm_url}/api/feeds/pkgj/psp/games`    |
| PSP DLCs      | `{romm_url}/api/feeds/pkgj/psp/dlc`      |
| PSX games     | `{romm_url}/api/feeds/pkgj/psx/games`    |

### Configuring pkgj

1. Connect the Vita to your PC over USB with VitaShell running.
2. Open `/pkgj/config.txt` on the Vita in a text editor.
3. Append lines for each feed you have content for:

```ini
url_games       {romm_url}/api/feeds/pkgj/psvita/games
url_dlcs        {romm_url}/api/feeds/pkgj/psvita/dlc
url_psp_games   {romm_url}/api/feeds/pkgj/psp/games
url_psp_dlcs    {romm_url}/api/feeds/pkgj/psp/dlc
url_psx_games   {romm_url}/api/feeds/pkgj/psx/games
```

Replace `{romm_url}` with your actual RomM URL (e.g. `https://demo.romm.app`).

4. Save and disconnect from VitaShell.
5. On the Vita: open pkgj → press `△` to open the menu → **Refresh**.

### Using pkgj

Once configured, pkgj shows your PS Vita/PSP library. Select a title and install!

### File format requirements

**Listed in pkgj feeds: `.pkg` files plus compressed archives (`.zip`, `.7z`, etc.) for game entries. DLC stays `.pkg`-only.** If your Vita or PSP games are in `.iso`, `.chd`, or other uncompressed formats, they won't appear in pkgj. If you have non-`.pkg` files you want on the Vita, you'll need to convert them or use a different workflow (FTP through VitaShell, for example).

### Authentication notes

Unlike Tinfoil, pkgj sends basic auth headers natively, so you don't have to turn off download auth to use it. Some users prefer disabling auth for a smoother first-time flow, and either path works.

## pkgi

**pkgi** is the older `.pkg` installer family, predating pkgj.

### Feed URLs

```text
{romm_url}/api/feeds/pkgi/{platform}/{content_type}
```

Where:

- `{platform}` must be one of `ps3`, `psvita`, `psp`
- `{content_type}` for **PS3/PSP** must be one of `game`, `dlc`, `demo`, `update`, `patch`
    - **Vita** also accepts `hack`, `manual`, `mod`, `translation`, `prototype`, and `cheat`

Examples:

```text
{romm_url}/api/feeds/pkgi/ps3/game
{romm_url}/api/feeds/pkgi/ps3/dlc
{romm_url}/api/feeds/pkgi/psp/game
```

Each URL returns a CSV in the format the matching pkgi client expects. The schema differs slightly between PS3/PSP and Vita.

### Configuration

Each pkgi fork has its own `config.txt` location and URL-key names. Consult the client's README. The pattern is the same regardless: drop a URL entry pointing at the feed for each content type you want to browse, then refresh inside the client.

For Vita and PSP, the layout is similar to [pkgj's config](#configuring-pkgj) above. Substitute the pkgi feed URLs for the pkgj ones.

### File format requirements

- `.pkg` files only!
- **PS3 and PSP:** if a `.rap` license file sits as a sibling in the same ROM, its hash and download URL are included in the feed automatically. Without a matching `.rap`, the entry still appears but pkgi can't install it.
- **PS Vita:** the `zRIF` column is left blank in the feed. You need to supply license keys separately (e.g. via NoNpDrm) for installs to succeed.

### Authentication notes

pkgi sends basic auth in its URL config like pkgj does. Either embed credentials in the URL or use `DISABLE_DOWNLOAD_ENDPOINT_AUTH=true` server-side.

### Troubleshooting

- **HTTP 400 on the feed URL.** `{content_type}` isn't valid for the platform. PS3 and PSP only accept `game`, `dlc`, `demo`, `update`, `patch`. Vita is more permissive (see above).
- **Feed is empty.** No `.pkg` files on the platform match the requested content type. Game listings also accept compressed archives, but only as top-level files within a ROM.
- **Install fails on the client.** PS3/PSP need a matching `.rap` file in the same ROM (picked up automatically). Vita additionally needs a zRIF. The feed leaves it blank, so supply it through your client config.

## fpkgi

[fpkgi](https://github.com/CyberYoshi64/fpkgi) is PS4/PS5 homebrew for installing `.pkg` packages from custom URL feeds. fpkgi-compatible feeds are exposed for its PS4 and PS5 libraries.

### Prerequisites

- Games stored as `.pkg` files!
- **PS4 or PS5** with fpkgi installed (requires CFW/jailbreak, and setup is out of scope here)
- **Reachable from the console over Wi-Fi.**

### Feed URL

```text
{romm_url}/api/feeds/fpkgi/{platform_slug}
```

Where `{platform_slug}` is `ps4` or `ps5`.

Example:

```text
https://demo.romm.app/api/feeds/fpkgi/ps4
```

The feed returns JSON in the fpkgi-expected schema: titles, title IDs, content types, and download URLs back to the server.

### Configuring fpkgi

Exact steps depend on the fpkgi version but the gist is:

1. Put the feed URL in fpkgi's config (check fpkgi's docs).
2. Restart fpkgi.
3. The library appears in fpkgi's browse view.

Consult [fpkgi's README](https://github.com/CyberYoshi64/fpkgi) for the current config-file location and format.

### Authentication notes

The `/api/feeds/fpkgi/` endpoints support basic auth the same way `/api/feeds/pkgi/` does. Either set basic-auth credentials in fpkgi's config (if it supports them) or use `DISABLE_DOWNLOAD_ENDPOINT_AUTH=true` on the server.

### File format

fpkgi only installs `.pkg` (PS4 `.pkg` specifically, not `.iso` or compressed), but the feed doesn't filter by extension. Every ROM on the `ps4`/`ps5` platform appears in the listing, so non-`.pkg` entries show up too and will fail at install time. Curate the platform folder if you want to keep them out of the listing.

### Troubleshooting

- **Feed is empty.** No ROMs on the `ps4`/`ps5` platform. Check your library.
- **Downloads fail with 401.** Auth config mismatch, see [Authentication](#authentication-applies-to-every-feed) above.
- **Downloads succeed but install fails.** `.pkg` is for a different firmware version.

## Kekatsu

**Kekatsu** is a Nintendo DS homebrew for loading games from a custom URL feed.

### Prerequisites

- DS games in `.nds` format!
- A Nintendo DS with Kekatsu installed (requires a flashcart or homebrew launcher)
- **Reachable from the DS over Wi-Fi** (the DS's Wi-Fi is WEP/old WPA only)

### Feed URL

```text
{romm_url}/api/feeds/kekatsu/{platform_slug}
```

For standard DS content, the platform slug is `nds`:

```text
https://demo.romm.app/api/feeds/kekatsu/nds
```

### Configuring Kekatsu

Exact config steps depend on your Kekatsu build but the shared concept is "point the app at this URL and it fetches the manifest". Consult Kekatsu's own docs for the current config-file location.

### File format

Kekatsu only loads `.nds`, but the feed doesn't filter by extension. Every ROM on the requested platform appears in the listing, so DSi Ware/iQue/other formats show up too and won't load when selected. Curate the platform folder if you want to keep them out.

### Authentication notes

Kekatsu can send basic auth, either configure it on the DS side or set `DISABLE_DOWNLOAD_ENDPOINT_AUTH=true` in the environment variables.

### Why the legacy-Wi-Fi hassle

The DS's original Wi-Fi hardware supports WEP and an older WPA variant only, while modern home routers usually don't. Workarounds:

- **Dedicated DS-friendly SSID.** Many routers allow per-SSID security, so add a WEP one just for the DS.
- **Travel router in bridge mode.** A cheap travel router configured for WEP uplinks to your main (secure) network.
- **Use a DSi, 3DS, or homebrew replacement driver.** These support secure connection standards.

If none of this is appealing, Kekatsu-over-LAN isn't going to work. Fall back to sideloading via flashcart or similar.

### Troubleshooting

- **Feed is empty.** No ROMs on the `nds` platform
- **DS can't see the network.** See the legacy-Wi-Fi section above.
- **Downloads fail.** Either network timeout (LAN latency over WEP is rough) or disk space. Retry one game at a time.

## See also

- [Authentication → Download-endpoint auth bypass](../administration/authentication.md#download-endpoint-auth-bypass): the `DISABLE_DOWNLOAD_ENDPOINT_AUTH` caveat

---

### Ecosystem/First Party Apps

---
title: First-Party Apps
description: Official clients for Android, Windows, and Linux handhelds.
---




# First-Party Apps

These are the only clients built and maintained by the team. Pick the one(s) that matches your device(s):

| App                                 | Platform                                    |
| ----------------------------------- | ------------------------------------------- |
| [Argosy Launcher](#argosy-launcher) | Android (AYN Thor, Retroid, etc.)           |
| [Grout](#grout)                     | Linux (muOS, MinUI, NextUI, etc.)           |
| [Playnite Plugin](#playnite-plugin) | Windows ([Playnite](https://playnite.link)) |

For third-party clients, see the [Community section in the README](https://github.com/rommapp/romm/#community).

## Argosy Launcher

**Argosy Launcher** is our first-party Android app: browse your library, download ROMs on the fly, and launch into RetroArch or your emulator of choice.

<div align="center">
    <img src="../../resources/romm/apps/argosy.png" alt="Argosy Launcher screenshot" style="max-width: 600px; width: 100%;">
</div>

- **Repo:** [rommapp/argosy-launcher](https://github.com/rommapp/argosy-launcher)
- **Language:** Kotlin
- **License:** GPL-3.0
- **Platforms:** Android

### What it does

- Browses your full library from an Android device
- Handles authentication via [Client API Tokens](../developers/client-api-tokens.md), paired over a short code so you don't type a 44-character string
- Downloads ROMs on demand to your device's storage
- Launches RetroArch (or another configured emulator) with the downloaded ROM
- Syncs saves/states back to RomM when you finish a session (optional)

### Setup

See [Getting Started](https://github.com/rommapp/argosy-launcher#getting-started) in the Argosy repo for install and pairing instructions.

## Grout

**Grout** is our first-party companion for Linux-based handhelds, specifically [muOS](https://muos.dev) and [NextUI](https://github.com/mattsays/nextui). Syncs ROMs, saves, and states bidirectionally with your instance over Wi-Fi.

<div align="center">
    <img src="../../resources/romm/apps/grout.png" alt="Grout screenshot" style="max-width: 600px; width: 100%;">
</div>

- **Repo:** [rommapp/grout](https://github.com/rommapp/grout)
- **Language:** Go
- **License:** MIT
- **Platforms:** muOS (Anbernic and similar ARM handhelds), NextUI

### What it does

- Connects to your instance using a [Client API Token](../developers/client-api-tokens.md)
- **Pulls** ROMs from your instance to the handheld's SD card, organised into muOS/NextUI's expected folder layout
- **Pushes** saves and states back to your instance when you finish a session
- **Schedules** sync runs: on idle, on session end, or on a cron
- Works fully offline between syncs, so the handheld doesn't need your instance to play

### Setup

See [Getting Started](https://grout.romm.app/getting-started/) in the Grout docs for install and sync configuration instructions.

## Playnite Plugin

<div align="center">
    <img src="../../resources/romm/integrations/playnite.svg" height="200px" width="200px" alt="romm[playnite] logo">
</div>

[Playnite](https://playnite.link) is a unified, open-source game library manager for Windows: one place to launch Steam, Epic, GOG, RetroArch, and emulated games. This plugin imports your library into Playnite, so your ROMs appear alongside your Steam games.

<div align="center">
    <img src="../../resources/romm/apps/playnite.png" alt="Playnite Plugin screenshot" style="max-width: 600px; width: 100%;">
</div>

- **Repo:** [rommapp/playnite-plugin](https://github.com/rommapp/playnite-plugin)
- **Language:** C#
- **License:** GPL-3.0
- **Platforms:** Windows (Playnite)

### What it does

- Queries the API to pull your library metadata
- Creates Playnite library entries for every game
- Downloads a ROM on demand when you click **Install** in Playnite
- Launches via your configured emulator (using Playnite's existing emulator config)

### Setup

#### Install the plugin

Install through any of these methods:

- **Direct launch:** open `playnite://playnite/installaddon/RomM_9700aa21-447d-41b4-a989-acd38f407d9f` in your browser
- **In-app:** go to **Menu → Add-ons → Browse → Libraries**, search for **RomM**, and select **Install**
- **Add-ons website:** download it from the [Playnite add-ons portal](https://playnite.link/addons.html)
- **Manual:** download the `.pext` file from the [releases page](https://github.com/rommapp/playnite-plugin/releases) and drag it onto Playnite

#### Configure an emulator

You need at least one emulator installed and configured in Playnite before the plugin can launch anything, so add one under **Menu → Library → Configure Emulators → Add emulator** if you haven't already.

#### Connect to your instance

Open **Menu → Library → Configure Integrations → RomM** and enter:

- **Host URL**, including the protocol and without a trailing slash, for example `https://romm.example.com`
- Your **username** and **password**

Passwords are stored in plaintext in Playnite, so use a separate account with a **read-only permission group** rather than your main credentials.

#### Map emulator paths

For each platform you want to import, add a mapping with these fields:

- **Emulator:** a built-in or custom emulator
- **Emulator Profile:** the matching profile for that emulator
- **Platform:** the console or platform to map
- **Destination Path:** where downloaded ROMs are stored, for example `C:\roms\gc`
- **Auto-extract:** whether to automatically extract compressed files

#### Import your library

Select **Menu → Library → Import RomM library**. Every game matching your emulator path mappings is imported into Playnite, downloaded to its destination path on demand, and launched through the configured emulator.

## See also

- [Client API Tokens](../developers/client-api-tokens.md): the auth + pairing flow some of these clients use
- [Community section in the README](https://github.com/rommapp/romm/#community): third-party clients

---

### Ecosystem/Igir

---
title: Igir Collection Manager
description: Clean up and normalise your ROM collection
---

# Igir Collection Manager

[Igir](https://igir.io/) is a zero-setup ROM collection manager that sorts, filters, extracts, archives, patches, and reports on collections of any size. While not a companion app per se, it's useful for cleaning up a library _before_ importing into RomM, so scans have a better-named, better-organised starting point.

**This is not an official app.** Igir is a separate community project, but we document integration here because it's a common workflow and produces a compatible layout directly.

## When you'd use Igir

- You have a messy collection with inconsistent naming, mixed formats, dumps from multiple sources.
- You want to **match against No-Intro/Redump DAT files** to verify authenticity and standardise names.
- You want to **filter** only retail releases, or strip out hacks, or keep only one region, etc.
- You want to move/rename files to the expected platform folder layout.

## Directory setup

Igir works on a copy of your ROMs (never in place) to let you iterate on its config without risking the originals.

```text
.
├── dats/                 # DAT files (No-Intro, Redump)
├── roms/                 # Your original ROM collection (untouched)
├── roms-unverified/      # Working copy Igir will process
└── igir-romm-cleanup.sh  # the script below
```

1. Make a working copy

```sh
cp -r roms/ roms-unverified/
```

2. Download DAT files

DAT files are hash-referenced catalogues Igir matches against.

- **Cartridge systems:** [No-Intro daily](https://datomatic.no-intro.org/index.php?page=download&op=daily), full DAT compilation
- **Optical systems (PS1, Saturn, etc.):** [Redump](http://redump.org/downloads/), per-platform DAT files

Drop the DAT files into `dats/`. You can use a subset if you only care about specific platforms.

## The cleanup script

Save as `igir-romm-cleanup.sh`:

```bash
#!/usr/bin/env bash
set -ou pipefail
cd "$(dirname "${0}")"

INPUT_DIR=roms-unverified
OUTPUT_DIR=roms-verified

# https://igir.io/
# DAT files: https://datomatic.no-intro.org/index.php?page=download&op=daily
time npx -y igir@latest \
  move \
  extract \
  playlist \
  report \
  test \
  -d dats/ \
  -i "${INPUT_DIR}/" \
  -o "${OUTPUT_DIR}/{romm}/" \
  --input-checksum-quick false \
  --input-checksum-min CRC32 \
  --input-checksum-max SHA256 \
  --only-retail \
  --merge-discs
```

Make it executable:

```sh
chmod +x igir-romm-cleanup.sh
```

## Run

```sh
./igir-romm-cleanup.sh
```

## Manually migrate leftovers

Some ROMs won't be identified (homebrew, hacks with `--only-retail`, truly unknown dumps). Move them manually preserving the folder shape:

```sh
npx -y igir@latest \
  move \
  -i roms-unverified/ \
  -o roms-verified/ \
  --dir-mirror
```

This keeps the original subfolder structure but normalises extensions.

## Multi-disc games

Redump and No-Intro catalogue each disc of a multi-disc game as a separate game, so by default Igir writes them out as sibling folders — which confuses multi-file game detection. Two parts of the script above handle this, no manual reorganisation needed:

- `--merge-discs` groups the discs of a game back into a single folder.
- The `playlist` command writes an `.m3u` alongside them.

Before:

```text
Final Fantasy VII (USA) (Disc 1)/
Final Fantasy VII (USA) (Disc 2)/
Final Fantasy VII (USA) (Disc 3)/
```

After:

```text
Final Fantasy VII (USA)/
  Final Fantasy VII (USA) (Disc 1)/
  Final Fantasy VII (USA) (Disc 2)/
  Final Fantasy VII (USA) (Disc 3)/
  Final Fantasy VII (USA).m3u
```

The `.m3u` is a playlist RomM respects for launching multi-disc games. It holds a relative path to each disc's playable file, in disc order:

```text
Final Fantasy VII (USA) (Disc 1)/Final Fantasy VII (USA) (Disc 1).cue
Final Fantasy VII (USA) (Disc 2)/Final Fantasy VII (USA) (Disc 2).cue
Final Fantasy VII (USA) (Disc 3)/Final Fantasy VII (USA) (Disc 3).cue
```

A few things worth knowing:

- A playlist points at each disc's playable file, so discs can't be sitting inside zip archives — that's why the script uses `extract` rather than `zip` for these platforms. The extensions Igir will reference default to `.ccd`, `.cdi`, `.chd`, `.cue`, `.gdi`, `.iso`, `.mdf`, and `.toc`, adjustable with `--playlist-extensions`.
- CHDs need no special handling to appear in a playlist, though the script as written will unpack them — see [Keeping CHDs as CHDs](#keeping-chds-as-chds).
- Playlists are only written for multi-disc games. If you want one for every game, add `--playlist-mode always`.
- `--merge-discs` doesn't require DAT files, but is far more reliable with them — the script already passes `-d dats/`.
- Some TOSEC-catalogued discs won't merge, because the ring/box codes used to distinguish separate pressings can't be told apart from other metadata programmatically. See Igir's [merging limitations](https://igir.io/roms/sets/#merging-limitations).

## Keeping CHDs as CHDs

Igir reads inside a CHD to identify its tracks, but `extract` will unpack it into those tracks — `.cue`/`.bin`, or `.gdi` — rather than leaving the CHD intact. This applies to single-disc games as much as multi-disc ones.

`extract` applies to the whole run, so dropping it to protect your CHDs would also stop cartridge ROMs being unzipped. Split the run in two instead, excluding CHDs from the pass that extracts and handling them in a second pass that copies them through untouched:

```bash
# Everything except CHDs, extracted
npx -y igir@latest \
  move extract playlist report test \
  -d dats/ \
  -i "${INPUT_DIR}/" \
  -I "${INPUT_DIR}/**/*.chd" \
  -o "${OUTPUT_DIR}/{romm}/" \
  --only-retail \
  --merge-discs

# CHDs, left as they are
npx -y igir@latest \
  move playlist report test \
  -d dats/ \
  -i "${INPUT_DIR}/**/*.chd" \
  -o "${OUTPUT_DIR}/{romm}/" \
  --only-retail \
  --merge-discs
```

Each game's discs are either all CHDs or all not, so disc grouping and playlists still come out right despite the split.

Matching CHDs against DATs is slower on the first run, since a CHD carries only a SHA1 rather than per-file CRC32. Igir caches the results, so subsequent runs are much faster.

## Importing

Once `roms-verified/` looks right, mount it as the library:

```yaml
services:
    romm:
        volumes:
            - /path/to/roms-verified:/romm/library/roms:ro
```

Read-only is safer: if you need Igir to re-clean, work in a parallel folder and re-promote it to `roms-verified/`. Once you run a scan from RomM, and everything should match cleanly against providers!

## See also

- [Igir docs](https://igir.io/)
- [Folder Structure](../getting-started/folder-structure.md)

---

### Ecosystem/Index

---
title: Integrations & Ecosystem
description: Companion apps, feeds, and protocol references
---

# Integrations & Ecosystem

RomM has a sizeable ecosystem of companion apps and integration patterns.

## First-party apps

Maintained by the team:

- **[Argosy Launcher](first-party-apps.md#argosy-launcher)**: Android launcher that browses and launches your library on mobile
- **[Grout](first-party-apps.md#grout)**: Linux handheld companion for muOS/NextUI devices
- **[Playnite Plugin](first-party-apps.md#playnite-plugin)**: Windows desktop, imports your library into [Playnite](https://playnite.link)

## Feeds (for third-party apps)

RomM exposes several URL feed endpoints for external homebrew/custom firmware apps that already know how to consume them.

- **[Tinfoil](feed-clients.md#tinfoil)**: Nintendo Switch homebrew for installing `.nsp`/`.xci` from a URL
- **[pkgj](feed-clients.md#pkgj)**: PS Vita and PSP homebrew installer
- **[pkgi](feed-clients.md#pkgi)**: PS3/PS Vita/PSP installer (older CSV format)
- **[fpkgi](feed-clients.md#fpkgi)**: PS4/PS5 installer
- **[Kekatsu](feed-clients.md#kekatsu)**: Nintendo DS multiboot loader

## Community apps

Maintained by individuals in the community, not the team, so support quality varies.

See the **[Community section in the README](https://github.com/rommapp/romm/#community)** for the full list with status flags (active/maintenance-mode/abandoned) and links.

Highlights:

- **romm-ios-app** (iOS native)
- **romm-mobile** (Android + iOS)
- **RommBrowser** (Electron desktop)
- **RomMate** (desktop)
- **romm-client** (desktop)
- **DeckRommSync** (Steam Deck)
- **SwitchRomM** (Nintendo Switch homebrew NRO)
- **RetroArch Sync**
- **romm-comm** (Discord bot)
- **GGRequestz** (game request tracker)

## Build your own

For developers building something new on top of RomM:

- **[Client API Tokens](../developers/client-api-tokens.md)**: how to authenticate your app, how the device-pairing flow works
- **[Device Sync Protocol](../developers/device-sync-protocol.md)**: wire-level reference for save/state/play-session sync
- **[SSH Sync](../developers/ssh-sync.md)**: server-side SSH config for push/pull sync to handhelds
- **[API Reference](../developers/api-reference.md)**: every REST endpoint
- **[WebSockets](../developers/websockets.md)**: live-update channels and Netplay coordination
- **[Consuming OpenAPI](../developers/openapi.md)**: codegen patterns

## External tooling

Not a companion app but useful:

- **[Igir Collection Manager](igir.md)**: ROM sorting/verifying tool that cleans up library layout

## Contributing a companion app

Built something adjacent? Open a PR on [rommapp/romm](https://github.com/rommapp/romm) adding it to the [Community section in the README](https://github.com/rommapp/romm/#community), or drop a link in the [Discord](https://discord.gg/romm) `#community-projects` channel.

We list active, maintained projects, with no gate on code quality, but we do flag abandoned projects so users know what's current.

---

### Getting Started/First Scan

---
title: Your First Scan
description: Populate a fresh install by scanning the library for the first time
---

# Your First Scan

You're up and running ([Quick Start](quick-start.md)), your ROMs are laid out correctly ([Folder Structure](folder-structure.md)), and metadata credentials are configured ([Metadata Providers](metadata-providers.md)). Time to catalogue everything!

## Before you hit scan

A fifteen-second check that saves hours:

- **Library is mounted**: on the host, `ls /path/to/library` should show your `roms/` (or per-platform) folders. If it doesn't, the mount is wrong.
- **At least one metadata provider is configured**: scans run without one but every game comes back "unmatched" and you'll have nothing useful to look at.

## Run the scan

Trigger a scan from the web UI:

- Pick which metadata sources to query
- Use the **Quick** mode for the first run
- Start the scan

A running scan survives browser refreshes and you can leave and come back later. Per-platform progress shows counts updating live (total found, matched, unmatched), so you can dip in and inspect matched ROMs while the scan continues.

First scans on big libraries take a while: expect ~4 seconds per ROM with a fast network to IGDB/ScreenScraper, and hashing (which runs unless you disabled it) adds IO time proportional to file size.

## What "matched" means

For each ROM the scanner:

1. **Computes hashes** (CRC32, MD5, SHA1, plus RetroAchievements-specific hashes).
2. **Hits the configured metadata providers** in priority order. First provider to recognise the file (by hash or filename) becomes the initial match.
3. **Writes the DB entry** with title, cover, description, release date, and anything else the providers returned.
4. **Merges overlay data** from other providers: RetroAchievements progression, HowLongToBeat completion times, SteamGridDB alternate covers if you've asked.

An **unmatched** ROM means no provider recognised it, with common causes:

- Filename is too generic (`game.gba`)
- Platform folder misnamed
- Bad rip, intro/patch applied, or a regional variant no provider has indexed
- Metadata provider credentials wrong or rate-limited

Most of these are fixable, see [Scanning Troubleshooting](../troubleshooting/scanning.md).

## When the scan finishes

Your dashboard surfaces a card per scanned platform plus recently-added and continue-playing rows.

Typical next steps:

- **Fix unmatched ROMs**: rename or re-tag, then re-run an **Unmatched** scan to pick them up (see [Scanning & Watcher](../administration/scanning-and-watcher.md#scan-modes)).
- **Tweak priorities**: if ScreenScraper's covers are nicer than IGDB's for your library, reorder `scan.priority.artwork` in [`config.yml`](../reference/configuration-file.md).
- **Switch boxart styles**: want 3D boxes, physical media, or mix images on your cards? That needs the matching media type added to `scan.media` and a rescan, not just the UI picker. See [Boxart styles and media types](metadata-providers.md#boxart-styles-and-media-types).

## Skip to a targeted scan

If you're adding ROMs later and don't want a full rescan:

- **New Platforms**: only scans folders not seen before, and it's fast.
- **Quick**: skips ROMs already catalogued, a good default for "I added a few games".
- **Unmatched**: re-runs matching against ROMs without a provider ID, ideal after adding a metadata provider.

All six scan modes are documented in [Scanning & Watcher](../administration/scanning-and-watcher.md#scan-modes).

---

### Getting Started/Folder Structure

---
title: Folder Structure
description: How to organise your library on disk
---



# Folder Structure

RomM expects your library to be organised in one of two layouts. It tries **Structure A** first, and falls back to **Structure B** if A isn't found. This auto-detection is per-library (not per-platform), so if you don't pick one up front, just arrange files the way you prefer and it'll figure it out.

## The two layouts

Both layouts separate ROMs from BIOS files, and they differ on whether the split lives at the top of the tree or inside each platform.

- **Structure A (recommended)**: one top-level `roms/`, one top-level `bios/`, platforms nested inside each

```text
/roms/{platform}/
/bios/{platform}/
```

- **Structure B (fallback)**: one folder per platform at the top, `roms/` and `bios/` inside each

```text
/{platform}/roms/
/{platform}/bios/
```

As the BIOS/firmware tree is **optional**, only platforms that require firmware for emulation need it.

### Mount point

The path you mount into the container as `/romm/library` depends on which structure you pick:

- **Structure A**: mount the parent of the `roms/` folder.
- **Structure B**: mount the parent of the platform folders.

See the [reference Docker Compose](quick-start.md) for where `/romm/library` lives.


!!! tip "Platform folder names"
    The platform folder name has to match a known slug from the full list in [Supported Platforms](../platforms/supported-platforms.md). If your existing folder names don't match (say, `super_nintendo/` instead of `snes/`), override the mapping via `system.platforms` in [`config.yml`](../reference/configuration-file.md).

## Multi-file games

Some games come as **folders** instead of single files, which could include multiple disc, DLCs, manuals, or patches. These sub-folder names are recognised and surfaced as tags in the UI: `dlc`, `hack`, `manual`, `mod`, `patch`, `update`, `demo`, `translation`, `prototype`, `screenshots`.

## Visual reference

<table>
<tr>
    <th style="text-align: center"><b>Structure A (recommended)</b></th>
    <th style="text-align: center"><b>Structure B (fallback)</b></th>
</tr>
<tr>
    <td style="text-align: center">
        <code>library/roms/{platform}/{game}</code>
    </td>
    <td style="text-align: center">
        <code>library/{platform}/roms/{game}</code>
    </td>
</tr>
<tr>
    <td>
        <pre style="font-size: 0.85em;">
        library/
        ├─ roms/
        │  ├─ gbc/
        │  │  ├─ game_1.gbc
        │  │  └─ game_2.gbc
        │  │
        │  ├─ gba/
        │  │  ├─ game_3.gba
        │  │  └─ game_4/
        │  │     ├─ game_4.gba
        │  │     ├─ dlc
        │  │     │  ├─ game_4_dlc_1.7z
        │  │     │  └─ game_4_dlc_2.7z
        │  │     ├─ hack
        │  │     │  └─ game_4_hardmode.rar
        │  │     ├─ manual
        │  │     │  └─ game_4_manual.pdf
        │  │     ├─ mod
        │  │     │  └─ game_4_crazy_mode.zip
        │  │     ├─ patch
        │  │     │  └─ game_4_patch_v1.1.zip
        │  │     ├─ update
        │  │     ├─ demo
        │  │     ├─ translation
        │  │     ├─ prototype
        │  │     └─ screenshots
        │  │
        │  └─ ps/
        │     ├─ game_5/
        │     │   ├─ game_5_cd_1.iso
        │     │   └─ game_5_cd_2.iso
        │     │
        │     └─ game_6.iso
        │
        └─ bios/
           ├─ gba/
           │  └─ gba_bios.bin
           │
           └─ ps/
              ├─ scph1001.bin
              ├─ scph5501.bin
              └─ scph5502.bin
        </pre>
    </td>
    <td>
        <pre style="font-size: 0.85em;">
        library/
        ├─ gbc/
        │  └─ roms/
        │     ├─ game_1.gbc
        │     └─ game_2.gbc
        │
        ├─ gba/
        │  ├─ roms/
        │  │  ├─ game_3.gba
        │  │  └─ game_4/
        │  │     ├─ game_4.gba
        │  │     ├─ dlc
        │  │     ├─ hack
        │  │     ├─ manual
        │  │     ├─ mod
        │  │     ├─ patch
        │  │     ├─ update
        │  │     ├─ demo
        │  │     ├─ translation
        │  │     ├─ prototype
        │  │     └─ screenshots
        │  │
        │  └─ bios/
        │     └─ gba_bios.bin
        │
        └─ ps/
           ├─ roms/
           │  ├─ game_5/
           │  │  ├─ game_5_cd_1.iso
           │  │  └─ game_5_cd_2.iso
           │  │
           │  └─ game_6.iso
           │
           └─ bios/
              ├─ scph1001.bin
              ├─ scph5501.bin
              └─ scph5502.bin
        </pre>
    </td>
</tr>
</table>


!!! note "Starting from scratch?"
    If you upload files through the web UI without any existing structure, it'll create **Structure A** on your behalf.

## Naming convention

Filenames are parsed for region, language, revision, and arbitrary tags, with both `[]` and `()` delimiters supported:

- **Region/language**: both ISO-like codes and full names. Add a custom region or language by prefixing with `reg`/`reg-` (e.g. `reg MyOwnLang` or `reg-MyOwnLang`).
- **Revision**: prefix with `rev`/`rev-` (e.g. `rev v1`, `rev-1`)
- **Arbitrary tags**: anything else in brackets is imported verbatim (e.g. `tetris [1.0001](HACK)[!].gba`)

Inline tags like `(igdb-1234)` in filenames can be used to force a match to a specific provider entry, covered in [Metadata Providers → Filename tags](metadata-providers.md#metadata-tags-in-filenames).

<div class="grid cards" markdown>

<div markdown>

### Supported languages

| Code   | Language    |
| ------ | ----------- |
| Ar     | Arabic      |
| Da     | Danish      |
| De     | German      |
| El     | Greek       |
| En     | English     |
| Es     | Spanish     |
| Fi     | Finnish     |
| Fr     | French      |
| It     | Italian     |
| Ja     | Japanese    |
| Ko     | Korean      |
| Nl     | Dutch       |
| No     | Norwegian   |
| Pl     | Polish      |
| Pt     | Portuguese  |
| Ru     | Russian     |
| Sr     | Serbian     |
| Sv     | Swedish     |
| Zh     | Chinese     |
| nolang | No Language |

</div>

<div markdown>

### Supported regions

| Code | Region        |
| ---- | ------------- |
| A    | Australia     |
| AS   | Asia          |
| B    | Brazil        |
| C    | Canada        |
| CH   | China         |
| E    | Europe        |
| F    | France        |
| FN   | Finland       |
| G    | Germany       |
| GR   | Greece        |
| H    | Holland       |
| HK   | Hong Kong     |
| I    | Italy         |
| J    | Japan         |
| K    | Korea         |
| NL   | Netherlands   |
| NO   | Norway        |
| PD   | Public Domain |
| R    | Russia        |
| S    | Spain         |
| SW   | Sweden        |
| T    | Taiwan        |
| U    | USA           |
| UK   | England       |
| UNK  | Unknown       |
| UNL  | Unlicensed    |
| W    | World         |

</div>

</div>

---

### Getting Started/Metadata Providers

Multiple metadata providers are supported to enrich your game library with titles, descriptions, cover art, and achievements. You don't need all providers, so this guide covers [popular combos](#popular-combos) and [setup instructions](#setup-instructions).

## Popular combos

Here are some combinations you can use based on your needs:

#### ⭐ The French Connection: [ScreenScraper](#screenscraper) + [Retroachievements](#retroachievements)

- Supports 125+ popular systems
- ScreenScraper provides titles, descriptions, cover art, screenshots and manuals
    - Also supports hash-based matching (as of `v4.4`)
    - With the option for 3D boxes and CD/cartridge covers
- Retroachievements provides achievement progress
- **Use this if you want to avoid Twitch/Amazon products**



#### ⭐ The Chef's Choice: [Hasheous](#hasheous) + [IGDB](#igdb) + [SteamGridDB](#steamgriddb) + [Retroachievements](#retroachievements)

- Supports 135+. popular systems
- Hasheous provides hash-based matching and proxies IGDB data (titles, descriptions and artwork)
- IGDB adds additional metadata like related games and screenshots
- SteamGridDB provides high-quality alternative cover art
- Retroachievements provides achievement progress
- **This is the recommended setup for most users**



#### The Twitch Fanboy: [IGDB](#igdb) + [Playmatch](#playmatch)

- Supports the 200+ systems available on IGDB
- Provides titles, descriptions, cover art and related games from IGDB
- Playmatch adds hash-based matching for unmatched files
- **Use this if you want a single-provider solution**

#### The Quick Starter: [Hasheous](#hasheous)

- Hash-based matching only ⚠️
- Proxies titles, descriptions and cover art from IGDB
- Incredibly fast scan times
- **For users who want to avoid API keys**

## Setup instructions

### IGDB

[IGDB](https://www.igdb.com/) (Internet Game Database) is a popular metadata provider that offers metadata, cover art, screenshots, related games and more.

To access the IGDB API you'll need a Twitch account and a valid phone number for 2FA verification. Up-to-date instructions are available in the [IGDB API documentation](https://api-docs.igdb.com/#account-creation). When registering your application in the Twitch Developer Portal, fill out the form like so:

- Name: Something **unique or random** like `romm-3fca6fd7f94dea4a05d029f654c0c44b` or `KVV8NDXMSRFJ2MRNPNRSL7GQT`
- OAuth Redirect URLs: `localhost`
- Category: `Application Integration`
- Client Type: `Confidential`


!!! important
    The name you pick has to be unique! Picking an existing name will fail silently, with no error messages. We recommend using `romm-<random hash>`, like `romm-3fca6fd7f94dea4a05d029f654c0c44b`

Note the client ID and secret that appear on screen, and use them to set `IGDB_CLIENT_ID` and `IGDB_CLIENT_SECRET` in your environment variables.


??? Screenshots
    
    

### ScreenScraper

[ScreenScraper.fr](https://screenscraper.fr/) is a French provider that offers metadata, cover art, screenshots and manuals, along with the option for 3D boxes and CD/cartridge cover art. It supports a wide range of systems and is a great alternative to IGDB.

To access the ScreenScraper API, create a [ScreenScraper](https://www.screenscraper.fr/membreinscription.php) account and copy the **user** and **password** you just created to `SCREENSCRAPER_USER` and `SCREENSCRAPER_PASSWORD` respectively.

### MobyGames

MobyGames is a metadata provider that offers metadata, cover art and screenshots.

To access the MobyGames API, [create a MobyGames account](https://www.mobygames.com/user/register/) and then visit your profile page. Click the **API** link under your user name to sign up for an API key. Copy the key shown and use it to set `MOBYGAMES_API_KEY`.


!!! important
    Access to the MobyGames API is a [paid feature](https://www.mobygames.com/info/api/#non-commercial). While we will continue to support it, we recommend using [ScreenScraper](#screenscraper) instead, as it is free to use.

### LaunchBox

The [LaunchBox](https://gamesdb.launchbox-app.com/) Games Database is a community-driven database that provides metadata, cover art, and screenshots. Like the Launchbox desktop application, the entire database is downloaded locally and matches games based on their exact filenames.

To enable LaunchBox, set `LAUNCHBOX_API_ENABLED=true` and `ENABLE_SCHEDULED_UPDATE_LAUNCHBOX_METADATA=true` in your environment variables. You can customize scheduled updates of the database by setting the frequency on the cron job with `SCHEDULED_UPDATE_LAUNCHBOX_METADATA_CRON` (defaults to 5:00 AM every day).

You must run a LaunchBox metadata update (either manually, or scheduled via cron) to generate a local `.xml` file with Launchbox metadata before using it as a metadata provider. The server will parse the local `.xml` file when trying to match a ROM and fetch metadata from this source.

### Hasheous

[Hasheous](https://hasheous.org/) is a free, open-source metadata provider that uses file hashes to match games. It proxies IGDB data for titles, descriptions, and cover art, and can provide Retroachievements IDs for matched games.

Simply set `HASHEOUS_API_ENABLED=true` in your environment variables, and future scans will start using the [Hasheous API](https://hasheous.org/swagger/index.html).

### Playmatch

[Playmatch](https://github.com/RetroRealm/playmatch) is a free, open source and community driven hash based matching service supporting multiple metadata providers such as IGDB, ScreenScraper, SteamGridDB, Retroachievements and more, hosted by a member of our community.

To enable Playmatch, set `PLAYMATCH_API_ENABLED=true` in your environment variables.

When Playmatch is enabled, manually matching a ROM through the edit dialog also forwards the ROM's hashes, filename, filesize and resolved provider IDs as a suggestion to Playmatch. Suggestions are reviewed manually before being added to the Playmatch database, which helps improve match quality for the wider community over time.

By default RomM talks to the community-hosted Playmatch instance. To point at your own [self-hosted Playmatch](https://github.com/RetroRealm/playmatch), set `PLAYMATCH_API_URL` to its API base (e.g. `https://playmatch.example.com/api/v2`).

### SteamGridDB

SteamGridDB provides custom cover art for games or collections. It's not accessed through the scanner but from the "search cover" button when manually editing a game.

To access the SteamGridDB API, you need to login to their [website](https://www.steamgriddb.com/) with a [Steam account](https://store.steampowered.com/join). Once logged in, go to your [API tab under the preferences page](https://www.steamgriddb.com/profile/preferences/api). Copy the key shown and use it to set `STEAMGRIDDB_API_KEY`.

### RetroAchievements

Achievements are displayed from [RetroAchievements](https://retroachievements.org/). To sync, you need to generate an API key from your RetroAchievements account in your [settings](https://retroachievements.org/settings).

Copy the key shown and use it to set `RETROACHIEVEMENTS_API_KEY` and perform a `UNMATCHED` scan targeting the platform you want to match with RetroAchievements.

After that, each user needs to set their own username in their profile and sync it with RetroAchievements. A new `Achievements` tab will appear in the `Personal` tab in the game details.

To avoid unnecessary API calls, a cached file with the RA database is stored locally. Refresh time for that cache file can be changed with the environment variable `REFRESH_RETROACHIEVEMENTS_CACHE_DAYS`.


??? Screenshots
    
    

### Flashpoint

The [Flashpoint Project Database](https://flashpointproject.github.io/flashpoint-database/) is a project that enables metadata for 180,000+ flash and browser-based games. Enable this metadata source with the `FLASHPOINT_API_ENABLED=true` environment variable. If you are adding this provider to an existing setup, perform a `UNMATCHED` scan with Flashpoint selected to update an existing platform.

### HowLongToBeat

The [HowLongToBeat](https://howlongtobeat.com/) project provides game completion times for more than 84,000 games. Enable this metadata source with the `HLTB_API_ENABLED=true` environment variable. If you are adding this provider to an existing setup, perform a `UNMATCHED` scan with HowLongToBeat selected to update an existing platform.

Game completion times will be added to a new tab on the details page for supported matched games.

### ES-DE gamelist.xml

EmulationStation, and its modern successor ES-DE, use a custom XML format to store game metadata. RomM parses this format and imports the assets as cover art and screenshots. You'll need to store the gamelist.xml file and any related assets under the platform folder:


```yaml
library/
└─ roms/
    └─ gba/
        ├─ game_1.gba
        ├─ game_2.gba
        ├─ gamelist.xml
        ├─ 3dboxes/
        │  ├─ game_1.png
        │  └─ game_2.png
        ├─ covers/
        ├─ screenshots/
        └─ etc...
```


```xml
<?xml version="1.0"?>
<gameList>
	<game id="12345">
        
		<path>./game.gba</path>

        
		<name>Game Title</name>
		<desc>A fun game to play</desc>
		<lang>en</lang>
		<region>USA</region>

        
        <rating>0.8</rating>
        <releasedate>19990615T000000</releasedate>
        <developer>Developer Inc.</developer>
        <publisher>Publisher Co.</publisher>
        <family>Game Series</family>
        <genre>Action</genre>
        <players>1-2</players>
        <md5>f1234567890abcdef1234567890abcde</md5>

        
        <image>./images/game.png</image>
        <cover>./covers/game.png</cover>
        <backcover>./backcovers/game.png</backcover>
        <box3d>./3dboxes/game.png</box3d>
        <fanart>./fanart/game.png</fanart>
        <manual>./manuals/game.pdf</manual>
        <marquee>./marquees/game.png</marquee>
        <miximage>./miximages/game.png</miximage>
        <physicalmedia>./physicalmedia/game.png</physicalmedia>
        <screenshot>./screenshots/game.png</screenshot>
        <title_screen>./titlescreens/game.png</title_screen>
        <thumbnail>./thumbnails/game.png</thumbnail>
        <video>./videos/game.mp4</video>
	</game>
	<game id="54321">
        ...
	</game>
    ...
</gameList>
```

#### ES-DE metadata

Here are the text properties that will be read from `gamelist.xml`.

| Property Name | Description                      |
| ------------- | -------------------------------- |
| name          | Game title                       |
| desc          | Game description or synopsis     |
| lang          | Game language (en, es, it, etc.) |
| region        | Game region (us, eu, jp, etc.)   |
| rating        | Game rating score                |
| releasedate   | Game release date                |
| developer     | Developer company                |
| publisher     | Publisher company                |
| family        | Game franchise or series         |
| genre         | Game category or type            |
| players       | Number of players supported      |
| md5           | ROM file hash identifier         |

#### ES-DE media

There are two ways media files are mapped: first it looks at `gamelist.xml` for properties, and it falls back to looking at nested folders for images that have the same name as the ROM.

| Property Name | Folder Name   | Description                            |
| ------------- | ------------- | -------------------------------------- |
| image         | images        | General game image                     |
| cover         | covers        | Front cover artwork                    |
| backcover     | backcovers    | Back cover artwork                     |
| box3d         | 3dboxes       | 3D box artwork                         |
| fanart        | fanart        | Fan-made artwork                       |
| manual        | manuals       | Game instruction manual                |
| marquee       | marquees      | Arcade game marquee or header          |
| miximage      | miximages     | Composite or mixed artwork             |
| physicalmedia | physicalmedia | Physical media (cartridge, disc, etc.) |
| screenshot    | screenshots   | In-game screenshot                     |
| title_screen  | titlescreens  | Game title screen                      |
| thumbnail     | thumbnails    | Small preview image                    |
| video         | videos        | Gameplay video or trailer              |

#### ES-DE settings

Here are the settings you need to change to read your artwork and gamelist.xml files from the same folder that holds your ROMs.

1. Open the ES-DE settings file:

    - Linux/macOS: `~/ES-DE/settings/es_settings.xml`
    - Windows: `C:\Program Files\ES-DE\settings\es_settings.xml`

2. Make these two edits (add the lines if they don’t exist):

```xml
<string name="MediaDirectory" value="/path/to/ROMs/folder" />
<bool name="LegacyGamelistFileLocation" value="true" />
```

- `MediaDirectory="/path/to/ROMs/folder"` download artwork into the same directory that contains the ROMs (should match `ROMDirectory`)
- `LegacyGamelistFileLocation="true"` forces gamelist.xml to be written next to the ROMs instead of inside the ES-DE config folder

3. If you already have scraped artwork, copy/move the systems from `~/ES-DE/downloaded_media/` and `~/ES-DE/gamelists/` into your ROMs folder

After a restart, ES-DE will place new artwork and the updated gamelist.xml directly in `roms/<system>/`, which is the expected layout.

## Metadata Tags in Filenames

Scans will now parse custom metadata tags in the filename that match specific patterns, and use them to fetch game metadata for the specified ID. The supported tags are:

(igdb-xxxx) for [IGDB](https://www.igdb.com/)
(moby-xxxx) for [MobyGames](https://www.mobygames.com/)
(ra-xxxx) for [RetroAchievements](https://retroachievements.org/)
(ssfr-xxxx) for [ScreenScraper](https://screenscraper.fr/)
(launchbox-xxxx) for [Launchbox](https://gamesdb.launchbox-app.com/)
(hltb-xxxx) for [HowLongToBeat](https://howlongtobeat.com/)

Filenames will not be renamed to add tags, as they are a non-standard formatting system and could create conflicts with other software.

## Boxart styles and media types

The gallery renders one piece of cover art per game card. Which one it shows is controlled by the **Boxart style** picker, a per-user setting under **Settings → User Interface**. The options are:

| Boxart style | Setting value   | Media type fetched by the scanner | In `scan.media` by default? |
| ------------ | --------------- | --------------------------------- | --------------------------- |
| 2D Box       | `cover_path`    | `box2d`                           | ✅ Yes (always enabled)     |
| 3D Box       | `box3d_path`    | `box3d`                           | ❌ No                       |
| Physical     | `physical_path` | `physical`                        | ❌ No                       |
| Mix Image    | `miximage_path` | `miximage`                        | ❌ No                       |

The picker only changes **what the gallery displays**, it doesn't fetch anything. The scanner downloads artwork during a scan, and it only downloads media types listed in `scan.media` in `config.yml`. The default is `box2d`, `screenshot`, and `manual`, so out of the box only the **2D Box** style has art to show.

If you switch to **3D Box**, **Physical**, or **Mix Image** without adding the matching media type to `scan.media`, your cards will come up blank even though the setting clearly "took" in the UI.

To use an alternate style end-to-end:

1. Add the media type(s) you want to `scan.media` in [`config.yml`](../reference/configuration-file.md#scanmedia). For all four styles plus the back/spine covers:

    ```yaml
    scan:
        media:
            - box2d
            - box2d_back
            - box2d_side
            - box3d
            - physical
            - miximage
            - screenshot
            - manual
    ```

    `box2d` is always fetched regardless of the list, so you don't strictly need to list it, but keeping it explicit makes the list self-documenting. See the [full `scan.media` table](../reference/configuration-file.md#scanmedia) for every type (fanart, title screens, marquees, bezels, videos, etc.).

2. Re-fetch the art. Most styles come from ScreenScraper, which only pulls media types in `scan.media` during a scan. Run an **Update Metadata** scan on the platforms you want.

3. Set your **Boxart style** in the UI, and the cards should display the newly-downloaded art.


!!! note "Provider support varies"
    ScreenScraper is the richest source for `box3d`, `physical`, and `miximage`. If you want 3D boxes across your library, make sure ScreenScraper is [enabled](#screenscraper) and ranked in [`scan.priority.artwork`](#priority-and-conflict-resolution).

## Priority and conflict resolution

When multiple providers return different values for the same field, the winner is determined by `scan.priority.metadata` and `scan.priority.artwork` in `config.yml`. Defaults:

```yaml
scan:
    priority:
        metadata:
            - igdb
            - moby
            - ss
            - ra
            - launchbox
            - gamelist
            - hasheous
            - flashpoint
            - hltb
        artwork:
            - igdb
            - moby
            - ss
            - ra
            - launchbox
            - libretro
            - gamelist
            - hasheous
            - flashpoint
            - hltb
```

Reorder these lists to taste. For example, put `ss` first if you prefer ScreenScraper boxart, or move `hltb` up if you care about completion times more than descriptions.

See the full [Configuration File reference](../reference/configuration-file.md) for everything `scan.priority` can do

---

### Getting Started/Quick Start

---
title: Quick Start
description: Get your instance running in about fifteen minutes
---

# Quick Start

This guide gets a RomM instance up and running with the default stack (MariaDB + Valkey) using Docker Compose. If you're on Unraid, Synology, TrueNAS, Kubernetes, or Railway, check out the [Install & Deploy](../install/index.md) section for platform-specific guides.

## Before you start

You'll need:

- [Docker](https://docs.docker.com/get-docker/) and Docker Compose installed on the host
- Your ROM files organised in the expected [folder structure](folder-structure.md)
- API credentials for at least one [metadata provider](metadata-providers.md)


!!! warning "Metadata providers are recommended"
    Scans work without a metadata API for basic use but setup problems and companion-app integrations (e.g. Playnite) can fail without them. Setting up **at least one** provider before your first scan is strongly recommended.

## 1. Write your `docker-compose.yml`

Start from the reference file shipped in the repo. A known-good, minimally-edited version is included below. Save it as `docker-compose.yml` in an empty directory on your host.


???+ example "docker-compose.yml"
    `yaml
        --8<-- "quick-start.docker-compose.yml"
    `

You'll want to edit the following values before launching:

| Where     | Variable                  | What to put                                                                                          |
| --------- | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `romm-db` | `MARIADB_ROOT_PASSWORD`   | A long, randomly generated password.                                                                 |
| `romm-db` | `MARIADB_PASSWORD`        | A separate long, randomly generated password.                                                        |
| `romm`    | `DB_PASSWD`               | Must match `MARIADB_PASSWORD` above.                                                                 |
| `romm`    | `ROMM_AUTH_SECRET_KEY`    | Generate with `openssl rand -hex 32` and keep it secret.                                             |
| `romm`    | Metadata provider creds   | Fill in only the providers you've registered with (see [Metadata Providers](metadata-providers.md)). |
| `romm`    | `/path/to/library` volume | Host path to the directory containing your `roms/` folder.                                           |
| `romm`    | `/path/to/assets` volume  | Host storage paths for saves, states and screenshots.                                                |
| `romm`    | `/path/to/config` volume  | Host path to a directory that will hold `config.yml`.                                                |

Generate the auth secret now so you don't forget:

```sh
openssl rand -hex 32
# -> 03a054b6ca27e0107c5eed552ea66becd9f3a2a8a91e7595cd462a593f9ecd09
```

## 2. Start the stack

From the directory containing your `docker-compose.yml`:

```sh
docker compose up -d
```

On the first run Docker will pull `rommapp/romm:latest` and `mariadb:latest`, bring up the database, wait for the healthcheck, then bring up the app. If you dropped the `romm-db` service and pointed RomM at a MariaDB or MySQL server you already run, read the [binary logging prerequisite](../install/databases.md#binary-logging-and-trigger-privileges) first, because migrations fail at startup without it. Verify everything is running:

```sh
docker ps -f name=romm
```

```asciinema-player
    {
        "file": "../../resources/asciinema/quick-start-docker-compose.cast",
        "title": "Docker Compose install",
        "preload": true,
        "loop": true,
        "auto_play": true,
        "cols": 140,
        "rows": 30,
        "fit": "width",
        "terminal_font_size": "small",
        "terminal_line_height": "1.2",
        "terminal_font_family": "Roboto Mono, Monaco, Consolas, monospace"
    }
```

## 3. Create the admin user

Open `http://<host>:8080` in a browser. On first start, you'll be redirected to the **Setup Wizard**. Set an admin username and password (the first user created always gets the Admin role), then log in.

## Next steps

- Populate the library by [scanning the mounted ROMs](first-scan.md)
- [Upload](../using/uploads.md) a handful of files in through the web UI

---

### Install/Backup And Restore

---
title: Backup & Restore
description: Protect your install against data loss
---

# Backup & Restore

This page covers routine backups and restoring from them.

## What to back up

| Path/volume                                  | What's in it                                                                                            | Backup?                                                                                                  |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Database** (`mysql_data`, `pg_data`, etc.) | User accounts, ROM metadata, collections, ratings, play sessions, paired devices, saves/states metadata | **Critical**: back this up nightly.                                                                      |
| **`/romm/assets`**                           | User uploads: save files, save states, user-uploaded screenshots, manuals, covers                       | **Critical**: back this up nightly.                                                                      |
| **`/romm/config`**                           | `config.yml` and any custom overrides                                                                   | **Critical**: rarely changes but small and painful to recreate.                                          |
| `/romm/resources`                            | Metadata images (covers, screenshots) fetched from IGDB/ScreenScraper/etc.                              | Medium priority, and can be re-downloaded on a rescan (including it speeds up recovery).                 |
| `/redis-data`                                | Task queue state                                                                                        | Low priority, in-flight tasks only, and lost tasks can be re-run.                                        |
| **`/romm/library`**                          | Your ROM files                                                                                          | Back this up **separately**. It's your source data and you should already have a backup strategy for it. |

## Routine backup


!!! warning "Always stop the stack or use consistent snapshots"
    A live `cp -r` of the DB volume can copy an inconsistent state. Either bring the stack down briefly, or use `mysqldump`/`pg_dump` for a consistent logical dump.

### DB dump (MariaDB/MySQL)

```sh
docker exec romm-db mariadb-dump \
  --user=romm-user --password=<DB_PASSWD> \
  --single-transaction --databases romm \
  > romm-db-$(date +%F).sql
```

### DB dump (PostgreSQL)

```sh
docker exec romm-db pg_dump \
  --username=romm-user --dbname=romm \
  > romm-db-$(date +%F).sql
```

### Assets + config

Copy the host paths you mounted as `/romm/assets` and `/romm/config`. Incremental rsync is fine:

```sh
rsync -a --delete /srv/romm/assets/ /backup/romm/assets/
rsync -a --delete /srv/romm/config/ /backup/romm/config/
```

### Putting it together

A minimal nightly cron:

```sh
#!/usr/bin/env bash
set -euo pipefail
STAMP=$(date +%F)
DEST=/backup/romm

docker exec romm-db mariadb-dump --user=romm-user --password=$DB_PASSWD \
  --single-transaction --databases romm | gzip > "$DEST/db-$STAMP.sql.gz"

rsync -a --delete /srv/romm/assets/ "$DEST/assets/"
rsync -a --delete /srv/romm/config/ "$DEST/config/"

# keep 14 days of DB dumps
find "$DEST" -maxdepth 1 -name 'db-*.sql.gz' -mtime +14 -delete
```

Send it offsite however you already do (rclone to B2/S3, restic, borg). Remember the 3-2-1 rule: 3 copies, on 2 different media, with 1 offsite!

## Restore

### Into an empty install

1. Start a fresh stack with the same `ROMM_AUTH_SECRET_KEY` (if the secret changes, all sessions and invite links are invalidated).
2. Wait for the first-run setup to finish, then stop the stack: `docker compose stop`.
3. Restore the DB:

```sh
docker exec -i romm-db mariadb --user=root --password=<root-pw> romm < romm-db-2026-04-15.sql
# or for Postgres:
docker exec -i romm-db psql --username=romm-user --dbname=romm < romm-db-2026-04-15.sql
```

4. Restore `assets/`, `config/` and `resources/` to the mounted host paths.
5. Restart with `docker compose start`.

## Verifying a backup is actually restorable

A backup you haven't restored is a hope, not a backup. Spin up a throwaway stack from a recent backup twice a year:

```sh
# in a scratch directory
cp docker-compose.yml ./test-compose.yml
# point DB + assets volumes at test paths
docker compose -f test-compose.yml up -d
# restore the latest dump into it
# log in, check that users/collections/saves are present
docker compose -f test-compose.yml down -v
```

---

### Install/Databases

---
title: Databases
description: Supported database drivers
---

# Databases

RomM uses SQLAlchemy + Alembic for persistence. Three drivers are supported, so pick based on what you already run.

| Driver                             | `ROMM_DB_DRIVER` | Image         | Default port | Notes                                          |
| ---------------------------------- | ---------------- | ------------- | ------------ | ---------------------------------------------- |
| **MariaDB** (default, recommended) | `mariadb`        | `mariadb:11`  | `3306`       | What the reference compose uses. Well-tested.  |
| **MySQL**                          | `mysql`          | `mysql:8`     | `3306`       | Largely interchangeable with MariaDB for RomM. |
| **PostgreSQL**                     | `postgresql`     | `postgres:16` | `5432`       | Use if you already run Postgres.               |

## MariaDB (default)

This is what the [reference Compose](../getting-started/quick-start.md) sets up. No extra config beyond filling in the passwords.

```yaml
services:
    romm:
        environment:
            - ROMM_DB_DRIVER=mariadb
            - DB_HOST=romm-db
    romm-db:
        image: mariadb:11
        environment:
            - MARIADB_ROOT_PASSWORD=<separate-strong-password>
            - MARIADB_DATABASE=romm
            - MARIADB_USER=romm-user
            - MARIADB_PASSWORD=<same-as-DB_PASSWD>
        volumes:
            - mysql_data:/var/lib/mysql
        healthcheck:
            test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
            start_period: 30s
            interval: 10s
            timeout: 5s
            retries: 5
```

## MySQL

Identical compose to MariaDB but swap the image and the healthcheck:

```yaml
services:
    romm:
        environment:
            - ROMM_DB_DRIVER=mysql
            - DB_PORT=3306
    romm-db:
        image: mysql:8
        environment:
            - MYSQL_ROOT_PASSWORD=<separate-strong-password>
            - MYSQL_DATABASE=romm
            - MYSQL_USER=romm-user
            - MYSQL_PASSWORD=<same-as-DB_PASSWD>
        volumes:
            - mysql_data:/var/lib/mysql
        healthcheck:
            test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
            interval: 10s
            timeout: 5s
            retries: 5
```

## Binary logging and trigger privileges

RomM's migrations create triggers on the `roms` table. MariaDB and MySQL refuse trigger DDL when binary logging is enabled and the connecting user lacks `SUPER`, so the container aborts during startup with:

```text
sqlalchemy.exc.OperationalError: (mariadb.OperationalError) You do not have the SUPER
privilege and binary logging is enabled (you *might* want to use the less safe
log_bin_trust_function_creators variable)
ERROR:    [RomM][init] Failed to run database migrations
```

This mainly affects external or managed database servers, because binary logging is on by default on MySQL 8 and is commonly enabled on hardened or replicated MariaDB instances. The `mariadb:11` container from the reference Compose is not affected out of the box.

Both fixes below have to be applied by an admin or root database user rather than the RomM user. The quickest one sets the global flag, though it is lost when the database restarts:

```sql
SET GLOBAL log_bin_trust_function_creators = 1;
```

To make it survive a restart, add it under `[mysqld]` in the server's option file and restart the database (see [Configuring MariaDB with option files](https://mariadb.com/docs/server/server-management/install-and-upgrade-mariadb/configuring-mariadb/configuring-mariadb-with-option-files)). That file is usually `my.cnf`, or `custom.cnf` under `/config` on the linuxserver image:

```cnf
[mysqld]
log_bin_trust_function_creators = 1
```

Alternatively, grant the privilege to the RomM user itself:

```sql
GRANT BINLOG ADMIN ON *.* TO 'romm-user'@'%';  -- MariaDB 10.5+
GRANT SUPER ON *.* TO 'romm-user'@'%';         -- older MariaDB, or MySQL
```

Restart RomM once the change is in place. A migration that failed this way is safe to re-run, so it picks up from wherever it stopped and completes.

## PostgreSQL

```yaml
services:
    romm:
        environment:
            - ROMM_DB_DRIVER=postgresql
            - DB_PORT=5432
    romm-db:
        image: postgres:16
        environment:
            - POSTGRES_DB=romm
            - POSTGRES_USER=romm-user
            - POSTGRES_PASSWORD=<same-as-DB_PASSWD>
        volumes:
            - pg_data:/var/lib/postgresql/data
        healthcheck:
            test: ["CMD-SHELL", "pg_isready -U romm-user -d romm"]
            interval: 10s
            timeout: 5s
            retries: 5
```

## Extra connection parameters

`DB_QUERY_JSON` takes a JSON blob of extra parameters appended to the connection string, e.g. for enabling TLS to an external DB, a longer connection timeout, or a non-default port:

```yaml
environment:
  - DB_QUERY_JSON={"ssl": "true", "connect_timeout": "5"}
```

---

### Install/Image Variants

---
title: Image Variants
description: Choose between the slim and full container images
---

# Image Variants

RomM publishes two production image variants. They're interchangeable at the config level, so pick based on whether you want baked-in EmulatorJS cores or fetch them from the CDN at runtime.

| Variant            | Tag                                           | Approx size | When to pick                                                                             |
| ------------------ | --------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------- |
| **Full** (default) | `rommapp/romm:latest` `rommapp/romm:5.0.0`    | ~400MB      | You want in-browser play (most users pick this).                                         |
| **Slim**           | `rommapp/romm:slim` `rommapp/romm:5.0.0-slim` | ~100MB      | Headless use (API + native-app clients only) or when you're running emulators elsewhere. |

Both variants are published on Docker Hub (`docker.io/rommapp/romm`) and GitHub Container Registry (`ghcr.io/rommapp/romm`). The GHCR images track the same tags and are a good choice if you run into Docker Hub's rate limits.

## Switching variants

Change the `image:` line in `docker-compose.yml` and recreate the container:

```yaml
services:
    romm:
        image: rommapp/romm:5.0.0-slim # was :5.0.0
```

```sh
docker compose up -d
```

No data migration is required. Saves, states, metadata, and `config.yml` are the same across variants.

---

### Install/Index

---
title: Install & Deploy
description: On Docker Compose, Unraid, Synology, TrueNAS, Kubernetes, or Railway
---

# Install & Deploy

RomM is distributed as a Docker image. Every supported deployment runs the same container, and the differences are in who manages it.

## Pick your path

| If you're on…        | Start here                                                         |
| -------------------- | ------------------------------------------------------------------ |
| **Linux server/NAS** | [The canonical reference setup](../getting-started/quick-start.md) |
| **Unraid**           | [Community Apps template or DCM](unraid.md)                        |
| **Synology**         | [Container Manager + DSM-specific notes](synology.md)              |
| **TrueNAS**          | [App Catalog or YAML install](truenas.md)                          |
| **Kubernetes**       | [Community charts and gotchas](kubernetes.md)                      |
| **Railway**          | [Community one-click template](railway.md)                         |

If none of those match, start with [Docker Compose](../getting-started/quick-start.md) and adapt as needed.

## Foundational pieces

Regardless of host platform, you'll make the same handful of decisions:

- **[Database](databases.md)**: MariaDB (default), MySQL or PostgreSQL
- **[In-memory store](redis-or-valkey.md)**: required for sessions + task queue, embedded or external
- **[Reverse proxy](reverse-proxy.md)**: Caddy, nginx, Traefik, or NPM. HTTPS is required for OIDC and PWA install.
- **[Backup & restore](backup-and-restore.md)**: Test it before you need it!

## After you're up and running

- **Configure metadata providers**: [Metadata Providers](../getting-started/metadata-providers.md)
- **Populate the library**: [Your First Scan](../getting-started/first-scan.md)
- **Add users**: [Invitations & Registration](../administration/invitations-and-registration.md)

---