retroBITE is a clean, self-hosted collection manager for retro games. Pair your ROMs with rich metadata and artwork, then serve your library over the local network directly to your devices.
From a folder of ROMs to a library your consoles can load.
retroBITE started as the search for a Docker setup to network-load games onto real consoles. When nothing fit, the server script grew into a full collection manager.
01 · CONSOLES
130+ consoles. Add only the ones you own.
Pick consoles from a catalog of 130+ systems across 55 brands, from the Channel F to the PlayStation 4, plus arcade and engine targets. Each one gets its own folder under games/, and only the consoles you add show up in your library.
LIBRARY
Consoles
5 consoles · 72 games · 196.3 GB on disk
Count filesAdd console
Sony PlayStation
Sony · 1994
GAMES
20
UNIDENTIFIED
1
FILES
172
ON DISK
18.9 GB
psx · Game folders
PlayStation 2
Sony · 2000
GAMES
44
UNIDENTIFIED
1
FILES
52
ON DISK
158.6 GB
ps2 · Open PS2 Loader
GameCube
Nintendo · 2001
GAMES
6
UNIDENTIFIED
1
FILES
6
ON DISK
7.9 GB
gc
Wii
Nintendo · 2006
GAMES
1
FILES
1
ON DISK
4.4 GB
wii
02 · IDENTIFY
Every file matched to a title
Scans pick up each console's file types. Files are looked up by name and size first, then by CRC32, MD5 and SHA1. Multi-disc games merge through cue sheets and .m3u playlists. Anything left over waits in Needs identifying, where an exact MD5 match or a name search sorts it out.
Needs identifying3 files scanned but not matched to a title
SLUS_203.12.Silent Hill 2.iso
PS23.9 GB · 1 day ago
Identify
GALE01.rvz
GC1.1 GB · 2 days ago
Identify
Tekken 3 (Disc 1) [fixed].cue
PSX612.4 MB · 3 days ago
Identify
HOW A FILE GETS MATCHED
Name + sizeCRC32 · MD5 · SHA1Exact MD5 matchSearch by name
03 · METADATA
Artwork, details and ratings
Matched games pull their developer, publisher, genre, players and release date from ScreenScraper, along with up to 23 artwork types in your preferred region, and other regions on request. Each game gets a retroBITE score out of 100, from LaunchBox ratings and how many play it on RetroAchievements, and a rank across your library. Browse each console as a cover grid or a list, filtered by genre, players, rating or status.
PLAYSTATION 2
Crash Bandicoot - The Wrath of Cortex
Cortex builds Crunch, a super-bandicoot, to finish Crash for good. Rolling-sphere runs, air combat and classic jump-and-run stages stand in the way.
80retroBITE score#212
REGION
United States
CONSOLE
PlayStation 2
RELEASED
2001-11-01
SIZE
1.9 GB
DEVELOPER
Traveller’s Tales
PUBLISHER
Universal Interactive
GENRE
Platform
PLAYERS
1
RetroAchievementsHARDCORE
UNLOCKED
3 / 87
POINTS
20 / 515
HARDCORE
3
SITE RANK
#18,204
Rokked and Rolled5
Hardcore · 2d ago
Ruby Beauty5
Hardcore · 1w ago
Wrung Out5
Locked · 40.9% of players
N. Mobilized10
Locked · 26.1% of players
games/ps2
Crash Bandicoot - The Wrath of Cortex (USA).iso
SLUS_202.38
REGION
US
SCRAPES
1.4K
ROLE
Game
DISC
—
SIZE
1.9 GB
FORMAT
ISO
ADDED
3 weeks ago
LAST SEEN
Present
MD53e8b0c4d1f2a9e7b6c5d4a3f2e1b0c9d
FETCH ANOTHER REGIONJapanFetch
EUEurope3
USUnited States5
SHOWN · FROM SETTINGS
No region1
Wrath of Cortex on OPL
Setup · Edited 3 days ago
Open in Documents
Runs from the internal HDD in Open PS2 Loader.
Also tried over SMB from the box in the hall, wired.
Cover, disc and screenshot copied to ART/ by the toolbox.
SOURCE
Crash Bandicoot - The Wrath of Cortex (USA).isoISO · 1.9 GB
OUTPUT FORMAT
Writes beside each source, in games/ps2/
04 · ACHIEVEMENTS
RetroAchievements, kept in sync
Link your account and every game shows its set: hardcore and softcore unlocks, points, site rank, progression and win-condition badges, and how rare the locked ones are. The hash index refreshes nightly and new unlocks sync every 15 minutes.
RetroAchievementsHARDCORE
UNLOCKED
3 / 87
POINTS
20 / 515
HARDCORE
3
SITE RANK
#18,204
Rokked and Rolled5
Defeat Rok-Ko and Crunch in ‘Rumble in the Roks’.
Hardcore · 2d agoPROGRESSION
Ruby Beauty5
Obtain the hidden Red Gem in Crash and Burn.
Hardcore · 1w ago
Wrung Out5
Defeat Wa-Wa and Crunch in ‘Drain Damage’.
Locked · 40.9% of playersPROGRESSION
N. Mobilized10
Defeat Cortex and Crunch in ‘Crunch Time’.
Locked · 26.1% of playersWIN CONDITION
05 · LAYOUTS & TOOLBOX
Folders the way your loader expects
Give each console a layout that matches the loader or frontend you play it on, from a flat folder to one folder per game. Open PS2 Loader, for example, reads games from DVD/ and CD/, cover art from ART/ and settings from CFG/. The toolbox fills in those folders and adds or removes the license-ID prefix on file names. Disc consoles get .m3u playlists, and uploads land where the layout reads games from.
ConsolesPlayStation 2
PlayStation 2
Sony · 2000
LAYOUT
Open PS2 Loader
GAMES
44
FILES
52
ON DISK
190.2 GB
Scan folder
Upload files
Write OPL configs
Write OPL art
Rename files
Fetch missing artwork
Re-fetch all artwork
Fetch missing ratings
Re-fetch all ratings
Manage console
Any genreAny playersAny ratingAny statusTitle, A to Z
Baldur’s Gate - Dark Alliance II
3.4 GB90
Batman Begins
4.3 GB80
Beyond Good And Evil
4.0 GB90
Buffy the Vampire Slayer - Chaos Bleeds
3.6 GB80
Burnout 3 - Takedown
3.4 GB90
06 · NETWORK
Load games over SMB, FTP or PS3NETSRV
Samba (SMBv1 to SMB3) and vsftpd serve the same folders retroBITE manages, so modded consoles and loaders like OPL read games straight off the share, and ps3netsrv streams PS3, PS2 and PS1 games to webMAN MOD. Per-console shares keep paths short, and the dashboard shows each share's address and status.
Network shares192.168.1.20
PROTOCOLSTATUSPORTSLOGINSHARES
GameCube\\192.168.1.20\gc
PlayStation 2\\192.168.1.20\ps2
Sony PlayStation\\192.168.1.20\psx
Wii\\192.168.1.20\wii
Xbox\\192.168.1.20\xbox
GameCubeftp://192.168.1.20/gc
PlayStation 2ftp://192.168.1.20/ps2
Sony PlayStationftp://192.168.1.20/psx
Wiiftp://192.168.1.20/wii
Xboxftp://192.168.1.20/xbox
PlayStation 2192.168.1.20:38008 · PS2ISO
Sony PlayStation192.168.1.20:38008 · PSXISO
Meant for your LAN. SMB and FTP ask for the share login, but FTP is not encrypted. ps3netsrv has no password, so limit it to your PS3 with PS3NETSRV_WHITELIST.
07 · HARDWARE DOCS
Keep repair notes next to the games
Write repair logs, calibration procedures and compatibility matrices in Markdown, saved as files on disk and filed by console. Add images, YouTube embeds and references, import a .md or .zip, and keep the last 20 revisions of every doc.
KNOWLEDGE BASE · 4 DOCS
Docs
TEMPLATES
08 · LOOK
Five schemes and a CRT tube
Default amber, Phosphor green, Famicom crimson, DMG pea-green and Cobalt blue recolor the whole interface and the logo. Turn on scanlines for the faint banding of a tube over key art, and choose whether game pages lead with the logo or the title.
Color scheme
Recolors the whole interface and the logo, sign-in page included.
GAME PAGE TITLE
09 · CONVERSION
Convert and compress, in a queue
Shrink disc images to CHD, CSO or ZSO, pack GameCube and Wii games into RVZ or WBFS, turn PlayStation games into VCDs for POPStarter, or unpack any of them back to ISO or BIN/CUE. Pick one game or a whole shelf, choose the output format, and the conversion queue works through them with the bundled chdman, maxcso, ecm, cue2pops and nodtool. Output can be verified before it reaches your library, and the originals stay until the new file is in place.
SOURCE
DVD/SLES_519.17.Beyond Good and Evil.isoISO · 2.0 GB
OUTPUT FORMAT
QUEUE2 conversions run at a time
SLES_527.25.Need for Speed - Underground 2.iso
PlayStation 2 · → .zso · maxcso
62%
Atlantis - The Lost Tales (Europe).m3u
PlayStation · → .chd · chdman createcd
1.8 GB → 0.9 GB · saved 48%
DONE
Batman Begins (Europe).iso
PlayStation 2 · → .zso · maxcso
4.3 GB → 3.6 GB · saved 16%
DONE
10 · DECRYPT
Unlock discs with their key
Some disc images are encrypted and will not start without their disc key. Add the key, typed in or loaded from a key file, and retroBITE checks it against the disc and keeps it with the image. Or decrypt the image for good: the job runs through the same queue as conversion, and the decrypted image replaces the encrypted one. PlayStation 3 is supported today through ps3dec, and more consoles will follow.
Red Dead RedemptionRed Dead Redemption (Europe).isoNot checkedBLES006807.6 GBNot checked
Gran Turismo 5Gran Turismo 5 (Europe).isoDecryptedBCES0056912.0 GBDecrypted
Key ready plays over ps3netsrv already. Decrypt makes it play anywhere, without the key.
retroBITE does not include or download disc keys. Bring your own for the discs you own.
ALSO IN THE BOX
Live activity
Scanning, identifying, hashing, artwork, thumbnails, achievements, progress and toolbox jobs run on their own queues. Pages update over WebSockets.
Setup wizard
First run walks through your account, the interface, ScreenScraper and RetroAchievements.
Accounts
Sign in with username or email. Add accounts and reset passwords from the command line.
Storage at a glance
Used and free space is measured every 15 minutes, so files copied in over a share show up without a scan.
PROJECT STATUS
In active development
The core of retroBITE is in and working, and more is on the way before the first public release. The roadmap tracks what's shipped and what's coming next.
retroBITE (retrobite.app) is a free, self-hosted collection manager for retro games. It scans your ROM folders, matches each file to a title, adds metadata and artwork, and serves the library to real consoles over your local network.
Which consoles does retroBITE support?
The catalog covers 130+ systems across 55 brands, from the Channel F to the PlayStation 4, plus arcade and engine targets. You add only the consoles you own, and each gets its own folder.
Is retroBITE free and open source?
Yes. retroBITE is free and MIT licensed. The source code will be published with the first public release.
How do games get onto my consoles?
Samba (SMBv1 to SMB3) and FTP shares serve the same folders retroBITE manages, so modded consoles and loaders like Open PS2 Loader read games straight off the network. ps3netsrv streams PS3, PS2 and PS1 games to webMAN MOD on a PS3. Transfer can also copy games to a USB drive or SD card.
Where do metadata and achievements come from?
Metadata and up to 23 artwork types come from ScreenScraper. Each game’s retroBITE score, out of 100, weighs LaunchBox community ratings with how many play it on RetroAchievements. Link a RetroAchievements account to see each game’s achievement set, with new unlocks synced every 15 minutes.
When can I install retroBITE?
Now. retroBITE is in public beta and runs as a Docker Compose stack of three images: the app, the network share and MariaDB. Download the Compose file, set your passwords and your games folder, and start it. The Installation guide covers the command line, Portainer, Dockhand, Synology, QNAP, Unraid and TrueNAS.
Does retroBITE include games?
No. retroBITE manages games you already have and is meant for legally made backups of media you own. It does not include games or endorse piracy.
INSTALL
One Compose file, three images.
retroBITE runs as a Docker Compose stack: the app and the network share, built for amd64 and arm64, with the official MariaDB image. Download the Compose file, change the passwords and point it at your games. There is no key to generate; the first start sets everything up and opens a short setup in the browser.
It runs from the command line, Portainer, Dockhand or a NAS's container manager. The installation guide covers each, and a NAS whose own file sharing already uses the SMB and FTP ports. Join the Discord for help and release news.
For legally made backups of media you own. retroBITE does not endorse piracy.
mkdir retrobite && cd retrobite
# the stack, and the settings worth changing
curl -LO https://retrobite.app/docker-compose.yml
curl -L -o .env https://raw.githubusercontent.com/retroBITE-app/retroBITE/develop/.env.example
# set AUTH_PASS, DB_PASSWORD, DB_ROOT_PASSWORD, GAMES_PATH
nano .env
docker compose up -d
# then open http://<this machine>:81
# images
retrobite/retrobitethe app
retrobite/shareSMB, FTP + ps3netsrv
mariadblibrary database
# ports
81web interface (WEB_PORT)
139, 445SMB
20, 21FTP, passive 21100-21110
38008ps3netsrv (webMAN MOD)
# tags · linux/amd64 + linux/arm64
latestnewest release
developnewest pre-release
20261006-BETAone version, to stay on
# retroBITE: save as docker-compose.yml, then docker compose up -d.
#
# Every setting has a default, so this runs as it is. Change them in a .env
# file beside it, or in your container manager's variables: at least
# AUTH_PASS, DB_PASSWORD, DB_ROOT_PASSWORD and GAMES_PATH. The full list is
# at https://retrobite.app/docs/getting-started/configuration
#
# Needs Docker Compose 2.24 or newer. Runs develop, the newest pre-release;
# set RETROBITE_TAG to a version, such as 20261006-BETA, to stay on one.
services:
retrobite-web:
image: retrobite/retrobite:${RETROBITE_TAG:-develop}
container_name: retrobite-web
# Anything not listed under environment below — queue workers,
# ScreenScraper and RetroAchievements timeouts, conversion tools — is read
# from .env when there is one. See the Configuration docs.
env_file:
- path: .env
required: false
environment:
APP_ENV: ${APP_ENV:-production}
APP_DEBUG: ${APP_DEBUG:-false}
APP_URL: ${APP_URL:-http://localhost:${WEB_PORT:-81}}
APP_TIMEZONE: ${APP_TIMEZONE:-UTC}
# Left empty, a key is generated on first start and kept in the state
# volume below. It encrypts the passwords retroBITE stores, so set it
# only to keep one you already have.
APP_KEY: ${APP_KEY:-}
LOG_LEVEL: ${LOG_LEVEL:-warning}
DB_CONNECTION: mariadb
DB_HOST: retrobite-db
DB_PORT: 3306
DB_DATABASE: ${DB_DATABASE:-retrobite}
DB_USERNAME: ${DB_USERNAME:-retrobite}
DB_PASSWORD: ${DB_PASSWORD:-retrobite}
# This machine's LAN address: shown as the address consoles connect to,
# used to check SMB and FTP are up, and the network Settings →
# Destinations searches. The web container is behind Docker's bridge and
# cannot work it out itself.
HOST_IP: ${HOST_IP:-}
# The SMB and FTP account, shown on the Network page.
AUTH_USER: ${AUTH_USER:-retrobite}
# Transfers write to a USB drive from the browser, which Chrome allows
# only on https or localhost; a page opened another way links here.
TRANSFER_LOCALHOST_URL: ${TRANSFER_LOCALHOST_URL:-http://localhost:${WEB_PORT:-81}}
# nginx is in front, so game files and artwork are sent by it rather
# than streamed by PHP (App\Support\NginxFile).
SERVE_WITH_NGINX: "true"
# Whether retrobite-share runs ps3netsrv, what it serves and to whom,
# so its card is shown with the right consoles and says when it is open.
PS3NETSRV: ${PS3NETSRV:-true}
PS3NETSRV_FOLDERS: ${PS3NETSRV_FOLDERS:-PS3ISO=ps3 PS2ISO=ps2 PSXISO=psx}
PS3NETSRV_WHITELIST: ${PS3NETSRV_WHITELIST:-}
ports:
- "${WEB_PORT:-81}:80"
volumes:
# The ROM library, shared with retrobite-share below.
- ${GAMES_PATH:-./games}:/app/storage/app/games
# The markdown knowledge base, a folder beside this file.
- ${DOCS_PATH:-./docs}:/app/storage/app/docs
# Artwork retroBITE downloads itself, kept out of the games tree so a
# console browsing the share never sees it.
- ${MEDIA_PATH:-retrobite-media}:/app/storage/app/media
# The application key and Reverb's keys. Back it up with the database.
- ${STATE_PATH:-retrobite-state}:/app/storage/state
depends_on:
retrobite-db:
condition: service_healthy
restart: unless-stopped
retrobite-db:
image: mariadb:11.4
container_name: retrobite-mariadb
environment:
# Read once, when the database is first created: change them before the
# first start, or change them inside MariaDB afterwards as well.
MARIADB_DATABASE: ${DB_DATABASE:-retrobite}
MARIADB_USER: ${DB_USERNAME:-retrobite}
MARIADB_PASSWORD: ${DB_PASSWORD:-retrobite}
MARIADB_ROOT_PASSWORD: ${DB_ROOT_PASSWORD:-retrobite}
volumes:
- ${DB_PATH:-retrobite-db}:/var/lib/mysql
# Not published to the host: nothing outside the compose network needs it,
# and this box sits on a LAN with consoles on it.
expose:
- "3306"
healthcheck:
# The web container's migrate races the database otherwise: the server
# reports started long before InnoDB will accept a connection.
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 5s
timeout: 5s
retries: 20
start_period: 30s
restart: unless-stopped
retrobite-share:
image: retrobite/share:${RETROBITE_TAG:-develop}
container_name: retrobite-share
env_file:
- path: .env
required: false
environment:
AUTH_USER: ${AUTH_USER:-retrobite}
AUTH_PASS: ${AUTH_PASS:-retrobite}
# Advertised to FTP clients for passive mode. Empty, it is read off the
# default route on every start.
HOST_IP: ${HOST_IP:-}
# The console folders created in the library, and those that also get
# an SMB share of their own (what Open PS2 Loader connects to).
GAME_FOLDERS: ${GAME_FOLDERS:-}
SMB_SHARES: ${SMB_SHARES:-}
# ps3netsrv on port 38008, serving the PS3, PS2 and PS1 folders to
# webMAN MOD as its PS3ISO, PS2ISO and PSXISO lists. Read-only, and with
# no login: the whitelist (such as 192.168.1.*) limits who can read it.
PS3NETSRV: ${PS3NETSRV:-true}
PS3NETSRV_WHITELIST: ${PS3NETSRV_WHITELIST:-}
PS3NETSRV_FOLDERS: ${PS3NETSRV_FOLDERS:-PS3ISO=ps3 PS2ISO=ps2 PSXISO=psx}
# On the host's network, so consoles find it by NetBIOS and passive FTP
# works without a port range published. Ports 445, 139, 21 and 38008 must
# be free: on a NAS they are its own file sharing; see the Installation docs.
network_mode: host
volumes:
- ${GAMES_PATH:-./games}:/games
cap_add:
- NET_ADMIN
- SYS_ADMIN
init: true
restart: unless-stopped
volumes:
retrobite-db:
retrobite-media:
retrobite-state: