Sphaira: a homebrew menu for the Nintendo Switch

A homebrew menu with its own file browser and app store

Sphaira is a homebrew menu for the Nintendo Switch, and the README points to a GBATemp thread for detail and discussion, plus a Discord server, while asking that bugs go through the issues tab because that is easier for the maintainer to track.

The bug report template is more specific than most, and it tells you what the project needs to know about its environment. You are asked to include the CFW type, the CFW version, the firmware version, the bug itself and how to reproduce it. The template even notes the assumption it makes, that the reporter is on Atmosphere, but that someone out there is still using Rajnx, so the answer is requested rather than assumed. For a homebrew application that talks to a console over unofficial channels, the environment is the bug report, and asking for it up front is a sign of a project that has seen real failure modes.

The screenshots in the README show what the menu actually contains: a homebrew list, a games list, an app store with a page view, the file browser, the launch options screen, a theme browser, a web view, and the two Ownfoil screens. So the scope is a launcher that also does installing, browsing and a couple of extras, rather than a minimal program picker.

The project is C++ under the GPL-3.0, with the default branch on master, a release history of 1.0.6 on 2026-08-15, 1.0.7 on 2026-09-09 and 1.0.8 on 2026-10-06, and a last push on 2026-10-06.

File association is what turns a menu into a launcher

The feature that distinguishes Sphaira from a plain application list is file association, and it is small enough to understand in one screen.

The idea: if your application supports loading .png files, you write an association file, and then clicking a .png in the file browser launches your application with the .png as argv[1]. The README says this was primarily added for rom loading support for emulators and frontends such as RetroArch, MelonDS and mGBA, which is the honest description of what a console homebrew menu is for in practice.

The format is an ini file:

path=/switch/your_app.nro
supported_extensions=jpg|png|mp4|mp3

The path field is optional, and the lookup rule when it is left out is worth knowing, because it is what makes the format low-friction. If the path is omitted, Sphaira uses the name of the ini to find the nro, so an ini called mgba.ini is looked for at /switch/mgba.nro and /switch/folder/mgba.nro. More examples live in assets/romfs/assoc/.

The design is deliberately minimal. There is no database and no registry, just one ini per application in a directory that the loader can enumerate, with a pipe-separated list of extensions. That is the right amount of ceremony for a homebrew environment, where adding a new emulator should not involve a configuration file format with a schema.

Installing packages from an SD card, a gamecard, FTP, USB or a hard disk

Sphaira can install applications and mod packages, with the formats listed as nsp, xci, nsz, xcz and msp, from five sources: the SD card, a gamecard, FTP, USB, and a USB hard disk.

The USB path is the interesting one because it reuses an existing protocol rather than inventing one. The USB protocol is the same as tinfoil, so tools such as ns-usbloader and fluffy should work with Sphaira, and there is also a provided Python script at tools/usb_install_pc.py for the case where you want to drive it yourself. For FTP, the README's instruction is that you connect your FTP client to the Switch and upload files into the install folder.

Connected USB mass storage devices appear in the file browser, and as a dump location, under mounts:/, and installing from them works the same as installing from the SD card. The supported filesystems are FAT12/16/32, exFAT and NTFS, with EXT2/3/4 also supported but off by default. Both of those are compile-time decisions: NTFS support is provided by NTFS-3G and can be turned off with -DENABLE_NTFS=OFF, and EXT support is enabled with -DENABLE_EXT4=ON, which also needs the switch-lwext4 package.

The NTFS notes are the part to read carefully, because they are all ways the mount can fail on a desktop system. You are told to always eject the drive properly on Windows, and that if the journal is left dirty Sphaira replays it on mount, but only when HDD write protect is off. A drive left behind by Windows fast startup or hibernation is not mounted by default, and the Mount hibernated NTFS option forces it, at the cost of the saved Windows session. And NTFS is noticeably slower than exFAT, so for installing large files exFAT is the better choice.

Sphaira can also serve files itself: FTP is enabled from the network menu and uses the same configuration file as ftpsrv at /config/ftpsrv/config.ini, and MTP is enabled from the same menu.

Ownfoil turns a file manager into a library manager

The Ownfoil integration is the part of the README that goes beyond file handling, and it is worth reading on its own terms.

Ownfoil is a self-hosted Nintendo Switch library manager that automates library curation tasks and makes backups available to install directly on the console. From Sphaira's side, local servers are found automatically on the network, so there is no IP address or port to type in. Each server can have both a local and a remote address, over http or https, and sign-in uses a user account.

The library is browsed by content, not by files. You pick a game, a version and the DLC you want, and Sphaira works out which files it needs, however they are bundled, whether that is several nsp files or a single multi-content nsp or xci. Only what you picked is downloaded and installed, and nsp, nsz, xci and xcz are supported. A download survives a broken connection, resuming for up to 60 seconds.

Entries are listed under New games, Updates, DLC, All games and Search, paginated and sortable, and all artwork is served by the Ownfoil server, so the console never connects to Nintendo's servers. That last point is the one with the most practical consequence: the metadata the menu shows does not come from the console maker's infrastructure, which matters for a homebrew menu whose entire purpose is to run outside the normal channel.

The two Ownfoil screens in the screenshots are the browser and the detail view, which matches the description of picking a game, a version and DLC.

Building it means installing devkitPro and a list of switch packages

The build instructions are complete and use CMake presets, which is the modern way to express the different build flavours.

The first requirement is devkitPro, and then the dependencies come from its package manager:

sudo pacman -S switch-dev deko3d switch-cmake switch-curl switch-glm switch-zlib switch-mbedtls switch-ntfs-3g

The switch-ntfs-3g package is only needed for NTFS support on USB hard disks, and configuring with -DENABLE_NTFS=OFF builds without it, which is the same switch mentioned in the filesystem section. For EXT2/3/4 support with -DENABLE_EXT4=ON you also need switch-lwext4. The README also asks for git, make, zip and cmake on the machine.

With that in place, the build is three commands:

git clone https://github.com/ITotalJustice/sphaira.git
cd sphaira
cmake --preset MinSizeRel
cmake --build --preset MinSizeRel

The output lands at build/MinSizeRel/sphaira.nro.

Two details are worth flagging. First, the clone URL in the README points at ITotalJustice/sphaira rather than the repository you are reading, which is the upstream author's namespace; the repository under review is NaGaa95/sphaira, so anyone following the instructions verbatim clones the upstream tree. Second, the preset name is MinSizeRel, which is CMake's minimum-size release configuration, and that choice is consistent with a homebrew application that is distributed as a single .nro file and has to fit on an SD card alongside everything else.

The top-level listing shows how the project is arranged around that: a CMakeLists.txt, a CMakePresets.json, a cmake/ directory, the sphaira/ source directory, an hbl/ directory, an assets/ directory with the romfs and the screenshots, a build_release.sh, a tools/ directory and a .github/ directory.

A Docker build for people who will not install devkitPro

The alternative to installing the toolchain is a container, and the README describes it as a convenience for people who would rather not install and manage devkitPro on their machine.

tools/nro-builder/build.sh [Release|Dev|Lite] [--send]

The image holds the same devkitA64 toolchain that the release workflow uses, plus ninja and ccache. The first build takes longer, and after that only what you changed is compiled, which is the practical effect of the ccache layer. The output is found at build/<preset>/sphaira.nro, the same path pattern as a native build.

The three presets have different purposes. Release is the default and is what the release workflow publishes. Dev skips LTO, so a one file change is immediate, which is the trade a developer wants during iteration and would not want in a published build. Lite is the third, and the README does not describe it here beyond naming it, so its exact configuration is worth finding in the CMakePresets.json rather than guessing.

The --send flag is the nicest touch. It sends the built nro straight to the console over nxlink, with the note that nxlink has to be enabled in the Network options, and you follow its log. That closes the loop between building and testing on hardware without a manual file copy, and it is the kind of small integration that makes a homebrew build usable in practice.

Licence, credits, and a project that ships every few weeks

Sphaira is GPL-3.0, which is the expected licence for a homebrew project and the one that fits its dependency list. The credits section names borealis, stb, yyjson, nx-hbmenu, nx-hbloader, deko3d-nanovg, libpulsar, minIni, the GBATemp thread, hb-appstore and haze from Atmosphere, which is a useful map of what the menu is built on: a user interface library, single-header utilities, a JSON parser, the homebrew menu it replaces, the loader that runs it, a 2D rendering layer, an audio library, an ini parser, an app store and the homebrew environment itself.

The release cadence is fast and regular. Versions 1.0.6, 1.0.7 and 1.0.8 landed on 2026-08-15, 2026-09-09 and 2026-10-06, roughly every three and a half weeks, and the last push to the repository was on 2026-10-06, the same day as the newest release. The repository is not archived.

Two final observations for anyone evaluating it. First, the bug report template asks for the firmware version, and that is the honest framing for a homebrew application: it talks to the console through a custom firmware layer, and it is tested against specific versions of that layer, so its compatibility is a moving target that the project tracks. Second, while the installer handles game package formats, what a user chooses to install and whether they hold the rights to it is a decision that belongs to them, and the tool does not change that.

Editorial conclusion

Adopt Sphaira if you run Switch homebrew and want a single menu that browses your SD card, installs packages, launches your emulators with the right file, and talks to a self-hosted library server, because those are exactly the pieces it implements and the install paths it documents. Do not adopt it expecting the original hbmenu's exact behaviour, since Sphaira is a replacement with its own file browser, its own installer and its own configuration, and the file association rules are its own format. Before you build it, install devkitPro and the switch dependencies or use tools/nro-builder/build.sh, decide whether you want NTFS and EXT4 support from the start since both are compile-time switches, and remember that installing game packages is a decision you make under your own rights rather than something the tool confers.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. NaGaa95/sphaira on GitHub
4. README
5. Releases