Platform Notes: Android

Pegasus is available for Android devices running at least Android 4.1 (Jelly Bean). For proper multimedia support, Android 4.4 (KitKat) or newer is recommended.


Pegasus is released as an APK package. To install it, you'll need to enable such files, which can be done under Settings → Security → Unknown Sources, turned on. Then open the APK file with any file manager app.

If you have an active full screen app (eg. screen shade), Android might not allow you to press on the install button due to security reasons. In this case, just disable that app for the time of the installation.

Config directory

Config files are stored under <storage>/pegasus-frontend, where <storage> the internal storage, if you have one, otherwise the SD card. The directory will be created automatically when you first launch Pegasus (or you can create it yourself).

Loading games

Compared to desktop systems, launching other applications is slightly different on Android. Instead of directly calling a program, you'll need to ask the Activity Manager (am) to open a file or start an app, optionally with additional parameters.

Here's how it looks in practice:

Open a file with the default app

The best case is when you have a file format associated with an app already. To open a file with its default app, invoke the Activity Manager like this:

am start --user 0 -a android.intent.action.VIEW -d "file://<path-to-file>"

Here is an example metadata.txt that will open ISO files with the default app:

collection: PSP
extension: iso
launch: am start --user 0
  -a android.intent.action.VIEW
  -d "file://{file.path}"


  • am is the Activity Manager program
  • the start command sends an app launching request ("intent") to the Activity Manager
  • --user 0 selects the user (by ID) that sends this request. Without this parameter I've got permission denied errors on my devices.
  • -a stands for "action"; if an app supports opening files (android.intent.action.VIEW ie. "open with"), it will react to this action. There are other possible actions, like "take a photo" or "call a taxi", but we probably won't need them for our use.
  • -d is the parameter (data) of the action, and must be in such URI format (file://...)

The full documentation of am can be found here and here.
If you're not familiar with Pegasus' config files, you can find their documentation here.

Note that not every app supports opening arbitrary files, or opening files at all (for example, RetroArch). In addition, there seems to be a glich on some systems where a file may get opened with something else when there are multiple apps that can handle the file type. Which leads to...

Open a file with a specific app

Unfortunately opening a file with anything else than the default is a bit painful. To open the file, you have to know the exact name of the app component ("activity") that handles file opening requests. For example, for the Android version of the PPSSPP emulator, this is org.ppsspp.ppsspp/.PpssppActivity.

I haven't found a good app yet that could tell this about the installed apps, so I guess the best bet for now is either asking the developers for a particular app or looking into its source code (tip: it's always in AndroidManifest.xml). I've also made a small collection which you can find at the bottom of this page.

Anyway, once you know the Activity you want to call, the command is

am start --user 0 -a android.intent.action.VIEW -n <activity-name> -d "file://<path-to-file>"


-n stands for "name"

Here is an example metadata.txt that will open ISO files with PPSSPP:

collection: PSP
extension: iso
launch: am start --user 0
  -a android.intent.action.VIEW
  -n org.ppsspp.ppsspp/.PpssppActivity
  -d "file://{file.path}"

Run a custom command

Some apps simply don't support opening files, for example because they rely on a built-in file browser or some other reasons. The way to call these apps may differ from what's described above, or they might need additional parameters. You'll have to ask the developers or look around the source code in this case. See below for some examples.

App-specific notes


RetroArch happens to use a large number of custom parameters. It can be launched like this:

collection: NES
extensions: zip
launch: am start --user 0
  -n com.retroarch/.browser.retroactivity.RetroActivityFuture
  -e ROM "{file.path}"
  -e LIBRETRO /data/data/com.retroarch/cores/
  -e CONFIGFILE /storage/emulated/0/Android/data/com.retroarch/files/retroarch.cfg
  -e IME
  -e DATADIR /data/data/com.retroarch
  -e APK /data/app/com.retroarch-1/base.apk
  -e SDCARD /storage/emulated/0
  -e DOWNLOADS /storage/emulated/0/Download
  -e SCREENSHOTS /storage/emulated/0/Pictures
  -e EXTERNAL /storage/emulated/0/Android/data/com.retroarch/files

(based on the source code of their Android port at the time of writing).

The important parts here are the core and the storage paths. Make sure you correct the paths of the above example to match your system and collection:


-e KEY VALUE defines an extra parameter, specific to the app. Unlike the file opening before, RetroArch does not need file:// for the ROM path.

Known emulators

Here's an incomplete list of emulators that can open external files using android.intent.action.VIEW. If you think some some of the entries are incorrect, or you'd like to extend this list, feel free to open an Issue here.

App nameActivity
Emulator for NES/SNES - Arcade Classic Gamesno support
John emulatorsno support
MegaN64no support
Mupen64 Plus
Nostalgia.NESno support
SuperRetro16 Litecom.bubblezapgames.supergnes_lite/com.bubblezapgames.supergnes.IntentFilterActivity

Additional notes