Installation

Install ROMKADE Manager with Docker

Two steps: install Docker, the free tool that runs ROMKADE Manager on your computer, then start ROMKADE Manager.

1. Install Docker Desktop 2. Start ROMKADE Manager

Docker already installed? Go straight to step 2. Another system: macOS, Windows or Linux.

A single image for macOS, Windows and Linux, Intel/AMD and ARM processors · version 0.4.0 of 18 October 2026.

Version française (reference version) · Versión en español

Before you start

  • DockerDocker Desktop (macOS, Windows) or Docker Engine + Compose (Linux).
  • Same networkThe console and the computer are on the same local network.
  • SSH on the consoleSSH server running, username and password (or SSH key).
  • Compatible firmwareCheck the matrix before you start.
Before anything else

Install Docker

  1. Download Docker Desktop from the official Docker documentation, choosing the version for your processor (Apple Silicon or Intel).
  2. Open the downloaded file and drag Docker into the Applications folder.
  3. Start Docker Desktop and wait until the engine says it is running (whale icon in the menu bar).
  4. If macOS asks for permission to access the local network, allow it: it is what lets the Manager reach the console.
ROMKADE Manager

Start ROMKADE Manager

Four steps, about ten minutes the first time.

  1. 1Check Docker

    In a terminal (Terminal on macOS and Linux, PowerShell on Windows), these two commands should print a version number:

    Terminal
    docker --version
docker compose version

    “Cannot connect to the Docker daemon”? Docker Desktop is not running: see the common problems below.

  2. 2Download and start

    Available version: 0.4.0 of 18 October 2026 · what's new

    These commands create a romkade folder, download the official compose.yaml file of the latest release into it, then start ROMKADE Manager in the background.

    macOS and Linux
    mkdir romkade && cd romkade
curl -fsSLO https://github.com/RomKade/romkade-manager/releases/latest/download/compose.yaml
docker compose up -d
    Windows (PowerShell)
    mkdir romkade; cd romkade
curl.exe -fsSLO https://github.com/RomKade/romkade-manager/releases/latest/download/compose.yaml
docker compose up -d

    The first start downloads the images (a few hundred MB). Linux without the docker group: add sudo before docker compose. You can read the file before running it: compose.yaml, release notes.

  3. 3Open the interface

    Open localhost:8765 in your browser. The interface can only be reached from this computer: this is on purpose, it controls your console.

  4. 4Connect the console

    1. In Settings → Connection, enter the console's IP address, the SSH user and the password (or SSH key).
    2. Compare the fingerprint of the console's key with the one shown by the console, then approve it. If it ever changes, the connection will be blocked.
    3. Run Test the connection: six steps are checked, with a tip for each failure.
    4. Run the first sync: the card is read without writing anything to it.

Good to know

  • Nothing to configure: the file works as is, with the Typesense search engine included.
  • Data: catalog, settings, copies of saves and secrets live in the romkade-data Docker volume. They survive updates and docker compose down.
  • Port: 8765 by default. Already taken? ROMKADE_PORT=8780 docker compose up -d (PowerShell: $env:ROMKADE_PORT=8780; docker compose up -d), then open the chosen port.
  • Secrets: the console password and API keys stay in this volume, readable only by the container's account. Do not share a copy of the volume.
  • Automatic start: ROMKADE Manager restarts with Docker. To stop it: docker compose down in the romkade folder.
Advanced users

Useful commands

Run them in the folder that contains compose.yaml. Full reference: docker compose.

CommandEffect
docker compose psStatus of the services: running, stopped, restarting.
docker compose logs -fLive logs (Ctrl+C stops following, the service keeps running).
docker compose pullDownloads the new version of the images, without restarting anything.
docker compose up -dStarts, or restarts with the updated images. Volumes are kept.
docker compose downStops and removes the containers. Volumes, and so your data, are kept.
Never “docker compose down -v” out of habit

The -v option also deletes the volumes: catalog, copies of saves and settings would be lost. Only use it to erase everything on purpose, after copying your data.

Update

First read the release notes, then:

Terminal
docker compose pull
docker compose up -d

Back up and restore

Copy of the data volume into an archive in the current folder, then restore:

Terminal
docker compose down
docker run --rm -v romkade_romkade-data:/data -v "$PWD":/backup alpine tar czf /backup/romkade-data.tgz -C /data .
docker compose up -d

Restore: same command with tar xzf /backup/romkade-data.tgz -C /data, service stopped. PowerShell: replace "$PWD":/backup with "${PWD}:/backup".

Uninstall

docker compose down, then delete the romkade folder. The data volume stays until you delete it yourself (docker volume rm romkade_romkade-data).

Transparency

What Docker does not handle on its own

A container does not automatically have access to the local network, devices or your system's keychain. Bluetooth, sound and controllers are set up on the console over the network: the host computer does not need Bluetooth.

NeedHow it is handled
Reach the console on the local network (SSH, RetroArch network commands)Every feature goes through it. The container must be able to reach the console's IP address.
Store secrets (console password, API keys)In the container, a secrets.json file in the data volume, readable only by its owner (the system keychain cannot be reached from Docker).
Smart search (Typesense engine)A second service of the same compose.yaml file, with no published port: only ROMKADE Manager can reach it.
Access from a phoneNot with Docker: the interface is only open to the host computer (127.0.0.1), for security. Password-protected access from a phone exists in the install from source (macOS).

Tested with every release: full run on Linux (Intel/AMD and ARM) with a simulated console, and on macOS (Docker Desktop, Apple Silicon). Windows: file and PowerShell commands checked; Docker Desktop for Windows runs the same Linux image. A problem on your system? Tell us.

Security rules
  • Do not add --privileged, network_mode: host or a mount of /var/run/docker.sock to the provided file without a specific technical reason.
  • Do not expose ROMKADE Manager on the Internet: it controls your console. For remote access, wait for the documented authenticated method.
  • Keep your configuration file and your data folder private.
Troubleshooting

Common problems

“Cannot connect to the Docker daemon” or “docker: command not found”

Docker Desktop is not running (macOS, Windows) or the Docker service is stopped (Linux). Start it and wait until the engine says it is running, then repeat step 1.

Windows: “WSL 2 installation is incomplete”

WSL 2 or virtualization is not enabled. Follow Microsoft's WSL guide, restart, then start Docker Desktop again.

Linux: “permission denied” on the Docker socket

Your user has no rights on Docker. Use sudo or follow the post-installation steps.

The console still cannot be reached

Check that the console is on, connected to the same Wi-Fi and that its SSH server is running. The connection test in Settings checks six steps (network, SSH server, console key, credentials, command on the console, ROMs folder) and tells you which one fails.

macOS: “No route to host” while the console answers

macOS blocks local network access for the app concerned. Open System Settings → Privacy & Security → Local Network and allow it.

Going further: Full documentation