...or any other third-party app on your KaiOS device!
This page will explain everything you need to know about installing third-party applications on KaiOS. "INSTALL OMNISD" is an introductory guide on the purpose and usefulness of the Jailbreak of all KaiOS devices, and focused on the safest methods (OFFICIAL JAILBREAK and CACHE INJECTION), aimed at not interrupting official updates.
Use the following index to better navigate in this page:
How to install any app on KaiOS / Firefox OS normally
The sideload is the process of transferring files between two local devices, in particular between a computer and a mobile device. On Firefox OS it was a natural property, and it can be done using ADB and DevTools also on more KaiOS devices (source). The installation of OmniSD is a classic example.
Many devices can sideload third-party apps, but other devices require special patches (check the list). Let's start by seeing how to sideload naturally, before moving on to jailbreak.
ADB, a versatile command-line tool that allows you to communicate with a device;
Enable the debug mode on your device;
Connect the device to the PC using a USB cable;
Open WebIDE and connect to the "Remote runtime" (this should work on the official Kaiostr emulator), if not seen, start the "adb forward tcp:6000 localfilesystem:/data/local/debugger-socket" command and click again on "Remote runtime". If an error message about build date mismatch appears, you can safely ignore it. If the connection doesn't work, try rebooting the phone, running the "adb forward" command and connecting again.
Select the application's folder in the "Open packaged app" button of WebIDE.
With the triangular "Play button" at the top center of WebIDE, the app will be installed on your phone.
Jailbreak on KaiOS: all you need to know
Difference between "normal sideload" and "Jailbreak"
The official jailbreak method differs from the normal sideload only in the fact that, after point 5, a "privileged factory reset" is required directly from the jailbreak application that we will install (OmniSD, Wallace or Wallace-Toolbox) by pressing the # key from it, in order to automatically activate all the "Developer" options. After the reset, you will need to repeat the whole procedure if you want to use these applications for a different use (sideload without PC or root permissions).
The privileged mode, as the word itself says, is a boot mode in which the user has full control over the development tools and hidden components of the device, such as the "Developer" menu in the "Settings" app, you can also debug on the pre-installed applications and access the "Device Preferences" from WebIDE.
This mode still allows you to obtain updates, and can be removed simply by performing a normal factory reset from the Settings app or from Recovery mode.
How jailbreak works on KaiOS (diagram)
After two years of research, we have finally come to a precise pattern on how jailbreak works on different KaiOS devices. The approach is based on the type of processor used on the device, Qualcomm, Spreadtrum or Mediatek. Thanks to this study, we managed to jailbreak many different KaiOS devices. This diagram is provided by Luxferre, and here the five situations:
SITUATION 1, typical of Qualcomm-based devices. If the code *#*#33284#*#* needed for debugging works, we must verify if we have access to ADB and WebIDE. If all goes well we can use OmniSD or Wallace Toolbox to get the jailbreak;
SITUATION 2, typical of Spreadtrum-based devices. If the code *#*#33284#*#* needed for debugging works, we must verify if we have access to ADB and WebIDE. If the result is negative, enable debugging using the code *#*#0574#*#* and retry the access to ADB and WebIDE. If all goes well we can use Wallace-toolbox to get the jailbreak;
SITUATION 3, typical of Mediatek-based devices. The debug code does not work, let's check if Fastboot is available. If we have it, let check if it is possible to flash the "cache" partition. If all goes well, use the so-called "cache injection" method, and we will get the "Developer" menu;
SITUATION 4, typical for all the locked devices. The debug code does not work and Fastboot is not available even to flash the partitions. Let's check if we have other tools to flash the partitions. If yes, we can use the "cache injection" method, and we will get the "Developer" menu;
SITUATION 5. The debug code does not work, Fastboot is not available and we don't even have tools to flash the partitions. Jailbreak is not possible yet.
As you can see, not all KaiOS devices have the same possibilities. To help users better understand which installation method is more suitable, have classified KaiOS devices. Learn more here:
W2D: enable the Developer menu from the browser
This new method was born on Discord from an idea of Luxferre and Tbrrss on September 22, 2020 and is ideal for temporarily bringing up the Developer menu, so that you can enable easily ADB and DevTools.
This is probably the easiest and most versatile way of jailbreaking most existing KaiOS-based phones. We decided to call it W2D (web-to-dev) because it's based on the hidden but totally official (as confirmed by Fabrice, KaiOS architect) fact that MozActivity class is visible from the browser context.
It just calls a hidden activity in the Settings app that opens the developer menu directly:
As for usage, it's very simple for most KaiOS phones:
2. Enable first ADB, then "ADB & DevTools" in the Debugger menu item. Check that the bug icon appears in the panel;
4. Using Wallace Toolbox, just select # key ("Enable developer menu") and reboot the phone when prompted, or perform a privileged factory reset using OmniSD;
5. After reboot, ensure that the Developer menu is still present in the Settings > Device and you can connect to the phone in privileged mode.
What is OmniSD and why it is so important
OmniSD detects packaged applications in zip format present in the "downloads" or the "apps" folder of the sd card or the internal memory to then install them (jailbreak).
Another feature of this application is the ability to get a "Privileged Factory Reset" by pressing the # key while the app is running. This enable the "Developer" menu within the "Settings" application on the system, allowing the user to access ADB and DevTools directly from the menu.
OmniSD accepts app packages in the .zip format. An archive must contain three files:
application.zip file (with the actual WebIDE-compatible KaiOS/FFOS app);
update.webapp file (can be empty but must be present);
metadata.json file in the following format:
where [your_app_id] has to be replaced with the actual ID (origin) of your app registered in the manifest, and manifest.webapp has to be renamed if it's called differently in the application.zip archive. Other than that, the application structure in application.zip must match the general KaiOS and Firefox OS app structure. Learn more here:
Other applications similar to OmniSD
Luxferre has created various projects, including a custom privacy-oriented rom (GerdaOS) and a real library of extensions and various tools for KaiOS. Here are some applications developed by him, containing some features in common with OmniSD:
GerdaOS File Manager, a modified version of the stock File Manager for KaiOS, that installs omnisd packages by not limiting itself to the "download" and "app" folders, unlike OmniSD;
Wallace (see the "Temporary Root" page) is an application that enables root privileges and can perform "privileged reset". A classic version, a light version (without adbd binary file) and an optimized version for devices with Spreadtrum chipset are available for this app;
Best safe Jailbreak methods
A safe jailbreak method consists in working exclusively on /cache or /userdata, the only two dynamic partitions, subject to various changes and events due to the use of the user from the first start. If these partitions are damaged, simply perform a factory reset to restore everything (when you perform "wipe data / factory reset" from recovery mode you are cleaning both /cache and /userdata).