5.5.0-alpha.3预发布2026-11-19
What's Changed
* fix(frontend): follow bottom-nav taps made while a view transition runs by @sdornan in https://github.com/rommapp/romm/pull/5605
* chore(deps): update backend dependencies by @renovate[bot] in https://github.com/rommapp/romm/pull/5607
* fix(gallery): align the gallery shell's right gutter with the top bar by @sdornan in https://github.com/rommapp/romm/pull/5623
* fix(validation): reject email addresses ending in a newline by @marcello-pichini in https://github.com/rommapp/romm/pull/5593
* fix(export): encode filenames in ROM content URLs by @marcello-pichini in https://github.com/rommapp/romm/pull/5596
* chore(deps): update frontend dependencies by @renovate[bot] in https://github.com/rommapp/romm/pull/5608
* chore(trunk): Upgrade trunk by @github-actions[bot] in https://github.com/rommapp/romm/pull/5610
* fix(frontend): serve the generic platform icon as SVG by @mvanhorn in https://github.com/rommapp/romm/pull/5613
* fix(hasheous): map Neo Geo MVS to the Hasheous Neo Geo platform by @andest01 in https://github.com/rommapp/romm/pull/5616
* docs: add legal disclaimer and zero-tolerance piracy rule by @gantoine in https://github.com/rommapp/romm/pull/5618
* fix(frontend): catch mdi icon names the build would drop by @andest01 in https://github.com/rommapp/romm/pull/5562
* chore(deps): update dependency tornado to v6.6.1 [security] by @renovate[bot] in https://github.com/rommapp/romm/pull/5626
* fix(ui): dim verification sources the ROM did not match by @andest01 in https://github.com/rommapp/romm/pull/5627
* chore(trunk): clear the osv-scanner findings from the scheduled check-all run by @NevesHenry in https://github.com/rommapp/romm/pull/5619
* fix(ui): name the completion, rating and difficulty pills on hover by @andest01 in https://github.com/rommapp/romm/pull/5628
* fix(auth): issue a new session id when the session changes identity by @gantoine in https://github.com/rommapp/romm/pull/5630
* fix(sync): bound PSP PARAM.SFO size and TITLE length before ROM search by @gantoine in https://github.com/rommapp/romm/pull/5631
* fix(patcher): cap the output size a patch can declare by @gantoine in https://github.com/rommapp/romm/pull/5632
* fix(auth): check a dummy hash when the username is unknown by @gantoine in https://github.com/rommapp/romm/pull/5633
* feat(ui): show how many games a filtered platform page lists by @andest01 in https://github.com/rommapp/romm/pull/5629
* fix(export): fold line breaks in Pegasus metadata values by @gantoine in https://github.com/rommapp/romm/pull/5635
* fix(sync): map melonDS DS aliases to the RetroArch folder by @pcbeingused333 in https://github.com/rommapp/romm/pull/5637
* chore(deps): update peter-evans/create-pull-request action to v8.1.3 by @renovate[bot] in https://github.com/rommapp/romm/pull/5638
* perf(roms): page grouped galleries from the cached id index by @kynrek in https://github.com/rommapp/romm/pull/5636
* fix(env): quote empty values in env.template so Compose reads them as empty by @Spinnich in https://github.com/rommapp/romm/pull/5649
* fix(docker): update nginx to 1.30.7 for security fixes by @AnalyticETH in https://github.com/rommapp/romm/pull/5651
* chore(deps): update node.js to 6bd9ab4 by @renovate[bot] in https://github.com/rommapp/romm/pull/5654
* docs(readme): point Freegosy links to GitLab by @Spinnich in https://github.com/rommapp/romm/pull/5650
* chore(deps): update python:3.14-alpine3.24 docker digest to 5862d97 by @renovate[bot] in https://github.com/rommapp/romm/pull/5656
* fix(sync): support safe RetroArch WebDAV backups by @uPagge in https://github.com/rommapp/romm/pull/5648
New Contributors
* @marcello-pichini made their first contribution in https://github.com/rommapp/romm/pull/5593
* @kynrek made their first contribution in https://github.com/rommapp/romm/pull/5636
* @AnalyticETH made their first contribution in https://github.com/rommapp/romm/pull/5651
* @uPagge made their first contribution in https://github.com/rommapp/romm/pull/5648
Full Changelog: https://github.com/rommapp/romm/compare/5.5.0-alpha.2...5.5.0-alpha.3
5.5.0-alpha.2预发布2026-11-15
<!-- trunk-ignore-all(markdownlint/MD041) -->
<!-- trunk-ignore-all(markdownlint/MD033) -->
<!-- trunk-ignore-all(markdownlint/MD034) -->
<!-- trunk-ignore-all(markdownlint/MD024) -->
> [!CAUTION]
> Let the first start finish its migrations.
> Two migrations alter the roms table and one reads every ROM to flag custom sort names. Another adds columns to rom_files, saves, states and screenshots and moves every slot save into a save channel. All of this can take a while on a large library, so don't restart the container while they run.
> [!WARNING]
> Add your RomM credentials to Tinfoil.
> The Tinfoil feed at /api/feeds/tinfoil now requires authentication, like every other feed. If your Tinfoil shop entry has no username and password, add your RomM ones. Instances running with DISABLEDOWNLOADENDPOINT_AUTH=true are unaffected. #5344
> [!WARNING]
> List your library's articles under sorting.articles if it isn't in English.
> Titles now sort without a leading "the", "a" or "an" only, so "Die Hard Arcade" files under D instead of H. A library in another language can list its own articles in config.yml. When the list changes, RomM re-sorts every game on the next start, and a sort name you typed on a game is always kept as written. #5429
>
> ``yaml
> sorting:
> articles:
> - der
> - die
> - das
> `
> [!WARNING]
> Add a [host]:port line to knownhosts for push-pull devices on a port other than 22.**
> Push-pull sync now refuses any host the admin's known_hosts doesn't already trust, before opening a connection. A handheld listening on another port needs its own [host]:port entry; a bare host entry only covers port 22. #5460
> [!WARNING]
> Rescan your library to download saves converted for another emulator.
> Converting a save for a different core needs identity data from each ROM file that only a scan fills in, so run one rescan after upgrading. It also reads save ids from disc formats that earlier scans skipped. #5198
Technical changes
<details>
<summary>🌎 ENVIRONMENT VARIABLES</summary>
| variable | default | description |
| --- | --- | --- |
| OIDCAUTHPARAMS | - | JSON object of extra OIDC authorization request parameters, such as {"prompt":"select_account"}. Parameters RomM manages are rejected at startup |
| SEVENZIPTIMEOUT | 180 | Now also bounds Python-side reads of zip, tar, gzip, bz2 and xz archives during hashing |
| STREAMINGBROKERSECRET | - | Now only used for streaming containers that set no broker_secret in config.yml |
| SNAPSHOT_RETENTION | 10 | Snapshots each save channel keeps, not counting its current and pinned ones |
| SNAPSHOTBRANCHLIFETIME_DAYS | 30 | Days an unpinned branch left by a stale push is kept |
| ENABLESCHEDULEDPRUNE_SNAPSHOTS | true | Run the scheduled snapshot prune |
| SCHEDULEDPRUNESNAPSHOTSCRON | 41 * | Cron schedule for the snapshot prune |
</details>
<details>
<summary>📡 API CHANGES</summary>
Auth and users
| Change | Description |
| --- | --- |
| ⚠️ PUT /api/users/{id} current password | Changing your own username, password or email needs the new current_password form field: 400 when missing, 403 when wrong. Your own email is 403 when OIDC manages it (#5351) |
| UserSchema | New haspassword and emailmanagedbyoidc (#5351) |
| PUT /api/users/{id} empty values | email="" clears the email (#5472); rausername="" unlinks RetroAchievements and resets raprogression (#5475) |
| ⚠️ Acting on other users | PUT/DELETE /api/users/{id} and POST /api/users/{id}/ra/refresh on another user need users.write in the caller's scopes; a non-admin targeting an admin, or granting the admin role, gets 403 (#5346) |
| ⚠️ OAuth token revocation | Changing a password or username, or deleting a user, revokes that user's OAuth access and refresh tokens; rmm_ client tokens are unaffected (#5496) |
| ⚠️ ownonly permissions | Rejected with 422 on entities without owners; GET /api/permissions/catalog adds ownableentities (#5346) |
| GET /api/login/openid | Redirects to /login?bypass_autologin=true when OIDC provider discovery fails, instead of erroring (#5594) |
Client tokens and devices
| Change | Description |
| --- | --- |
| ⚠️ Client token scopes | POST /api/client-tokens and the device approval flow cap scopes at the calling credential's; regenerate and pair return 403 unless the caller holds every stored scope; DELETE returns 403 for a token broader than the caller (#5346) |
| DELETE /api/client-tokens/{id} | A client token can revoke itself without me.write; the route no longer declares a scope in OpenAPI (#5419) |
| DeviceAuthTokenResponse.id | POST /api/auth/device/token returns the token's id (#5419) |
| ⚠️ Device-bound tokens | A token paired to a device gets 404 for any other device on the devices, sync, saves, play session and activity heartbeat routes, and 403 on POST /api/client-tokens; deleting a device deletes its tokens (#5460) |
Visibility and validation
| Change | Description |
| --- | --- |
| ⚠️ GET /api/feeds/tinfoil | Requires roms.read, unless DISABLEDOWNLOADENDPOINT_AUTH is set (#5344) |
| ⚠️ GET /api/stats | Requires roms.read; totals leave out ROMs and assets hidden from the caller (#5496, #5498) |
| ⚠️ ROM visibility | Saves, states, screenshots, memory cards, virtual collections, feeds, recommendations, playlists, sync negotiation and /api/setup/library answer a hidden ROM or platform like a missing one (#5496, #5498) |
| POST /api/sync/sessions/{id}/complete | play_sessions need roms.user.write and are capped at 100 entries (#5496) |
| POST /api/roms/upload/{id}/complete | Returns 400 when the target platform became hidden or was deleted after /start (#5458) |
| ROM file routes | DELETE /api/roms/{romid}/files/{fileid} and GET/PUT .../files/{file_id}/progress answer a hidden ROM with the same not-found as a missing one (#5584) |
| Validation errors | Empty slug/fsslug in POST /api/config/system/platforms and /system/versions, a non-object smart collection filtercriteria, and a non-list rom_ids in PUT /api/collections/{id} return 422 (#5496) |
| Cover and manual URLs | file:// and launchbox-file:// URLs are refused for collection covers and ROM covers or manuals unless sent back unchanged (#5496) |
ROMs, saves and states
| Change | Description |
| --- | --- |
| GET /api/roms | New withprovidermetadata (default true); false returns every provider metadata blob as null, keeping manualmetadata (#5228) |
| ROM schemas version | New version field; revision and version are null instead of "" when the file name has none (#5255) |
| ROM schema name lists | Provider {id, name} entries in genres, companies and other name lists are returned as plain names (#5249) |
| RomFileSchema.category | Patch files are categorised as patch (#5538) |
| ⚠️ Legacy save and state writes | A save or state a snapshot holds is never rewritten: legacy routes return 409, RetroArch Cloud Sync uploads and deletes return 423, and device folder sync reports a conflict (#5198) |
| POST /api/saves with slot | Files the save under the channel of that name as its next snapshot; RetroArch .srm uploads go to default (#5198) |
| GET /api/saves/{id}/content | New core, option, profile and companion (up to 8) to download a save converted for a core (#5198) |
| POST /api/saves/{id}/content | New; merges the save into a memory card or volume sent as the container part (#5198) |
| SaveSchema, StateSchema | New channel_id (#5198) |
| DetailedRomSchema | New userchannels, channelfileid and snapshotsave_ids (#5198) |
| StateSchema.origindeviceid | New field; POST /api/states and PUT /api/states/{id} take an optional device_id` (#55
5.5.0-alpha.1预发布2026-11-11
<!-- trunk-ignore-all(markdownlint/MD041) -->
<!-- trunk-ignore-all(markdownlint/MD033) -->
<!-- trunk-ignore-all(markdownlint/MD034) -->
<!-- trunk-ignore-all(markdownlint/MD024) -->
> [!CAUTION]
> Let the first start finish its migrations.
> Two migrations alter the roms table and one reads every ROM to flag custom sort names, which can take a while on a large library. Don't restart the container while they run.
> [!WARNING]
> Add your RomM credentials to Tinfoil.
> The Tinfoil feed at /api/feeds/tinfoil now requires authentication, like every other feed. If your Tinfoil shop entry has no username and password, add your RomM ones. Instances running with DISABLEDOWNLOADENDPOINT_AUTH=true are unaffected. #5344
> [!WARNING]
> List your library's articles under sorting.articles if it isn't in English.
> Titles now sort without a leading "the", "a" or "an" only, so "Die Hard Arcade" files under D instead of H. A library in another language can list its own articles in config.yml. When the list changes, RomM re-sorts every game on the next start, and a sort name you typed on a game is always kept as written. #5429
>
> ``yaml
> sorting:
> articles:
> - der
> - die
> - das
> `
> [!WARNING]
> Add a [host]:port line to knownhosts for push-pull devices on a port other than 22.**
> Push-pull sync now refuses any host the admin's known_hosts doesn't already trust, before opening a connection. A handheld listening on another port needs its own [host]:port entry; a bare host entry only covers port 22. #5460
Technical changes
<details>
<summary>🌎 ENVIRONMENT VARIABLES</summary>
| variable | default | description |
| --- | --- | --- |
| OIDCAUTHPARAMS | - | JSON object of extra OIDC authorization request parameters, such as {"prompt":"select_account"}. Parameters RomM manages are rejected at startup |
| SEVENZIPTIMEOUT | 180 | Now also bounds Python-side reads of zip, tar, gzip, bz2 and xz archives during hashing |
| STREAMINGBROKERSECRET | - | Now only used for streaming containers that set no broker_secret in config.yml |
</details>
<details>
<summary>📡 API CHANGES</summary>
Auth and users
| Change | Description |
| --- | --- |
| ⚠️ PUT /api/users/{id} current password | Changing your own username, password or email needs the new current_password form field: 400 when missing, 403 when wrong. Your own email is 403 when OIDC manages it (#5351) |
| UserSchema | New haspassword and emailmanagedbyoidc (#5351) |
| PUT /api/users/{id} empty values | email="" clears the email (#5472); rausername="" unlinks RetroAchievements and resets raprogression (#5475) |
| ⚠️ Acting on other users | PUT/DELETE /api/users/{id} and POST /api/users/{id}/ra/refresh on another user need users.write in the caller's scopes; a non-admin targeting an admin, or granting the admin role, gets 403 (#5346) |
| ⚠️ OAuth token revocation | Changing a password or username, or deleting a user, revokes that user's OAuth access and refresh tokens; rmm_ client tokens are unaffected (#5496) |
| ⚠️ ownonly permissions | Rejected with 422 on entities without owners; GET /api/permissions/catalog adds ownableentities (#5346) |
Client tokens and devices
| Change | Description |
| --- | --- |
| ⚠️ Client token scopes | POST /api/client-tokens and the device approval flow cap scopes at the calling credential's; regenerate and pair return 403 unless the caller holds every stored scope; DELETE returns 403 for a token broader than the caller (#5346) |
| DELETE /api/client-tokens/{id} | A client token can revoke itself without me.write; the route no longer declares a scope in OpenAPI (#5419) |
| DeviceAuthTokenResponse.id | POST /api/auth/device/token returns the token's id (#5419) |
| ⚠️ Device-bound tokens | A token paired to a device gets 404 for any other device on the devices, sync, saves, play session and activity heartbeat routes, and 403 on POST /api/client-tokens; deleting a device deletes its tokens (#5460) |
Visibility and validation
| Change | Description |
| --- | --- |
| ⚠️ GET /api/feeds/tinfoil | Requires roms.read, unless DISABLEDOWNLOADENDPOINT_AUTH is set (#5344) |
| ⚠️ GET /api/stats | Requires roms.read; totals leave out ROMs and assets hidden from the caller (#5496, #5498) |
| ⚠️ ROM visibility | Saves, states, screenshots, memory cards, virtual collections, feeds, recommendations, playlists, sync negotiation and /api/setup/library answer a hidden ROM or platform like a missing one (#5496, #5498) |
| POST /api/sync/sessions/{id}/complete | play_sessions need roms.user.write and are capped at 100 entries (#5496) |
| POST /api/roms/upload/{id}/complete | Returns 400 when the target platform became hidden or was deleted after /start (#5458) |
| Validation errors | Empty slug/fsslug in POST /api/config/system/platforms and /system/versions, a non-object smart collection filtercriteria, and a non-list rom_ids in PUT /api/collections/{id} return 422 (#5496) |
| Cover and manual URLs | file:// and launchbox-file:// URLs are refused for collection covers and ROM covers or manuals unless sent back unchanged (#5496) |
ROMs, saves and states
| Change | Description |
| --- | --- |
| GET /api/roms | New withprovidermetadata (default true); false returns every provider metadata blob as null, keeping manualmetadata (#5228) |
| ROM schemas version | New version field; revision and version are null instead of "" when the file name has none (#5255) |
| ROM schema name lists | Provider {id, name} entries in genres, companies and other name lists are returned as plain names (#5249) |
| RomFileSchema.category | Patch files are categorised as patch (#5538) |
| StateSchema.origindeviceid | New field; POST /api/states and PUT /api/states/{id} take an optional device_id (#5531) |
Platforms
| Change | Description |
| --- | --- |
| PlatformSchema.firstreleaseyear | New field, filled from IGDB during scans (#5433) |
| PlatformSchema counts | romcount and fssize_bytes count only ROMs the caller can see (#5313) |
| Arcade platform slugs | New mame, mame-advmame, fbneo, fba and board slugs; cps1, cps2, cps3, model1, system16, system32 and system-32 are retired into arcade (#5273) |
Streaming
| Change | Description |
| --- | --- |
| Streaming admin routes | Listing containers and sessions needs users.read; opening a desktop, force-releasing or driving another user's session needs users.write (#5346) |
| POST /api/streaming/sessions | Optional discfileid picks the starting disc; 400 when it isn't one of the ROM's playlist discs (#5446) |
Heartbeat, setup, tasks and config
| Change | Description |
| --- | --- |
| GET /api/heartbeat | Adds FILESYSTEM.FSPLATFORMSLUGS (#5473), EMULATION.EJSCORES and EMULATION.EJSNIGHTLYCORES (#5533), ROMPATCHER.SUPPORTED_EXTENSIONS (#5538) |
| GET /api/setup/library | Existing platforms add slug (#5473) |
| Tasks | New manual task recomputenamesort_keys (#5429) |
| config.yml | New sorting.articles (#5429) |
</details>
Highlights
Farewell console mode 🫡
The classic UI and console mode are gone, along with the /console/* routes, and anyone who had picked the classic UI in Settings now gets the current one. Tailwind CSS and Vuetify went with them. The page background and default text colour now come from RomM's theme tokens, so the background shade shifts slightly in both themes. #5309 #5315
Arcade platforms by emulator family
Arcade folders no longer all fold into one arcade platform. MAME, AdvanceMAME, FinalBurn Neo and FinalBurn Alpha sets get their own platforms (mame, mame-advmame, fbneo, fba`),
5.4.12026-10-22
> [!CAUTION]
> This release includes mitigations for the recent eMudhra CA compromise as well as general dependency upgrades. While we don't believe RomM instances are vulnerable, we recommend upgrading as soon as possible.
What's Changed
* docs(readme): move corporate sponsors above friends by @gantoine in https://github.com/rommapp/romm/pull/5219
* chore(deps-dev): bump handlebars from 4.7.9 to 4.7.10 in /frontend by @dependabot[bot] in https://github.com/rommapp/romm/pull/5221
* fix(deps): bump certifi to 2026.10.19 to distrust compromised eMudhra intermediates by @gantoine in https://github.com/rommapp/romm/pull/5283
* chore(deps): bump uv to 0.13.4 by @gantoine in https://github.com/rommapp/romm/pull/5284
* chore(trunk): Upgrade trunk by @github-actions[bot] in https://github.com/rommapp/romm/pull/5225
* chore(deps): update github actions by @renovate[bot] in https://github.com/rommapp/romm/pull/5244
* chore(deps): bump aiohttp from 3.14.3 to 3.14.4 by @dependabot[bot] in https://github.com/rommapp/romm/pull/5276
* chore(deps-dev): bump vite from 8.3.1 to 8.3.4 in /frontend by @dependabot[bot] in https://github.com/rommapp/romm/pull/5285
* chore(deps): bump follow-redirects from 1.16.0 to 1.16.1 in /frontend by @dependabot[bot] in https://github.com/rommapp/romm/pull/5286
* docs: list the ROM patcher env vars in env.template by @pcbeingused333 in https://github.com/rommapp/romm/pull/5265
* chore(deps): update dependency pillow to v13 [security] by @renovate[bot] in https://github.com/rommapp/romm/pull/5288
* chore(deps): update dependency storybook to v10.6.2 [security] by @renovate[bot] in https://github.com/rommapp/romm/pull/5291
* chore(deps): bump Node to 24.22.1 for the October 2026 security release by @gantoine in https://github.com/rommapp/romm/pull/5295
* fix(docker): upgrade the image's pip to 26.2.2 by @gantoine in https://github.com/rommapp/romm/pull/5298
* chore(deps): update github/codeql-action action to v4.39.0 by @renovate[bot] in https://github.com/rommapp/romm/pull/5299
New Contributors
* @pcbeingused333 made their first contribution in https://github.com/rommapp/romm/pull/5265
Full Changelog: https://github.com/rommapp/romm/compare/5.4.0...5.4.1
5.4.02026-10-10
> [!CAUTION]
> Give the first start 15-20 mintes to finish its migrations.
> Several of this release's migrations rewrite the roms table and backfill it in batches, which can take a while on a large library. Don't restart the container while they run.
> [!WARNING]
> Cross-origin requests are denied by default.
> An unset or empty ROMMCORSALLOWEDORIGINS used to allow every origin, and now allows none. If a browser-based client on another origin talks to your RomM, list its origin in ROMMCORSALLOWEDORIGINS. A * still answers any origin, but without credentials, so a client that signs in with the session cookie needs its origin listed explicitly. #4699
> [!WARNING]
> Add a reverse proxy on a public address to FORWARDEDALLOWIPS.
> RomM now trusts X-Forwarded-For only from loopback and private ranges. A proxy outside those ranges has to be added, or every request is logged and rate limited as coming from the proxy's address. #4748
Technical changes
<details>
<summary>🌎 ENVIRONMENT VARIABLES</summary>
Notifications and email
| variable | default | description |
| --- | --- | --- |
| SMTPHOST | - | SMTP server; email stays off until this and SMTPFROM are set |
| SMTP_PORT | 587 | SMTP server port |
| SMTP_USERNAME | - | Login for the SMTP server, if it needs one |
| SMTP_PASSWORD | - | Password for the SMTP server |
| SMTP_FROM | - | Sender address, such as romm@example.com |
| SMTP_SECURITY | starttls | starttls, tls (implicit TLS, usually port 465) or none |
Audit log
| variable | default | description |
| --- | --- | --- |
| AUDITLOGRETENTION_DAYS | 90 | Days to keep audit events; 0 keeps them forever |
Library conversion
| variable | default | description |
| --- | --- | --- |
| ROMCONVERTOENABLED | false | Enable the "Convert library" task and ?format= download conversions |
| ROMCONVERTOTIMEOUT | 600 | Seconds per rom-converto operation |
| ROMCONVERTOMAX_CONCURRENCY | 2 | Concurrent conversions per web or task worker |
Devices and sync
| variable | default | description |
| --- | --- | --- |
| DEVICEINSTALLENABLED | true | Let users push a ROM to one of their devices for install |
| DEVICEINSTALLREQUESTTTLDAYS | 2 | Days an unfinished install request waits for its device; 0 waits forever |
| DEVICEINSTALLEXCLUDEDPLATFORMSLUGS | win,win3x,win9x,windows-apps | Platforms that can never be pushed to a device |
| SYNCRETROARCHPSPSERIALMAP | {} | JSON map of PSP serial to extensionless ROM file name, for RetroArch PSP saves whose title matches no ROM |
Scheduled cleanups
| variable | default | description |
| --- | --- | --- |
| ENABLESCHEDULEDCLEANUP_NETPLAY | true | Clean up empty netplay rooms |
| SCHEDULEDCLEANUPNETPLAYCRON | /30 | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPUPLOADTMP | true | Clean up abandoned chunked uploads |
| SCHEDULEDCLEANUPUPLOADTMPCRON | 0 | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPZIPCACHE | true | Clean up stale cached ZIP files |
| SCHEDULEDCLEANUPZIPCACHECRON | 0 4 * | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPSYNCSESSIONS | true | Fail sync sessions no client completed |
| SCHEDULEDCLEANUPSYNCSESSIONSCRON | 23 | When that cleanup runs |
General
| variable | default | description |
| --- | --- | --- |
| ⚠️ ROMMCORSALLOWEDORIGINS | - | Empty now allows no cross-origin requests; a ` allows any origin but never credentials |
| ⚠️ FORWARDEDALLOWIPS | local/loopback addresses | Proxies trusted to report the client's address; was * |
| DISABLE_EASYRPG | false | Disable the EasyRPG player for everyone |
| SEVENZIPTIMEOUT | 180 | Timeout for 7-Zip operations in seconds, was 60 |
</details>
<details>
<summary>📡 API CHANGES</summary>
| Change | Description |
| --- | --- |
| ⚠️ CORS denied by default | ROMMCORSALLOWEDORIGINS now defaults to empty instead of ; browser clients on another origin must be allowlisted (#4699) |
| CORS wildcard drops credentials | With in ROMMCORSALLOWEDORIGINS, responses no longer send Access-Control-Allow-Credentials (#4699) |
| Invalid credentials are unauthenticated | A malformed Basic header or an invalid/expired JWT bearer no longer 500s; the request proceeds unauthenticated and gets the route's 401/403 (#4799) |
| ⚠️ PermissionGroupSchema.issystem removed | Replaced by systemkey (SystemGroupKey or null) (#4767) |
| Age limits on permissions | PermissionGroupSchema/Create/Update and UserPermissionsSchema/Update gain agelimit, hideunratedroms; updates apply them only with setage_settings: true (#5081) |
| Collection romcount is computed | romcount on collection, smart and virtual collection schemas is now read-only, derived from the visible rom_ids (#4930) |
| ⚠️ Collection name errors | Duplicate name on create or rename returns 409 (was 500); names over 400 chars return 422 (#4997) |
| ⚠️ GET /api/netplay/list | Scope assets.read - roms.read; game_id is now an integer ROM id, 404 for a missing or hidden ROM (#4700) |
| ⚠️ Netplay socket rooms | open-room and password-less join-room require a signed-in user with roms.read who can see the ROM; the room password moved from extra.room_password to top-level password (#4700) |
| ⚠️ GET /api/play-sessions | Without devices.read, only allowed when deviceid equals the calling token's device; no longer defaults deviceid from the token (#4956) |
| ⚠️ PlaySessionSchema.syncsessionid removed | Field dropped from play session responses (#4670) |
| Page params on play and sync sessions | GET /api/play-sessions and GET /api/sync/sessions use shared page params (limit 1 to 10000, offset); sync sessions gains offset (#4715) |
| ⚠️ Sync delete operation | SyncOperationSchema.action adds delete (slot emptied on the server); SyncNegotiateResponse adds total_delete (#4674) |
| POST /api/sync/negotiate payload | New restore_unlisted and emulators fields to re-offer unlisted saves and filter by emulator (#5091) |
| Save sync baselines | POST /api/saves and PUT /api/saves/{id} take a contenthash query param; POST /api/saves/{id}/downloaded takes contenthash in the body (#4768) |
| Save/state uploads validated | emulator must be a single folder name (max length enforced); file names over 255 bytes return 400; uploads to a hidden ROM return 404 (#4851, #4997) |
| SaveSchema / StateSchema annotations | New is_favorite and labels; masked to defaults on another user's shared save or state (#4714) |
| StateSchema.core | New field naming the RetroArch core that wrote the state (#4862) |
| ⚠️ PUT /api/roms/{id} rename errors | Renaming onto an existing file returns 409 (was 500); an invalid or overlong fs_name returns 400 before any metadata fetch (#4997) |
| PUT /api/roms/{id} manual metadata | rawmanualmetadata is validated, 422 when malformed; ManualMetadata gains alternative_names (#5111) |
| POST /api/roms/{id}/convert-to-folder | Also returns 409 when an .m3u beside the file lists it; upload and walkthrough routes reject the same case (#5076) |
| GET /api/roms relevance ordering | Empty orderby with a search term ranks by relevance on every database; charindex is empty under relevance order (#4996) |
| GET/HEAD /api/roms/{id}/content/{file_name} | New ?format= for converted single-file downloads (202 + Retry-After while converting, 406 when unavailable) (#4999) |
| GET /api/roms/{id}/content/{file_name} | New purpose=download\|play query param, recorded in the audit log (#4748) |
| DetailedRomSchema.download_formats | Formats the caller can request with ?format= (#5000) |
| iseasyrpggame on ROM schemas | New boolean on SimpleRomSchema` a
5.4.0-beta.1预发布2026-10-09
> [!CAUTION]
> Give the first start time to finish its migrations.
> Several of this release's migrations rewrite the roms table and backfill it in batches, which can take a while on a large library. Don't restart the container while they run.
> [!WARNING]
> Cross-origin requests are denied by default.
> An unset or empty ROMMCORSALLOWEDORIGINS used to allow every origin, and now allows none. If a browser-based client on another origin talks to your RomM, list its origin in ROMMCORSALLOWEDORIGINS. A * still answers any origin, but without credentials, so a client that signs in with the session cookie needs its origin listed explicitly. #4699
> [!WARNING]
> Add a reverse proxy on a public address to FORWARDEDALLOWIPS.
> RomM now trusts X-Forwarded-For only from loopback and private ranges. A proxy outside those ranges has to be added, or every request is logged and rate limited as coming from the proxy's address. #4748
Technical changes
<details>
<summary>🌎 ENVIRONMENT VARIABLES</summary>
Notifications and email
| variable | default | description |
| --- | --- | --- |
| SMTPHOST | - | SMTP server; email stays off until this and SMTPFROM are set |
| SMTP_PORT | 587 | SMTP server port |
| SMTP_USERNAME | - | Login for the SMTP server, if it needs one |
| SMTP_PASSWORD | - | Password for the SMTP server |
| SMTP_FROM | - | Sender address, such as romm@example.com |
| SMTP_SECURITY | starttls | starttls, tls (implicit TLS, usually port 465) or none |
Audit log
| variable | default | description |
| --- | --- | --- |
| AUDITLOGRETENTION_DAYS | 90 | Days to keep audit events; 0 keeps them forever |
Library conversion
| variable | default | description |
| --- | --- | --- |
| ROMCONVERTOENABLED | false | Enable the "Convert library" task and ?format= download conversions |
| ROMCONVERTOTIMEOUT | 600 | Seconds per rom-converto operation |
| ROMCONVERTOMAX_CONCURRENCY | 2 | Concurrent conversions per web or task worker |
Devices and sync
| variable | default | description |
| --- | --- | --- |
| DEVICEINSTALLENABLED | true | Let users push a ROM to one of their devices for install |
| DEVICEINSTALLREQUESTTTLDAYS | 2 | Days an unfinished install request waits for its device; 0 waits forever |
| DEVICEINSTALLEXCLUDEDPLATFORMSLUGS | win,win3x,win9x,windows-apps | Platforms that can never be pushed to a device |
| SYNCRETROARCHPSPSERIALMAP | {} | JSON map of PSP serial to extensionless ROM file name, for RetroArch PSP saves whose title matches no ROM |
Scheduled cleanups
| variable | default | description |
| --- | --- | --- |
| ENABLESCHEDULEDCLEANUP_NETPLAY | true | Clean up empty netplay rooms |
| SCHEDULEDCLEANUPNETPLAYCRON | /30 | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPUPLOADTMP | true | Clean up abandoned chunked uploads |
| SCHEDULEDCLEANUPUPLOADTMPCRON | 0 | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPZIPCACHE | true | Clean up stale cached ZIP files |
| SCHEDULEDCLEANUPZIPCACHECRON | 0 4 * | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPSYNCSESSIONS | true | Fail sync sessions no client completed |
| SCHEDULEDCLEANUPSYNCSESSIONSCRON | 23 | When that cleanup runs |
General
| variable | default | description |
| --- | --- | --- |
| ⚠️ ROMMCORSALLOWEDORIGINS | - | Empty now allows no cross-origin requests; a ` allows any origin but never credentials |
| ⚠️ FORWARDEDALLOWIPS | local/loopback addresses | Proxies trusted to report the client's address; was * |
| DISABLE_EASYRPG | false | Disable the EasyRPG player for everyone |
| SEVENZIPTIMEOUT | 180 | Timeout for 7-Zip operations in seconds, was 60 |
</details>
<details>
<summary>📡 API CHANGES</summary>
| Change | Description |
| --- | --- |
| ⚠️ CORS denied by default | ROMMCORSALLOWEDORIGINS now defaults to empty instead of ; browser clients on another origin must be allowlisted (#4699) |
| CORS wildcard drops credentials | With in ROMMCORSALLOWEDORIGINS, responses no longer send Access-Control-Allow-Credentials (#4699) |
| Invalid credentials are unauthenticated | A malformed Basic header or an invalid/expired JWT bearer no longer 500s; the request proceeds unauthenticated and gets the route's 401/403 (#4799) |
| ⚠️ PermissionGroupSchema.issystem removed | Replaced by systemkey (SystemGroupKey or null) (#4767) |
| Age limits on permissions | PermissionGroupSchema/Create/Update and UserPermissionsSchema/Update gain agelimit, hideunratedroms; updates apply them only with setage_settings: true (#5081) |
| Collection romcount is computed | romcount on collection, smart and virtual collection schemas is now read-only, derived from the visible rom_ids (#4930) |
| ⚠️ Collection name errors | Duplicate name on create or rename returns 409 (was 500); names over 400 chars return 422 (#4997) |
| ⚠️ GET /api/netplay/list | Scope assets.read - roms.read; game_id is now an integer ROM id, 404 for a missing or hidden ROM (#4700) |
| ⚠️ Netplay socket rooms | open-room and password-less join-room require a signed-in user with roms.read who can see the ROM; the room password moved from extra.room_password to top-level password (#4700) |
| ⚠️ GET /api/play-sessions | Without devices.read, only allowed when deviceid equals the calling token's device; no longer defaults deviceid from the token (#4956) |
| ⚠️ PlaySessionSchema.syncsessionid removed | Field dropped from play session responses (#4670) |
| Page params on play and sync sessions | GET /api/play-sessions and GET /api/sync/sessions use shared page params (limit 1 to 10000, offset); sync sessions gains offset (#4715) |
| ⚠️ Sync delete operation | SyncOperationSchema.action adds delete (slot emptied on the server); SyncNegotiateResponse adds total_delete (#4674) |
| POST /api/sync/negotiate payload | New restore_unlisted and emulators fields to re-offer unlisted saves and filter by emulator (#5091) |
| Save sync baselines | POST /api/saves and PUT /api/saves/{id} take a contenthash query param; POST /api/saves/{id}/downloaded takes contenthash in the body (#4768) |
| Save/state uploads validated | emulator must be a single folder name (max length enforced); file names over 255 bytes return 400; uploads to a hidden ROM return 404 (#4851, #4997) |
| SaveSchema / StateSchema annotations | New is_favorite and labels; masked to defaults on another user's shared save or state (#4714) |
| StateSchema.core | New field naming the RetroArch core that wrote the state (#4862) |
| ⚠️ PUT /api/roms/{id} rename errors | Renaming onto an existing file returns 409 (was 500); an invalid or overlong fs_name returns 400 before any metadata fetch (#4997) |
| PUT /api/roms/{id} manual metadata | rawmanualmetadata is validated, 422 when malformed; ManualMetadata gains alternative_names (#5111) |
| POST /api/roms/{id}/convert-to-folder | Also returns 409 when an .m3u beside the file lists it; upload and walkthrough routes reject the same case (#5076) |
| GET /api/roms relevance ordering | Empty orderby with a search term ranks by relevance on every database; charindex is empty under relevance order (#4996) |
| GET/HEAD /api/roms/{id}/content/{file_name} | New ?format= for converted single-file downloads (202 + Retry-After while converting, 406 when unavailable) (#4999) |
| GET /api/roms/{id}/content/{file_name} | New purpose=download\|play query param, recorded in the audit log (#4748) |
| DetailedRomSchema.download_formats | Formats the caller can request with ?format= (#5000) |
| iseasyrpggame on ROM schemas | New boolean on SimpleRomSchema and Deta
5.4.0-alpha.2预发布2026-10-08
> [!CAUTION]
> Give the first start time to finish its migrations.
> Several of this release's migrations rewrite the roms table and backfill it in batches, which can take a while on a large library. Don't restart the container while they run.
> [!WARNING]
> Cross-origin requests are denied by default.
> An unset or empty ROMMCORSALLOWEDORIGINS used to allow every origin, and now allows none. If a browser-based client on another origin talks to your RomM, list its origin in ROMMCORSALLOWEDORIGINS. A * still answers any origin, but without credentials, so a client that signs in with the session cookie needs its origin listed explicitly. #4699
> [!WARNING]
> Add a reverse proxy on a public address to FORWARDEDALLOWIPS.
> RomM now trusts X-Forwarded-For only from loopback and private ranges. A proxy outside those ranges has to be added, or every request is logged and rate limited as coming from the proxy's address. #4748
Technical changes
<details>
<summary>🌎 ENVIRONMENT VARIABLES</summary>
Notifications and email
| variable | default | description |
| --- | --- | --- |
| SMTPHOST | - | SMTP server; email stays off until this and SMTPFROM are set |
| SMTP_PORT | 587 | SMTP server port |
| SMTP_USERNAME | - | Login for the SMTP server, if it needs one |
| SMTP_PASSWORD | - | Password for the SMTP server |
| SMTP_FROM | - | Sender address, such as romm@example.com |
| SMTP_SECURITY | starttls | starttls, tls (implicit TLS, usually port 465) or none |
Audit log
| variable | default | description |
| --- | --- | --- |
| AUDITLOGRETENTION_DAYS | 90 | Days to keep audit events; 0 keeps them forever |
Library conversion
| variable | default | description |
| --- | --- | --- |
| ROMCONVERTOENABLED | false | Enable the "Convert library" task and ?format= download conversions |
| ROMCONVERTOTIMEOUT | 600 | Seconds per rom-converto operation |
| ROMCONVERTOMAX_CONCURRENCY | 2 | Concurrent conversions per web or task worker |
Devices and sync
| variable | default | description |
| --- | --- | --- |
| DEVICEINSTALLENABLED | true | Let users push a ROM to one of their devices for install |
| DEVICEINSTALLREQUESTTTLDAYS | 2 | Days an unfinished install request waits for its device; 0 waits forever |
| DEVICEINSTALLEXCLUDEDPLATFORMSLUGS | win,win3x,win9x,windows-apps | Platforms that can never be pushed to a device |
| SYNCRETROARCHPSPSERIALMAP | {} | JSON map of PSP serial to extensionless ROM file name, for RetroArch PSP saves whose title matches no ROM |
Scheduled cleanups
| variable | default | description |
| --- | --- | --- |
| ENABLESCHEDULEDCLEANUP_NETPLAY | true | Clean up empty netplay rooms |
| SCHEDULEDCLEANUPNETPLAYCRON | /30 | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPUPLOADTMP | true | Clean up abandoned chunked uploads |
| SCHEDULEDCLEANUPUPLOADTMPCRON | 0 | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPZIPCACHE | true | Clean up stale cached ZIP files |
| SCHEDULEDCLEANUPZIPCACHECRON | 0 4 * | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPSYNCSESSIONS | true | Fail sync sessions no client completed |
| SCHEDULEDCLEANUPSYNCSESSIONSCRON | 23 | When that cleanup runs |
General
| variable | default | description |
| --- | --- | --- |
| ⚠️ ROMMCORSALLOWEDORIGINS | - | Empty now allows no cross-origin requests; a ` allows any origin but never credentials |
| ⚠️ FORWARDEDALLOWIPS | local/loopback addresses | Proxies trusted to report the client's address; was * |
| DISABLE_EASYRPG | false | Disable the EasyRPG player for everyone |
| SEVENZIPTIMEOUT | 180 | Timeout for 7-Zip operations in seconds, was 60 |
</details>
<details>
<summary>📡 API CHANGES</summary>
| Change | Description |
| --- | --- |
| ⚠️ CORS denied by default | ROMMCORSALLOWEDORIGINS now defaults to empty instead of ; browser clients on another origin must be allowlisted (#4699) |
| CORS wildcard drops credentials | With in ROMMCORSALLOWEDORIGINS, responses no longer send Access-Control-Allow-Credentials (#4699) |
| Invalid credentials are unauthenticated | A malformed Basic header or an invalid/expired JWT bearer no longer 500s; the request proceeds unauthenticated and gets the route's 401/403 (#4799) |
| ⚠️ PermissionGroupSchema.issystem removed | Replaced by systemkey (SystemGroupKey or null) (#4767) |
| Age limits on permissions | PermissionGroupSchema/Create/Update and UserPermissionsSchema/Update gain agelimit, hideunratedroms; updates apply them only with setage_settings: true (#5081) |
| Collection romcount is computed | romcount on collection, smart and virtual collection schemas is now read-only, derived from the visible rom_ids (#4930) |
| ⚠️ Collection name errors | Duplicate name on create or rename returns 409 (was 500); names over 400 chars return 422 (#4997) |
| ⚠️ GET /api/netplay/list | Scope assets.read - roms.read; game_id is now an integer ROM id, 404 for a missing or hidden ROM (#4700) |
| ⚠️ Netplay socket rooms | open-room and password-less join-room require a signed-in user with roms.read who can see the ROM; the room password moved from extra.room_password to top-level password (#4700) |
| ⚠️ GET /api/play-sessions | Without devices.read, only allowed when deviceid equals the calling token's device; no longer defaults deviceid from the token (#4956) |
| ⚠️ PlaySessionSchema.syncsessionid removed | Field dropped from play session responses (#4670) |
| Page params on play and sync sessions | GET /api/play-sessions and GET /api/sync/sessions use shared page params (limit 1 to 10000, offset); sync sessions gains offset (#4715) |
| ⚠️ Sync delete operation | SyncOperationSchema.action adds delete (slot emptied on the server); SyncNegotiateResponse adds total_delete (#4674) |
| POST /api/sync/negotiate payload | New restore_unlisted and emulators fields to re-offer unlisted saves and filter by emulator (#5091) |
| Save sync baselines | POST /api/saves and PUT /api/saves/{id} take a contenthash query param; POST /api/saves/{id}/downloaded takes contenthash in the body (#4768) |
| Save/state uploads validated | emulator must be a single folder name (max length enforced); file names over 255 bytes return 400; uploads to a hidden ROM return 404 (#4851, #4997) |
| SaveSchema / StateSchema annotations | New is_favorite and labels; masked to defaults on another user's shared save or state (#4714) |
| StateSchema.core | New field naming the RetroArch core that wrote the state (#4862) |
| ⚠️ PUT /api/roms/{id} rename errors | Renaming onto an existing file returns 409 (was 500); an invalid or overlong fs_name returns 400 before any metadata fetch (#4997) |
| PUT /api/roms/{id} manual metadata | rawmanualmetadata is validated, 422 when malformed; ManualMetadata gains alternative_names (#5111) |
| POST /api/roms/{id}/convert-to-folder | Also returns 409 when an .m3u beside the file lists it; upload and walkthrough routes reject the same case (#5076) |
| GET /api/roms relevance ordering | Empty orderby with a search term ranks by relevance on every database; charindex is empty under relevance order (#4996) |
| GET/HEAD /api/roms/{id}/content/{file_name} | New ?format= for converted single-file downloads (202 + Retry-After while converting, 406 when unavailable) (#4999) |
| GET /api/roms/{id}/content/{file_name} | New purpose=download\|play query param, recorded in the audit log (#4748) |
| DetailedRomSchema.download_formats | Formats the caller can request with ?format= (#5000) |
| iseasyrpggame on ROM schemas | New boolean on SimpleRomSchema and Deta
5.4.0-alpha.1预发布2026-10-06
> [!CAUTION]
> Give the first start time to finish its migrations.
> Several of this release's migrations rewrite the roms table and backfill it in batches, which can take a while on a large library. Don't restart the container while they run.
> [!WARNING]
> Cross-origin requests are denied by default.
> An unset or empty ROMMCORSALLOWEDORIGINS used to allow every origin, and now allows none. If a browser-based client on another origin talks to your RomM, list its origin in ROMMCORSALLOWEDORIGINS. A * still answers any origin, but without credentials, so a client that signs in with the session cookie needs its origin listed explicitly. #4699
> [!WARNING]
> Add a reverse proxy on a public address to FORWARDEDALLOWIPS.
> RomM now trusts X-Forwarded-For only from loopback and private ranges. A proxy outside those ranges has to be added, or every request is logged and rate limited as coming from the proxy's address. #4748
Technical changes
<details>
<summary>🌎 ENVIRONMENT VARIABLES</summary>
Notifications and email
| variable | default | description |
| --- | --- | --- |
| SMTPHOST | - | SMTP server; email stays off until this and SMTPFROM are set |
| SMTP_PORT | 587 | SMTP server port |
| SMTP_USERNAME | - | Login for the SMTP server, if it needs one |
| SMTP_PASSWORD | - | Password for the SMTP server |
| SMTP_FROM | - | Sender address, such as romm@example.com |
| SMTP_SECURITY | starttls | starttls, tls (implicit TLS, usually port 465) or none |
Audit log
| variable | default | description |
| --- | --- | --- |
| AUDITLOGRETENTION_DAYS | 90 | Days to keep audit events; 0 keeps them forever |
Library conversion
| variable | default | description |
| --- | --- | --- |
| ROMCONVERTOENABLED | false | Enable the "Convert library" task and ?format= download conversions |
| ROMCONVERTOTIMEOUT | 600 | Seconds per rom-converto operation |
| ROMCONVERTOMAX_CONCURRENCY | 2 | Concurrent conversions per web or task worker |
Devices and sync
| variable | default | description |
| --- | --- | --- |
| DEVICEINSTALLENABLED | true | Let users push a ROM to one of their devices for install |
| DEVICEINSTALLREQUESTTTLDAYS | 2 | Days an unfinished install request waits for its device; 0 waits forever |
| DEVICEINSTALLEXCLUDEDPLATFORMSLUGS | win,win3x,win9x,windows-apps | Platforms that can never be pushed to a device |
| SYNCRETROARCHPSPSERIALMAP | {} | JSON map of PSP serial to extensionless ROM file name, for RetroArch PSP saves whose title matches no ROM |
Scheduled cleanups
| variable | default | description |
| --- | --- | --- |
| ENABLESCHEDULEDCLEANUP_NETPLAY | true | Clean up empty netplay rooms |
| SCHEDULEDCLEANUPNETPLAYCRON | /30 | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPUPLOADTMP | true | Clean up abandoned chunked uploads |
| SCHEDULEDCLEANUPUPLOADTMPCRON | 0 | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPZIPCACHE | true | Clean up stale cached ZIP files |
| SCHEDULEDCLEANUPZIPCACHECRON | 0 4 * | When that cleanup runs |
| ENABLESCHEDULEDCLEANUPSYNCSESSIONS | true | Fail sync sessions no client completed |
| SCHEDULEDCLEANUPSYNCSESSIONSCRON | 23 | When that cleanup runs |
General
| variable | default | description |
| --- | --- | --- |
| ⚠️ ROMMCORSALLOWEDORIGINS | - | Empty now allows no cross-origin requests; a ` allows any origin but never credentials |
| ⚠️ FORWARDEDALLOWIPS | local/loopback addresses | Proxies trusted to report the client's address; was * |
| DISABLE_EASYRPG | false | Disable the EasyRPG player for everyone |
| SEVENZIPTIMEOUT | 180 | Timeout for 7-Zip operations in seconds, was 60 |
</details>
<details>
<summary>📡 API CHANGES</summary>
| Change | Description |
| --- | --- |
| ⚠️ CORS denied by default | ROMMCORSALLOWEDORIGINS now defaults to empty instead of ; browser clients on another origin must be allowlisted (#4699) |
| CORS wildcard drops credentials | With in ROMMCORSALLOWEDORIGINS, responses no longer send Access-Control-Allow-Credentials (#4699) |
| Invalid credentials are unauthenticated | A malformed Basic header or an invalid/expired JWT bearer no longer 500s; the request proceeds unauthenticated and gets the route's 401/403 (#4799) |
| ⚠️ PermissionGroupSchema.issystem removed | Replaced by systemkey (SystemGroupKey or null) (#4767) |
| Age limits on permissions | PermissionGroupSchema/Create/Update and UserPermissionsSchema/Update gain agelimit, hideunratedroms; updates apply them only with setage_settings: true (#5081) |
| Collection romcount is computed | romcount on collection, smart and virtual collection schemas is now read-only, derived from the visible rom_ids (#4930) |
| ⚠️ Collection name errors | Duplicate name on create or rename returns 409 (was 500); names over 400 chars return 422 (#4997) |
| ⚠️ GET /api/netplay/list | Scope assets.read - roms.read; game_id is now an integer ROM id, 404 for a missing or hidden ROM (#4700) |
| ⚠️ Netplay socket rooms | open-room and password-less join-room require a signed-in user with roms.read who can see the ROM; the room password moved from extra.room_password to top-level password (#4700) |
| ⚠️ GET /api/play-sessions | Without devices.read, only allowed when deviceid equals the calling token's device; no longer defaults deviceid from the token (#4956) |
| ⚠️ PlaySessionSchema.syncsessionid removed | Field dropped from play session responses (#4670) |
| Page params on play and sync sessions | GET /api/play-sessions and GET /api/sync/sessions use shared page params (limit 1 to 10000, offset); sync sessions gains offset (#4715) |
| ⚠️ Sync delete operation | SyncOperationSchema.action adds delete (slot emptied on the server); SyncNegotiateResponse adds total_delete (#4674) |
| POST /api/sync/negotiate payload | New restore_unlisted and emulators fields to re-offer unlisted saves and filter by emulator (#5091) |
| Save sync baselines | POST /api/saves and PUT /api/saves/{id} take a contenthash query param; POST /api/saves/{id}/downloaded takes contenthash in the body (#4768) |
| Save/state uploads validated | emulator must be a single folder name (max length enforced); file names over 255 bytes return 400; uploads to a hidden ROM return 404 (#4851, #4997) |
| SaveSchema / StateSchema annotations | New is_favorite and labels; masked to defaults on another user's shared save or state (#4714) |
| StateSchema.core | New field naming the RetroArch core that wrote the state (#4862) |
| ⚠️ PUT /api/roms/{id} rename errors | Renaming onto an existing file returns 409 (was 500); an invalid or overlong fs_name returns 400 before any metadata fetch (#4997) |
| PUT /api/roms/{id} manual metadata | rawmanualmetadata is validated, 422 when malformed; ManualMetadata gains alternative_names (#5111) |
| POST /api/roms/{id}/convert-to-folder | Also returns 409 when an .m3u beside the file lists it; upload and walkthrough routes reject the same case (#5076) |
| GET /api/roms relevance ordering | Empty orderby with a search term ranks by relevance on every database; charindex is empty under relevance order (#4996) |
| GET/HEAD /api/roms/{id}/content/{file_name} | New ?format= for converted single-file downloads (202 + Retry-After while converting, 406 when unavailable) (#4999) |
| GET /api/roms/{id}/content/{file_name} | New purpose=download\|play query param, recorded in the audit log (#4748) |
| DetailedRomSchema.download_formats | Formats the caller can request with ?format= (#5000) |
| iseasyrpggame on ROM schemas | New boolean on SimpleRomSchema and Deta
5.3.12026-09-23
Minor changes
* feat(v2): shorten the changelog's pull request links to #nnnn by @zurdi15 in https://github.com/rommapp/romm/pull/4705
Fixes
* fix(config): show folder mappings whose folder name is not lowercase by @sdornan in https://github.com/rommapp/romm/pull/4676
* fix(router): re-read the rom on every entry to the details route by @sdornan in https://github.com/rommapp/romm/pull/4685
* fix(streaming): put every container in a pool, and reach later pools by key by @LoneAngelFayt in https://github.com/rommapp/romm/pull/4596
* fix(security): patch OS packages in the published image and scope workflow permissions by @gantoine in https://github.com/rommapp/romm/pull/4592
* fix(docker): move the bases to Alpine 3.24 and nginx 1.30.5 by @sdornan in https://github.com/rommapp/romm/pull/4602
* fix(frontend): eliminate import cycles and gate them with eslint by @andest01 in https://github.com/rommapp/romm/pull/4643
* fix(security): revoke the target account's sessions on a credential change by @sdornan in https://github.com/rommapp/romm/pull/4653
* fix(v2): declare color-scheme with the v2 theme palettes by @sdornan in https://github.com/rommapp/romm/pull/4701
* fix(tooling): repair mypy's exclude regex and align its version with CI by @sdornan in https://github.com/rommapp/romm/pull/4655
* fix(frontend): keep the page title across query-only navigations by @gantoine in https://github.com/rommapp/romm/pull/4657
fix(frontend): tolerate null filtervalue lists from the API by @andest01 in https://github.com/rommapp/romm/pull/4680
* fix(v2): restore gamepad navigation on the platforms grid and every player by @gantoine in https://github.com/rommapp/romm/pull/4681
* fix(v2): pad focus follow-ups to #4681 by @gantoine in https://github.com/rommapp/romm/pull/4707
* fix(backend): correct three small typing faults mypy now reports by @sdornan in https://github.com/rommapp/romm/pull/4709
* fix(v2): descenders in chips are displayed by @andest01 in https://github.com/rommapp/romm/pull/4682
* fix(v2): rebuild the gallery list view for phones by @zurdi15 in https://github.com/rommapp/romm/pull/4654
* fix(backend): make type ignores honest and replace mypy trunk-ignores with fixes by @sdornan in https://github.com/rommapp/romm/pull/4711
* fix(backend): type fastapi-pagination pages and params for mypy by @sdornan in https://github.com/rommapp/romm/pull/4713
* fix(hltb): send a browser user agent so HLTB's firewall lets requests through by @sdornan in https://github.com/rommapp/romm/pull/4717
* fix(backend): cap music page size at the largest page the jukebox asks for by @sdornan in https://github.com/rommapp/romm/pull/4716
* fix(backend): type DML row counts from Session.execute for mypy by @sdornan in https://github.com/rommapp/romm/pull/4718
* fix(backend): build streaming response schemas directly instead of dicts by @sdornan in https://github.com/rommapp/romm/pull/4719
fix(backend): clear the remaining mypy errors outside romshandler by @sdornan in https://github.com/rommapp/romm/pull/4723
* fix(security): check endpoint ownership and consume invites atomically by @sdornan in https://github.com/rommapp/romm/pull/4694
* fix(sigil): bump the pin so GameCube save targets name a .gci on disk by @tmgast in https://github.com/rommapp/romm/pull/4687
Other changes
* docs: add a draft-announcement skill by @gantoine in https://github.com/rommapp/romm/pull/4667
* chore(deps): update astral-sh/setup-uv action to v10.2.0 by @renovate[bot] in https://github.com/rommapp/romm/pull/4668
chore: expand ts typecheck to frontend/scripts//*.ts by @andest01 in https://github.com/rommapp/romm/pull/4575
* build(frontend): prefix CSS in dev as well as production by @sdornan in https://github.com/rommapp/romm/pull/4609
* chore(security): harden Actions and Renovate, credit Socket in the readme by @gantoine in https://github.com/rommapp/romm/pull/4660
* test: fix the type errors mypy can now see in the test suite by @sdornan in https://github.com/rommapp/romm/pull/4708
* test(backend): simulate the CHD permission error without chmod by @sdornan in https://github.com/rommapp/romm/pull/4712
* ci: scan the published images, and stop scanning the lockfiles twice by @gantoine in https://github.com/rommapp/romm/pull/4683
* chore(v2) storybook viewport mirrors vue installBreakpointAttribute by @andest01 in https://github.com/rommapp/romm/pull/4710
Full Changelog: https://github.com/rommapp/romm/compare/5.3.0...5.3.1
5.3.02026-09-21
> [!CAUTION]
> ## Breaking changes
> ### Filesystem structure must be explicitly declared
> We no longer detect the filesystem layout by default, and an instance will refuses to start until explicitly declared in your config.yml. This is the equivalent of structure A:
>
> ``yaml
> filesystem:
> structure:
> default: "roms/{platform}/{game}"
> firmware: "bios/{platform}"
> `
>
> And the equivalent of structure B:
>
> `yaml
> filesystem:
> structure:
> default: "{platform}/roms/{game}"
> firmware: "{platform}/bios"
> `
>
> filesystem.romsfolder and filesystem.firmwarefolder have also been removed. An instance that still sets either will refuse to start and print the equivalent template.
>
> See Custom library structure and the filesystem.structure schema.
> [!WARNING]
> Emulator streaming config is now one entry per container, not one per emulator.
> A container's host, protocol and label become the defaults for every platform it serves, and a platform block only overrides what differs. Existing streaming setups need their config.yml rewritten before the feature will come back up.
>
> See Emulator Streaming for the new schema.
> [!NOTE]
>
> ### Environment variables
>
> #### Emulation
>
> | variable | default | description |
> | --- | --- | --- |
> | MAXSAVESPER_SLOT | 50 | Versions kept per save slot, newest first (0 disables) |
> | STREAMINGLAUNCHTIMEOUT | 600 | Seconds to wait for a streamed emulator to launch |
> | STREAMINGSTATEHISTORY_LIMIT | 50 | Save states kept per ROM, emulator and user |
>
> #### Physical games
>
> | variable | default | description |
> | --- | --- | --- |
> | UPCLOOKUPENABLED | true | Barcode lookups when adding a physical game |
> | UPCLOOKUPAPI_KEY | - | Key for the UPC lookup service |
> | UPCLOOKUPURL | https://api.upcitemdb.com/prod/trial/lookup | UPC lookup endpoint |
>
> #### Recommendations
>
> | variable | default | description |
> | --- | --- | --- |
> | ENABLESCHEDULEDBUILD_RECOMMENDATIONS | true | Nightly rebuild of the recommendation index |
> | SCHEDULEDBUILDRECOMMENDATIONSCRON | 30 5 | When that rebuild runs |
>
> #### Browser players
>
> | variable | default | description |
> | --- | --- | --- |
> | DISABLE_JSDOS | false | Disable the js-dos player for everyone |
> | DISABLE_PICO8 | false | Disable the PICO-8 player for everyone |
>
> #### Metadata providers
>
> | variable | default | description |
> | --- | --- | --- |
> | DEMOZOOAPIENABLED | false | Enable the Demozoo metadata provider |
> | POUETAPIENABLED | false | Enable the Pouët metadata provider |
> | CSDBAPIENABLED | false | Enable the CSDb metadata provider |
> | STEAMAPIENABLED | false | Enable the Steam storefront metadata provider |
> | HASHEOUSAPIURL | https://hasheous.org/api/v1 | Use a self-hosted Hasheous instance |
>
> #### General
>
> | variable | default | description |
> | --- | --- | --- |
> | SCAN_WORKERS | 4 | Parallel scan workers, was 1 |
> | WEBSERVERCONCURRENCY | 4 | API server workers, was 1 |
> | DBPOOLRECYCLE_SECONDS | 300 | Recycle pooled DB connections after this many seconds |
Highlights
Custom library structure
Instead of guessing between two folder structures, describe your exact library layout in config.yml. {platform} is the platform folder, the final {game} is where a game starts, and anything else in {braces} is just a folder you use to organize things. You can override the layout per platform, and give a platform a list of layouts when its games sit at more than one depth. #3571
ROM identity is now content-hashed, so you can move files around and keep their saves, favorites, play history and collections. And if you came from Batocera, RetroBat or ES-DE, their platform folder names are recognized out of the box, so most libraries need no mapping at all. #4345
`yaml
filesystem:
structure:
default: "roms/{platform}/{game}"
firmware: "bios/{platform}"
ps3: "roms/{platform}/{category}/{game}"
snes: "roms/{platform}/{region}/{game}"
nes:
- "roms/{platform}/{game}"
- "roms/{platform}/{category}/{game}"
`
Docs: Custom library structure, Folder name aliases
Emulator streaming
A massive update to emulator streaming. You configure one entry per container instead of one per emulator, a platform can pool several containers and grab whichever one is free, and platforms that do both browser and streamed play now get separate Play and Stream buttons. #4314
Saves and save states made while streaming are pulled back into your library with history and thumbnails. Multi-disc games get a disc-swap control, and whichever disc was mounted when you saved is the one remounted when you load. PS2 and GameCube can sync a whole memory card instead of individual save files, with a memory card library to create, rename, version, share and download them. Admins get a desktop session for setting up an emulator with no game running, plus a fleet view to force-release sessions across every container.
Docs: Emulator Streaming
Physical games
Own a game on a cartridge or disc, but have no ROM for it? You can now add it anyway, by name or by scanning its barcode with your camera, and it gets matched to metadata like any other game. #3848
Docs: Physical Games
<img width="522" height="400" alt="Screenshot 2026-09-11 at 6 00 19 PM" src="https://github.com/user-attachments/assets/dae5d22a-5bf5-4603-88a6-f45625ebcb48" />
Walkthroughs
Walkthroughs are now documents on a game, sitting next to its manuals. Upload your own, or paste a GameFAQs URL and have it fetched directly (as plain text). It'll even remember where you left off and show a progress bar for each user. #3816
Docs: Walkthroughs
<img width="1156" height="504" alt="Screenshot 2026-09-11 at 6 03 47 PM" src="https://github.com/user-attachments/assets/5b60009c-bbc6-4b87-8374-e938daf0e362" />
Title IDs read from the binary
Scans now pull a game's native Title ID straight out of its binary on PSX, PS2, PS3, PSP, PS Vita, Switch, 3DS, Wii, Wii U, GameCube, Dreamcast, Xbox and Xbox 360. It identifies games on the platforms we don't hash, so a renamed or moved file keeps its saves and collections, and it tells the system where a game writes its saves, so device sync knows what to look for. #3925
Docs: Title ids read from the binary
Jukebox
A soundtrack player for your whole library that follows you as a mini player anywhere in the app. Browse by album, platform, artist or genre, or just put a playlist on: Free Radio picks a randomized, album-balanced hour, and there's a Decade Mix, recently added, and your personal favorites. #4197
Docs: Jukebox
<img width="981" height="609" alt="Screenshot 2026-09-11 at 6 05 57 PM" src="https://github.com/user-attachments/assets/980edde3-51f6-4348-bdaa-a12767181cf3" />
JS-DOS and PICO-8 in the browser
Windows 3.x and 9x games now run on js-dos and its DOSBox-X backend. Note that js-dos` saves