Zaparoo Core
Zaparoo Core is the service that runs on your MiSTer, PC, handheld, or media device. It sits in the background, watches for scans from readers, reads the ZapScript from matching tokens, and launches the right game, app, script, or media file for that platform.
Core is the part of Zaparoo you install on the device that has access to your media library and launchers. The Zaparoo App, Web UI, command line tools, readers, and custom integrations all connect to or are managed by Core.
What Core does
Core coordinates the main Zaparoo system:
- Manages reader connections for NFC readers, barcode scanners, optical drives, MQTT, file readers, and other supported reader types.
- Reads token data from NFC tags, NFC toys, QR codes, barcodes, optical discs, and mapped sources.
- Applies mappings and runs ZapScript for launches, input actions, playlists, and other commands.
- Builds and searches the local media database so scans can match games, apps, videos, scripts, and other launchable files.
- Starts, monitors, and controls media through built-in or custom launchers.
- Publishes the Core API, a local JSON-RPC API used by the app, web UI, CLI, and integrations.
Installing and controlling Core
Start with the platform guides for installation steps. Each platform has its own paths, startup behavior, launchers, and reader notes.
After Core is installed, you can control it through:
- The Zaparoo App on iOS or Android.
- The embedded Web UI at
http://<device-ip>:7497/app/. - The terminal UI, when available for your platform.
- The command line, when supported by your platform.
- The Core API for custom tools and integrations.
Most Core settings live in config.toml. See the configuration reference for file locations, option names, and examples.
Core checks for new releases on its own and can install them in place when you opt in. See Core updates for how checks, automatic installs, and rollback work on each platform.
Media database and scraping
Core keeps a rebuildable media database so the app, Web UI, TUI, and ZapScript can search for games and other launchable media. Update it after adding files, installing games in a supported launcher, or changing launcher paths. Scraping is a separate step that imports local metadata and artwork into those indexed records.
The media database and scraper guide explains how to update all systems or selected systems, run scrapers, and recover a damaged media database without deleting favorites, history, mappings, or launcher overrides.
Maintenance and troubleshooting
Use these starting points for Core maintenance tasks:
| Task | Start here |
|---|---|
| Reload settings, mappings, or launchers | Reload Core from the TUI or command line |
| Restart or manage the Core service | Platform command-line flags and your platform guide |
| Find, view, or export logs | TUI logs and the log path in your platform guide |
| Update the media database or run a scraper | Media database and scraper guide |
| Back up before making changes | Device backups, local for free or automatic with Warp |
Edit config.toml | Configuration reference |
| Recover a corrupt media database | Database recovery |
| Update Core | Core updates; Update All on MiSTer and the package manager on Batocera when they installed Core |
| Uninstall Core | Your platform guide; uninstall steps are platform-specific |
Direct uninstall instructions are available for MiSTer, Batocera, LibreELEC, Linux, SteamOS, Bazzite, ChimeraOS, Windows, and RePlayOS.
Features and customization
Core includes optional features for larger setups and custom workflows. The features section covers device backups, profiles, playlists, audio playback, play controls, mappings, tags, scraping, systems, hooks, launchers, and publishers.
If you are setting up hardware, start with the readers and tokens sections first. If you already have a reader working and want to control what a scan does, start with ZapScript.
For developers
The Core API reference and the Developer Guide are maintained in the Core repository and published here automatically, so they read differently from the rest of these docs. The Zaparoo CLI is the maintained command-line client for scripts, tests, and AI agents.
A client on another device must pair with Core or send an API key on most platforms; the permissions section of the API reference lists what each kind of client can call.
Source and license
Zaparoo Core is free and open source under the GPLv3 license. The source code and releases are hosted in the Zaparoo Core GitHub repository.