Linux
Zaparoo Core on Linux provides desktop integration with support for Steam, Lutris, Heroic, RetroArch, standalone emulators, EmuDeck, RetroDECK, Bottles, Faugus, and Moonlight launching. This platform serves as the foundation for other Linux-based platforms.
File paths
| Item | Path |
|---|---|
| Config file | ~/.config/zaparoo/config.toml |
| Data directory | ~/.local/share/zaparoo |
| Log file | ~/.local/share/zaparoo/logs/core.log |
| Mappings directory | ~/.local/share/zaparoo/mappings |
Where ~ is the home directory of the current user.
Install
Open a terminal and run:
curl -fsSL https://zaparoo.org/install.sh | bash
This installs all necessary components and sets up the service to run on startup. Once running, use the Zaparoo App on your phone or the built-in web UI to manage your setup and write tokens.
The same script has a few more modes:
# Show the installed version and service health
curl -fsSL https://zaparoo.org/install.sh | bash -s -- status
# Remove Core while keeping your configuration and data
curl -fsSL https://zaparoo.org/install.sh | bash -s -- uninstall
# Install beta builds instead of stable releases
curl -fsSL https://zaparoo.org/install.sh | bash -s -- --channel beta
After installation, Core checks for new releases and can update itself in place. See Core updates.
Manual install
To install without the script, download Zaparoo Core for Linux from the Downloads page, unzip it, and copy the zaparoo file somewhere like your home directory or /usr/local/bin. Then install the components you want:
./zaparoo -install application # Installs the application binary
./zaparoo -install desktop # Installs desktop integration
./zaparoo -install service # Installs systemd service
sudo ./zaparoo -install hardware # Installs udev rules and hardware support
For a complete installation, run all four commands. The hardware component adds a udev rule so users can read NFC reader serial devices and a modprobe blacklist entry that fixes ACR122U reader issues. Then enable and start the service:
systemctl --user enable zaparoo.service
systemctl --user start zaparoo.service
Service controls
Zaparoo runs as a systemd user service. Do not add sudo to these commands:
systemctl --user status zaparoo.service
systemctl --user restart zaparoo.service
systemctl --user stop zaparoo.service
systemctl --user start zaparoo.service
Uninstall
Run the install script's uninstall mode (shown above), or remove the components by hand in this order. Keep the application binary until last so it remains available for the other commands:
./zaparoo -uninstall service
./zaparoo -uninstall desktop
sudo ./zaparoo -uninstall hardware
./zaparoo -uninstall application
Client security
Linux requires encrypted connections from remote clients. Pair a phone, browser, or other client with the six-digit PIN that Core shows under Settings > Clients > Pair in the terminal UI, or run zaparoo -pair. The PIN expires after five minutes. See encryption for how paired clients and their permissions work.
Readers
| Type | Reader | Support | Setup | Notes |
|---|---|---|---|---|
| NFC/RFID | PN532 USB | Supported | Auto-detected | |
| NFC/RFID | PN532 Module | Supported | Depends on wiring | UART can auto-detect. I2C is supported. |
| NFC/RFID | ACR122U | Limited | Manual enable | Uses libnfc: MIFARE Classic writing is limited, LED and beeper do not work, and some clone variants are incompatible. |
| NFC/RFID | RC522 | Limited | Via Simple Serial | Requires a microcontroller; not a direct USB reader. |
| Barcode and QR | Zaparoo App camera | Supported | Via Zaparoo App | |
| Barcode and QR | RS-232 scanner | Supported | Manual config | |
| Optical and Media | Optical Drive | Supported | Manual config | |
| Optical and Media | External Drive | Supported | Manual enable | |
| Custom and Virtual | MQTT Reader | Supported | Manual config | |
| Custom and Virtual | Simple Serial | Supported | Manual config | |
| Custom and Virtual | File Reader | Supported | Manual config | |
| Displays and Integrations | TTY2OLED | Supported | Manual enable |
Each reader's page has setup steps and troubleshooting. See readers to compare them, or the setup guide to pick one for your setup.
Launchers
| Launcher | Description |
|---|---|
| Steam | Steam games and non-Steam shortcuts |
| Lutris | Installed Lutris games from native or Flatpak library data |
| Heroic | Installed Epic Games and GOG titles managed by Heroic |
| RetroArch | Games through the RetroArch Flatpak, with built-in core mappings and controls |
| Standalone emulators | Installed emulators found on PATH, in ~/.local/bin, as AppImages in ~/Applications, or as Flatpaks |
| EmuDeck | Systems from an EmuDeck installation |
| RetroDECK | Systems from a RetroDECK installation |
| Bottles | Programs from Bottles |
| Faugus | Games from Faugus Launcher |
| Moonlight | Streamed apps through Moonlight |
| Kodi | Movies, TV, Music (requires Kodi API) |
| Web Browser | Opens URLs in default browser |
| Shell Scripts | Custom .sh execution (allowlist required) |
See Launchers for full details and configuration.
Troubleshooting
systemctl says the unit is not found. Zaparoo runs as a user service, so use systemctl --user, not sudo systemctl. If it is still missing, run the install command again.
Permission denied opening the reader's serial port. Add your user to the dialout group (sudo usermod -a -G dialout $USER), then log out and back in.
A reader is not detected. Check the reader's page under readers for the driver and any manual configuration, and turn on debug_logging in config.toml to see what Core finds.
An emulator launcher is missing. Core only registers emulators it finds installed. Install the emulator, natively or as a Flatpak, then reload Core and update the media database.