Installation
How to install, update, and uninstall Replay Control on a Raspberry Pi running RePlayOS.
Install
These steps work on Windows 10+, macOS, and Linux. On Windows, open PowerShell or Windows Terminal.
First, connect to the Pi:
ssh root@replay.localIf SSH asks whether you trust the host, type yes and press Enter.
When it asks for a password, type:
replayosYou will not see the password characters while typing. That is normal.
After you are connected to the Pi, paste this command:
curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bashThe installer downloads the latest stable release, installs the service, and starts Replay Control. When it finishes, type exit, then open https://replay.local:8443 in your browser.
Replay Control uses a local self-signed HTTPS certificate. Your browser will show a security warning the first time you open it; choose the advanced or continue option to approve the exception for your Pi.
On the first browser visit after install or after upgrading to the access-control release, Replay Control shows a first setup page. Enter the current RePlayOS root password to confirm admin access; on a fresh image the default password is replayos. Password changes are optional and can be done later from Settings > Access & Security.
If replay.local doesn’t resolve
Some Windows networks cannot find replay.local. Use the Pi’s IP address instead:
ssh root@192.168.1.50Replace 192.168.1.50 with your Pi’s real IP address. After you are connected, paste the installer:
curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bashFind the IP in your router’s connected-devices list. Use the same IP in the browser too: https://192.168.1.50:8443.
Install from another computer (no SSH session)
If you’d rather skip logging into the Pi yourself, you can run the installer from any Linux or macOS computer on the same network — it will SSH into the Pi for you and run the same steps:
curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bashPass --ip ADDRESS if mDNS discovery fails. This flow runs bash on your local machine, so on Windows use the SSH-first flow above instead.
Update / Uninstall
Re-run the install command to update; the binary and site assets are replaced and the service is restarted, while /etc/default/replay-control is preserved.
To remove the app:
curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bash -s -- --uninstallThe service is stopped and disabled, and the binary, site assets, systemd unit, and Avahi service are removed. The environment file is preserved in case you reinstall.
To wipe everything Replay Control has put on the Pi — binary, service files, environment file, and the on-storage .replay-control/ directory (DBs, settings, downloaded media, LaunchBox XML):
curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bash -s -- --purge --yes--purge prompts for confirmation when run interactively; pass --yes to skip the prompt (required when piping from curl). ROMs, saves, captures, and BIOS files are not touched.
Options
Append flags after bash -s --:
| Flag | Effect |
|---|---|
--ip ADDRESS | Skip mDNS discovery and use this address. |
--pi-pass PASSWORD | SSH password for the Pi (default: replayos). |
--version v0.3.0 | Install a specific release. Use beta for the latest pre-release. |
--dry-run | Print what would happen without making changes. |
--uninstall | Remove the app from the Pi. Preserves .replay-control/ data and the env file. |
--purge | Like --uninstall but also wipes .replay-control/ and /etc/default/replay-control. ROMs/saves/captures/BIOS untouched. |
--yes | Skip the confirmation prompt (required for --purge when piping from curl). |
Or set environment variables before the curl call:
| Variable | Default | Effect |
|---|---|---|
PI_PASS | replayos | Same as --pi-pass. |
REPLAY_PI_ADDR | (mDNS) | Same as --ip. |
REPLAY_CONTROL_VERSION | latest | Same as --version. |
Combining options:
curl -fsSL https://raw.githubusercontent.com/lapastillaroja/replay-control/main/install.sh | bash -s -- --pi-pass mypassword --version v0.3.0What gets installed
| Path | Contents |
|---|---|
/usr/local/bin/replay-control-app | Application binary. |
/usr/local/bin/catalog.sqlite | Read-only embedded game catalog. The service won’t start without it. |
/usr/local/share/replay/site/ | Static web assets (CSS, WASM, icons). |
/etc/systemd/system/replay-control.service | Systemd service unit. |
/etc/default/replay-control | Environment configuration. |
/etc/avahi/services/replay-control.service | mDNS service advertisement. |
The service starts automatically on boot. The app listens on HTTPS port 8443; HTTP port 8080 shows a page that points browsers to HTTPS. Customise behaviour by editing /etc/default/replay-control:
| Variable | Default | Effect |
|---|---|---|
REPLAY_PORT | 8080 | HTTP guidance page port. |
REPLAY_HTTPS_PORT | 8443 | HTTPS app/API port. |
REPLAY_SITE_ROOT | /usr/local/share/replay/site | Static-assets path. |
REPLAY_STORAGE_PATH | (auto-detected) | Override ROM storage path. |
REPLAY_CONFIG_PATH | (auto-detected) | Override the RePlayOS config path. |
REPLAY_CONTROL_IDENTITY_WORKERS | 2 | Advanced: hash-identification workers for library rebuilds and rescans. Valid range: 1-4. |
REPLAY_EXTRA_ARGS | (empty) | Extra CLI flags. Dangerous debugging flags must be explicit here, such as --dangerous-disable-https --dangerous-allow-insecure-auth-over-http. |
RUST_LOG | replay_control_app=info,replay_control_core=info | Log level. |
Troubleshooting
Pi not found. Make sure the Pi is powered on and on the same network. Check your router for its IP and pass --ip <addr>.
SSH authentication failed. The default password is replayos. If you’ve changed it, pass --pi-pass yourpassword.
Windows: ssh command not found. OpenSSH client ships with Windows 10 build 1809 (Oct 2018) and later, and with all Windows 11 versions. If it’s missing, enable it from Settings → Apps → Optional Features → Add a feature → OpenSSH Client.
Windows: replay.local doesn’t resolve. Use the Pi’s IP address from your router’s connected-devices list, then ssh root@<ip> and https://<ip>:8443. Common on Windows in VMs, where multicast often doesn’t cross between host and guest.