| name | mister-remote |
| description | Drive a MiSTer FPGA over its mrext Remote HTTP API (default mister.local:8182). Use when the user asks to launch a core/game on the MiSTer, send keystrokes, take or download a screenshot, send the MiSTer reset key, reboot the MiSTer, browse files on the device, search the games index, manage wallpapers, control the music player, run scripts, or read/write MiSTer.ini settings. Wraps the wizzomafizzo/mrext remote API. |
mister-remote
Wrapper around the wizzomafizzo/mrext Remote HTTP API. The MiSTer must be running the Remote service (default port 8182). All operations go through one helper script.
When to use
Trigger phrases:
- "launch the Oric core / launch system X on the mister"
- "launch this game / load this disk on the mister"
- "press menu / osd / arrow / reset on the mister"
- "send these keystrokes to the mister"
- "take a screenshot from the mister" / "download the latest screenshot"
- "reset the (mister) core" / "send reset"
- "reboot the mister"
- "list / browse cores in /media/fat/..."
- "search the mister games index for X"
- "what's the active mister wallpaper?" / "set wallpaper Y"
- "play / stop / next mister music"
- "list / run mister scripts"
- "read / edit MiSTer.ini" / "switch active INI"
- "list peer mister devices"
Do not use for source-level actions (compile, deploy .rbf) — those go through tools/oric-build.
Default config
- Host:
mister.local (override with --host or env MISTER_HOST)
- Port:
8182 (override with --port or env MISTER_PORT)
- Timeout: 5 s (helper auto-extends for
reboot and settings-remote-restart)
Helper script
python3 .claude/skills/mister-remote/scripts/mister-remote.py <subcommand> [args]
JSON-returning commands print pretty JSON on stdout. Errors go to stderr with a non-zero exit code. Destructive commands require --yes.
System info
| Subcommand | Endpoint | Notes |
|---|
sysinfo | GET /sysinfo | hostname, ips, dns, version, disks |
generate-mac | GET /settings/system/generate-mac | proposes a fresh MAC address |
Games
| Subcommand | Endpoint | Notes |
|---|
playing | GET /games/playing | currently running core/game |
games-search <query> [--system <id>] | POST /games/search | full-text search the indexed corpus |
games-search-systems | GET /games/search/systems | systems with an indexed corpus |
games-index | POST /games/index | rebuild the search index (async) |
Systems / launching
| Subcommand | Endpoint | Notes |
|---|
systems | GET /systems | id / category / name (tab-separated) |
launch-system <id> | POST /systems/{id} | boot a core by system id |
launch <path> | POST /launch | generic launcher: .rbf, .mra, .mgl, game files |
launch-game <path> | POST /games/launch | launch a game by absolute path |
launch-menu | POST /launch/menu | exit running core, soft reset to MiSTer menu |
launch-new <gamePath> <folder> <name> | POST /launch/new | create a new launcher file pointing at gamePath |
launch-encoded <data> | GET /l/{data} | launch from a base64-url-encoded payload (QR / NFC) |
File browser (Menu)
| Subcommand | Endpoint | Notes |
|---|
menu-view <path> | POST /menu/view | list a directory; response items have path/name/type/extension |
menu-create <type> <folder> <name> | POST /menu/files/create | create a file / folder |
menu-rename <fromPath> <toPath> | POST /menu/files/rename | rename / move on the device |
menu-delete <path> --yes | POST /menu/files/delete | delete a file (requires --yes) |
Controls (keystrokes)
| Subcommand | Endpoint | Notes |
|---|
key <name> | POST /controls/keyboard/{name} | one named keystroke (validated client-side) |
key-raw <code> | POST /controls/keyboard-raw/{code} | raw uinput key code |
keys <n1> <n2> ... | (loop over key) | sequence of named keys with --delay between |
reset-core | POST /controls/keyboard/reset | send MiSTer's reset key (alias for key reset); this is not a guaranteed cold core restart |
Screenshots
| Subcommand | Endpoint | Notes |
|---|
screenshot | POST /screenshots | fire-and-forget capture (returns empty stub) |
screenshot-list | GET /screenshots | list all stored screenshots |
screenshot-get <core> <filename> [--out PATH] | GET /screenshots/{core}/{filename} | download one PNG |
screenshot-delete <core> <filename> --yes | DELETE /screenshots/{core}/{filename} | delete one (requires --yes) |
screenshot-capture-and-download [--out PATH] | capture + poll + download | recommended path; see workflow below |
Wallpapers
| Subcommand | Endpoint | Notes |
|---|
wallpapers | GET /wallpapers | list available + active + background mode |
wallpapers-clear --yes | DELETE /wallpapers | clear active wallpaper |
wallpapers-get <filename> [--out PATH] | GET /wallpapers/{filename} | download one image |
wallpapers-set <filename> | POST /wallpapers/{filename} | set as active |
Music player
| Subcommand | Endpoint | Notes |
|---|
music-status | GET /music/status | running / playback / playlist / track |
music-play | POST /music/play | start playback |
music-stop | POST /music/stop | stop playback |
music-next | POST /music/next | skip to next track |
music-playback <type> | POST /music/playback/{type} | mode: random / loop / single (server-validated) |
music-playlist | GET /music/playlist | list available playlists |
music-playlist-set <name> | POST /music/playlist/{name} | switch active playlist |
Scripts
| Subcommand | Endpoint | Notes |
|---|
scripts-list | GET /scripts/list | scripts in /media/fat/Scripts/ (incl. canLaunch) |
scripts-launch <filename> | POST /scripts/launch/{filename} | run a script |
scripts-console | POST /scripts/console | toggle the on-screen script console |
scripts-kill --yes | POST /scripts/kill | kill the running script |
Settings — INI files
| Subcommand | Endpoint | Notes |
|---|
settings-inis | GET /settings/inis | list configured INIs and which is active |
settings-inis-set <int> | PUT /settings/inis | switch active INI by id |
settings-ini-get <id> | GET /settings/inis/{id} | read INI as a JSON dict |
settings-ini-set <id> --from-file PATH | PUT /settings/inis/{id} | write a key-value JSON dict (--from-stdin also works) |
settings-menu-mode <mode> | PUT /settings/core/menu | set the OSD menu mode |
Settings — Remote service
| Subcommand | Endpoint | Notes |
|---|
settings-remote-restart --yes | POST /settings/remote/restart | restart the Remote service (will briefly drop the API) |
settings-remote-log [--out PATH] | GET /settings/remote/log | download the service log |
settings-remote-peers | GET /settings/remote/peers | list known peer devices |
settings-remote-logo [--out PATH] | GET /settings/remote/logo | download the logo asset |
System lifecycle
| Subcommand | Endpoint | Notes |
|---|
reboot --yes | POST /settings/system/reboot | full MiSTer restart (~30 s offline) |
Valid keystroke names
Pass any of these to key or keys:
up down left right
volume_up volume_down volume_mute
menu back confirm cancel osd
screenshot raw_screenshot
pair_bluetooth change_background
core_select user reset
toggle_core_dates console exit_console
computer_osd
Most useful: reset, osd, menu, screenshot, arrow keys, confirm/cancel. Unknown names are rejected client-side.
Reset Semantics
For Oric core work, treat a true cold core start as a launch of the RBF or
MGL, not as reset-core. Use:
python3 .claude/skills/mister-remote/scripts/mister-remote.py launch /media/fat/_Aoric/Oric.rbf
or launch the relevant .mgl.
| User says | Use |
|---|
| "cold boot the Oric core" / "start fresh" | launch /media/fat/_Aoric/Oric.rbf or launch the target .mgl. This is the reliable core cold-start path. |
| "press reset" / "send reset" | reset-core or key reset. Sends MiSTer's reset key; depending on the running context it may leave the core and return to MENU. |
| "soft reset to menu" / "exit core" | launch-menu. Drops back to the MiSTer main menu without rebooting. |
| "reboot mister" / "restart the mister" | reboot --yes. Full system restart. Confirm with the user first. |
| "restart the remote service" | settings-remote-restart --yes. Bounces only the Remote daemon (~5 s API outage). |
Screenshot workflow
POST /screenshots is fire-and-forget — it returns an empty stub and the file is written asynchronously. screenshot-capture-and-download snapshots the listing, posts the capture, then polls GET /screenshots until a new entry appears (timeout: max(--timeout, 10s)):
python3 .claude/skills/mister-remote/scripts/mister-remote.py screenshot-capture-and-download
prints e.g.:
{
"core": "Oric",
"filename": "20260510_190406-screen.png",
"saved_to": "/home/niki/projects/Oric_MiSTer/mister_screenshots/20260510_190406-screen.png"
}
Default destination: ./mister_screenshots/<filename> in CWD. The folder is auto-created and mister_screenshots/ is gitignored. Override with --out /path/file.png (exact path) or --out /path/dir/ (existing/trailing-slash dir).
Discovering content
menu-view mirrors the MiSTer file browser. Useful starting points:
/media/fat/_Computer — official Computer cores (Oric, Atari ST, BBC, etc.)/media/fat/_Aoric — this repo's dev/test build directory (timestamped + Oric.rbf)/media/fat/_Console, /media/fat/_Arcade, /media/fat/_Other — sibling category folders/media/fat/Scripts — scripts available to scripts-launch/media/usb0/games/Oric/dsk — Oric .dsk images on USB
Each item carries path / name / filename / extension / type / modified / size. Pass path to launch to start it.
For text searches, prefer games-search <query> if the games index has been built (games-index to (re)build).
Launching Oric content
Oric .dsk images live at /media/usb0/games/Oric/dsk/ (USB, not SD). Examples:
... launch-game /media/usb0/games/Oric/dsk/Cobra-Pinball.dsk
... launch-system Oric # boot Oric core to BASIC, no media
... launch /media/fat/_Aoric/Oric.rbf # cold boot a specific dev RBF
Error recovery
- Connection refused / DNS failure: ask the user to
ping mister.local. If that fails, fall back via --host <ip> (the build script uses 192.168.0.108).
- HTTP 4xx/5xx: helper prints the response body to stderr; surface to user.
- Remote service not running: live in
/media/fat/Scripts/ on the device — suggest enabling it.
Confirmation guards (commands that need --yes)
reboot — full system restartscreenshot-delete — deletes a filewallpapers-clear — clears active wallpapermenu-delete — deletes a file on the devicescripts-kill — kills a running scriptsettings-remote-restart — drops the API briefly
When the user asks for any of these, confirm intent before passing --yes.
Out of scope (deliberate)
- WebSocket transport — no live key-hold, no chord/combo support. (Endpoints
kbd:, kbdRaw:, kbdRawDown:, kbdRawUp:, getIndexStatus and the coreRunning / gameRunning / menuNavigation / indexStatus event stream are not exposed by the helper.)
- TLS / auth — the API is plain HTTP, no auth.
