What Is PortMaster? How to Play PC Game Ports on Retro Handhelds

Stardew Valley, Balatro, Half-Life and Celeste, running on a handheld that was built to play Game Boy games. That’s what PortMaster does. It’s a free app for Linux-based handheld firmware that installs PC games rebuilt to run on these little ARM chips, sets up their controls for you, and handles the bits behind the scenes. One twist: my Steam Deck can run it today, and the Miyoo Mini Plus, about as retro as handhelds get, can’t. This guide covers what PortMaster is, where it runs, how to get it going, and how to add the games that need your own copy.

What PortMaster actually does

Think of it as an app store for game ports. You open it, browse, pick a game, and it downloads the port, puts the files where your firmware expects them and maps the controls so the game works with the handheld’s buttons. Volunteers PortMaster calls Port Navigators set up most ports so they launch with sensible controls on the devices it supports.

A port is a PC game rebuilt to run on hardware it was never made for. Some are open-source games compiled straight for the low-power ARM chips these handhelds use. Others are fan-made engines that read the original game’s files. Plenty of ports lean on the same few engines, so PortMaster downloads each engine once and shares it between games. That saves space on a small card. It’s also designed to leave your firmware’s own libraries alone. Anything unusual a port needs lives in that port’s own folder.

It began in 2021 as a script by christianhaitian, the developer behind ArkOS. Since 2023 it’s been a rebuilt app, with kloptops as lead developer. Still free. Still run by volunteers, and they take donations through Open Collective.

Ready to run, or files needed

Every port falls into one of two camps, and it’s worth knowing which before you get attached to a game.

Ready-to-run ports come with everything. These are free and open-source games, or games whose makers allowed it, like Celeste 64, Spelunky Classic, VVVVVV, SuperTux, Sonic Robo Blast 2 and OpenTTD. Some even include a shareware version of a bigger game: DevilutionX comes with the Diablo shareware, and the Quake port comes with Quake’s shareware episode, with room for your full copy later.

Files-needed ports bring the engine and the controls, and you bring the game. That’s how Stardew Valley, Balatro, Half-Life, Undertale, Celeste, TMNT: Shredder’s Revenge and FEZ work. The version you own matters. Take Stardew Valley. It now comes as two ports. The main one wants the Windows version from Steam, and Stardew Valley Compatibility works with the compatibility version from Steam or GOG. Every port’s page on portmaster.games spells out the version and the files, so check it before you buy. And those files have to come from a copy you bought or otherwise got legitimately. That’s PortMaster’s rule.

Where it runs

PortMaster is made for Linux firmware on ARM handhelds. Its own device list is marked as outdated, so don’t lean on it. Look at the firmware instead. ROCKNIX, Knulli, muOS, ArkOS, dArkOS and AmberELEC get full support, and UnofficialOS gets partial support.

What decides it is whether your handheld can run one of those firmwares. My Odin 2 Portal Max can, through ROCKNIX from a microSD card, which uses the same bootloader method I covered in my Armada guide for AYN handhelds. Plenty of popular handhelds can’t, though. The Miyoo Mini Plus usually runs Onion OS, which has its own Ports Collection instead, and the KONKR Pocket Advance has no Linux firmware at all.

Getting PortMaster on your handheld

Check first, because on most firmwares it’s already there. ROCKNIX, muOS and ArkOS bundle it, Knulli installs it from Device Settings, and RetroDECK includes it. If yours doesn’t, PortMaster’s installation page has two installers: a small one that downloads shared engines as games need them, and a full one, around 630 MB, with everything included, which it recommends for handhelds that won’t be online.

Copy the installer into your firmware’s folder for it, then run it from that menu: Ports on most firmwares, Tools on ArkOS.

PortMaster has stable and beta update channels under Options, plus a hidden alpha one. The newest download on its GitHub page is often an alpha build, so don’t assume “latest” means stable. To update, use Options, then Update PortMaster, and check the version shown at the bottom of the screen.

Installing your first port

Open PortMaster and you’ll see Featured Ports, All Ports, Ready to Run Ports and Manage Ports. The list only shows games that suit your handheld’s screen, sticks, memory and chip, which saves you from installing something that can’t run. Pick a game, install it, and it appears in your firmware’s Ports list, though some firmwares need you to refresh the game list first.

Start with something from Ready to Run Ports to get a feel for it. When you’re done playing, Start and Select together closes most ports, since that’s the exit combo built into PortMaster’s control tool.

Adding files from a game you own

For a files-needed port, install it from PortMaster first, then copy your files in. The port’s page tells you which files and exactly where they go. Take Half-Life. Find the valve folder in your Steam copy of the game and copy it into Half-Life/valve, inside your firmware’s ports folder. That’s it. Most other ports work the same way, with a gamedata or assets folder waiting for your files.

Be patient on the first launch. Some ports spend several minutes compressing or repacking your files the first time, and it can look stuck while it works. After that, they start normally.

When something won’t run

A few problems come up often enough to know about. On Knulli, the card format can bite. Big microSD cards usually come as exFAT, and some older ports use a kind of file shortcut that exFAT can’t handle, so they won’t save or won’t start. Knulli has said only about 25 ports are still affected. Formatting the card as ext4, the Linux format, avoids it. If a port fails for some other reason, look for a log.txt in its folder. PortMaster’s Discord has a help channel for ports too.

Without Wi-Fi, you can still install ports: download a port’s zip from portmaster.games and drop it, still zipped, into PortMaster’s autoinstall folder, which on ROCKNIX is /roms/ports/PortMaster/autoinstall/. Ports that need a shared engine also need that runtime, which is why the full installer is the one to use for a handheld that stays offline. To update a port, reinstall it from PortMaster, which normally keeps your game files and saves. To remove one, use Manage Ports.

On a Steam Deck or another PC handheld

Back to that twist from the top. PortMaster also comes as an x86 build, the kind of chip a PC uses, and RetroDECK, the emulation front end for the Steam Deck, includes it. You launch PortMaster from RetroDECK’s menu, install ports, then rescan your games so they show up. About 350 ports are marked for the Steam Deck, and more than 200 of those are ready to run. That’s a slice of the catalogue, and RetroDECK is upfront that not every port has made it to x86 yet. It runs on other Linux handhelds too, with Bazzite and SteamOS among its recommended systems. Windows misses out. There’s no PortMaster for it at all.

On Android handhelds

There’s no official Android version. You’ve got two routes. The supported one is putting a Linux firmware on the handheld, which is how an Odin 2 Portal like mine could get PortMaster through ROCKNIX. The other is Starboard, an unofficial app that runs part of the catalogue inside Android, and you don’t have to root the device (unlock Android’s system files) to use it. It isn’t a PortMaster project, and both sides are clear about that. One PortMaster developer estimated about half the catalogue runs on it, often at unplayable frame rates. Treat it as an experiment.