# Project pack: RomM @ 9c74d01

Facts about **RomM** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> RomM is a self-hosted manager for game ROMs and the games you own. It scans your folders, fetches covers, descriptions and screenshots, organises by platform and collection, and lets you play many retro games right in the browser. It supports multiple users and has a clean, mobile-friendly interface.

## Version and source
- Repository: https://github.com/rommapp/romm
- Pinned commit: `9c74d0143fbb876f2f62260b91c6fd0b3f590226`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/rommapp/romm/archive/9c74d0143fbb876f2f62260b91c6fd0b3f590226.zip
- Official docs: https://docs.romm.app
- Live demo: https://demo.romm.app/. Shared demo. Don't enter real data.
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/rommapp/romm bespoke-romm
  cd bespoke-romm
  git checkout --detach 9c74d0143fbb876f2f62260b91c6fd0b3f590226
  # Prepare development requirements and local configuration first.
  uv sync
  cd frontend
  npm install
  cd ..
  uv run python backend/main.py
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the quick start at https://docs.romm.app/latest/Getting-Started/Quick-Start-Guide, which provides a docker-compose file with RomM and MariaDB.
  ```

- Needs: Docker with a database, and your games organised in folders; Python 3.13 and Node for development
- Develop: `uv run python backend/main.py`
- Test: `uv run pytest`
- Stack: python, typescript (FastAPI, Vue, Vuetify, EmulatorJS, Docker). Difficulty for a non-developer with an AI: **advanced**. A Python FastAPI back end with a Vue front end and several metadata providers. Collections and users are settings; new features touch many parts.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`.

## Customisation points (settings → extend → code)
- **platforms-and-collections** [settings]: How your platforms and favourites are organised. → `Library structure and Collections in the app`
- **metadata-providers** [settings]: Where covers and descriptions come from. → `Environment variables for IGDB and others`
- **users-and-permissions** [settings]: Roles and access for family members. → `Administration → Users`
- **frontends-and-devices** [extend]: Use your library from other devices. → `docs.romm.app integrations (Playnite, Grout, Argosy)`
- **vue-ui** [code]: Screens and themes. → `frontend/src`
- **fastapi-backend** [code]: New endpoints and scanners. → `backend/endpoints and backend/handler`

## Must keep working
- Alembic migrations. Add new ones; never edit old ones.
- File handling, so users' folders are never modified.
- Permission checks for roles.

## Staying updatable
Use collections, settings and integrations. Keep code as new endpoints and components.

## Data, costs and safety
- Personal data: **yes**. Stored in: A database plus your library folders, assets (saves, states) and resources. Back up the database and the assets folder. Your ROM folders are read by RomM.
- Service: Metadata providers (IGDB, ScreenScraper, SteamGridDB, RetroAchievements) (optional, free keys): Covers, descriptions and screenshots.
- Service: MariaDB (required, free locally): Stores your library data.
- Setting `ROMM_AUTH_SECRET_KEY` (**secret**: the person enters it themselves, never in chat): Secret used to sign logins. Never paste it into an AI chat.
- Setting `DB_PASSWD` (**secret**: the person enters it themselves, never in chat): Database password.
- Setting `IGDB_CLIENT_SECRET` (**secret**: the person enters it themselves, never in chat): Your IGDB secret for metadata. Never paste it into an AI chat.
- Only use games you legally own. RomM does not provide game files.
- Keep provider keys and the auth secret out of Git and chats.

---

# Customising RomM

RomM is a FastAPI back end and a Vue front end. Its repo includes AGENTS.md with project conventions.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| API endpoints | backend/endpoints/ |
| Scanners and metadata handlers | backend/handler/ |
| Database models and migrations | backend/models/ and backend/alembic/ |
| Web app | frontend/src/ |
| Docker setup | docker/ and docker-compose.yml |
| Docs | docs/ |

## Use the gentlest change first

1. **Settings (no code):** libraries, collections, users and providers.
2. **Extend:** integrations and the API.
3. **Code:** endpoints and screens.

## Recipes

- **New metadata provider:** add a handler under `backend/handler/metadata` following an existing one, then register it in the scanner.
- **New collection view:** add an endpoint and a Vue page, and link it from the navigation.

## Running and checking your changes

- `uv run pytest` and the front-end checks for the area you changed.
- Scan a tiny sample library and play one game in the browser.

## Pitfalls

- Use a copy of your library while developing.
- Add Alembic migrations for schema changes.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/romm/9c74d01/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/romm/9c74d01/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/romm/9c74d01/r2/SKILL.md)