Sideloading and debugging third‐party applications

As with many other KaiOS 2.5.4 devices, the 6300 4G is classified as debug-enabled: this means that you can install and debug apps from outside sources as you wish. However, this comes with a few caveats: you cannot install apps with 'forbidden' permissions (embed-apps, embed-widgets and engmode-extension, such as Wallace Toolbox), or debug apps that come with the phone using WebIDE's DevTools; although you can check the global warnings and errors with adb logcat.

Do note that OmniSD, one method used for on-device sideloading, plus many Gerda-related apps do NOT work on this phone. They require the navigator.mozApps.mgmt.import API that has been removed from KaiOS 2.5.2.2. However, the Privileged factory reset feature that could be used on KaiOS 2.5.2 and older can now be activated after permanent rooting to gain privileged userspace session.

ADB and WebIDE

Note

• This guide is only applicable on debug-enabled KaiOS 2.5 devices, and is no longer relevant for recent versions. In 2021, Mozilla partnered with KaiOS Technologies to "modernize the old Boot2Gecko codebase to run atop a modern Gecko so that it can be used by KaiOS as a basis for their future phones"^1, and completely redesigned WebIDE in the process (currently included in Firefox Developer Edition). For debug-enabled KaiOS 3 devices, follow the instructions on using KaiOS’s in-house appscmd on the official Developer Portal.
• Before proceeding, make sure that your phone is debug-enabled, or you have taken steps to enable debugging capability on your phone. To check if your phone is debug-enabled, go to Devices page on BananaHackers Wiki.
• Be careful when installing apps from unknown sources; it's never a bad practice to proof-read their source code. While there are certain security practices, such as prohibiting installing apps with engmode-extension permission, KaiOS is still prone to malicious code^2 ^3 which can result in performance degradation, data loss or worse.

Not to be confused with jailbreaking on iOS devices, which is the act of using exploits to gain elevated permissions and bypass Apple's security restrictions on their devices.

Now, let's learn how to sideload and debug an application on your KaiOS phone using ADB and WebIDE. This will let us install apps which might be not available from KaiStore, or ones that you are developing.

ADB, short for Android Debug Bridge, is a powerful toolset that can be used on Android-based devices to unlock access to a range of functions beyond what the typical user interface provides. It's mainly designed for app developers to get access to system logs and debug the performance of their apps, but it's also a great tools for power users and enthusiasts to control their phones through shell access, install third-party APKs, tweak the system and restore it from being a dead paperweight.

While KaiOS and Firefox OS are not directly based on Android and you cannot install APKs on them, their Gonk layer makes significant use of Android's well-established hardware compatibility, including the ability to use ADB to interact with the phone through a computer.^4 This is for the sake of deploying the OS onto different hardware without raising the cost for development.

Meanwhile, WebIDE, short for Web Integrated Development Environment, allows you to create, edit, run and debug web applications on Firefox OS (and later KaiOS) devices and simulators. It's built on the former Firefox OS App Manager^5 but with additional functions such as a code editor, boilerplate code templates and manifest validation, and includes Firefox debugging tools. With it, you can also connect your browser to one or multiple "runtimes" where you can manage app installation.

We'll refer to this guide as the main, officially supported method of installing third-party apps onto your KaiOS phone, for the sake of simplicity. Other methods, such as Luxferre's CLI gdeploy, are also available.

What we'll need

1. Turn on debugging mode on the phone by dialing *#*#debug#*#* on the home screen.

• If you're connecting to a Linux-based PC, you may need to go to Settings > Storage and turn on USB Storage for udev to properly register your phone as an USB peripheral. Another icon in the status bar will appear indicating storage access via USB.

2. Connect the phone to a computer with an USB cable. On the computer, download Android Debug Bridge: Windows, macOS, Linux

• If your operating system has a package manager, you can utilize that to quickly install and set up ADB (skip step 3 when done):
  • Windows: choco install adb
    (winget prohibits installing executables with symlinks)
  • macOS: brew install android-platform-tools
  • Linux (Debian/Ubuntu): sudo apt-get install adb
  • Linux (Fedora): sudo dnf install android-tools
  • Linux (Arch): sudo pacman -S android-tools

3. Extract the downloaded archive to a folder (double-click the file on macOS/Linux, 7-Zip > Extract here on Windows), navigate to its platform-tools root and open Command Prompt/Terminal within it.
4. Type adb devices to start the ADB server. If a device shows, that means your phone is being detected by ADB and you're good to go.
5. Download and install either the latest version of Waterfox Classic, Firefox 59/ESR 52.9 or Pale Moon 28.6.1 corresponding to your operating system.

• Firefox 59 (ESR 52.9): the last official Firefox version to bundle with working WebIDE and other tools for development on Firefox OS devices, before Mozilla decided to kill the project in 2016. Archives of all Firefox releases can be found on https://archive.mozilla.org.
• Pale Moon 28.6.1 (Windows/Linux): a popular fork of Firefox with older user interface, legacy Firefox add-on support and always running in single-process mode. Archives of all releases can be found on https://www.palemoon.org/archived.shtml.

6. Open the browser and press Shift + F8 (or select Menu > Developer > WebIDE) to open the WebIDE window.
7. Your phone's name should already appear in the right pane. Click it to connect. If you don't see any, type this into the command-line window:

adb forward tcp:6000 localfilesystem:/data/local/debugger-socket

• In WebIDE, click Remote Runtime, leave it as default at localhost:6000 and press OK.
• If you're using other means to access WebIDE such as Firefox v59 or Pale Moon <28.6.1, you may now see a warning header about mismatched build date. You can safely ignore it as WebIDE was mainly designed to support Firefox OS device builds released alongside that Firefox/Pale Moon versions.

8. To sideload an app, download it and extract its ZIP content (if you see an OmniSD-packaged application.zip you may need to extract that). Select Open Packaged Apps in WebIDE's left sidebar and navigate to the root of the app folder you just extracted.
9. Once you've got the app loaded, press the triangle Install and Run in the top bar to sideload, or click the wrench to open the Developer Tools for debugging.

Tip: If you've downloaded the SDK package from Android Developers' website, for quicker access to ADB next time, include the extracted ADB folder in PATH. We won't cover this here as this would be a lengthy process. This will be automatically handled if you've installed ADB via package manager.

gdeploy

gdeploy is a small cross-platform command-line utility developed by Luxferre as an alternative to the graphical WebIDE, and can even be used as NodeJS module/library. According to Luxferre, 'it uses the same firefox-client backend but has much simpler architecture for application management'.

For Windows 10 version 1709 and later, type these commands one by one into Command Prompt, with [DIR_PATH] replaced by the extracted folder directory of the app you want to install (see step 8 above):

winget install Git.Git
winget install OpenJS.NodeJS.LTS
cd /d "%USERPROFILE%\Desktop"
git clone https://gitlab.com/suborg/gdeploy.git
curl -Lo platform-tools.zip https://dl.google.com/android/repository/platform-tools-latest-windows.zip
tar -xf platform-tools.zip
cd platform-tools\
adb devices
adb forward tcp:6000 localfilesystem:/data/local/debugger-socket
cd ..\gdeploy\
npm i && npm link
gdeploy install [DIR_PATH]

For macOS and Linux, if you have Homebrew installed as a package manager:

brew install git node android-platform-tools
cd ~/Desktop
git clone https://gitlab.com/suborg/gdeploy.git
adb devices
adb forward tcp:6000 localfilesystem:/data/local/debugger-socket
cd gdeploy
npm i && npm link
gdeploy install [DIR_PATH]

Other means of sideloading

• KaiOS RunTime (Linux): official developing environment for KaiOS 2.5 made by KaiOS Technologies. To download and set up KaiOSRT on Ubuntu, type these commands one-by-one in Terminal:

wget https://s3.amazonaws.com/kaicloudsimulatordl/developer-portal/simulator/Kaiosrt_ubuntu.tar.bz2
tar -axvf Kaiosrt_ubuntu.tar.bz2
cd kaiosrt-v2.5-ubuntu-20190925163557-n378
tar -axvf kaiosrt-v2.5.en-US.linux-x86_64.tar.bz2
cd kaiosrt
./kaiosrt

It's also possible to get KaiOSRT to work on Windows 10 and later using Windows Subsystem for Linux (WSLg). See this video on YouTube for action.

• Make KaiOS Install: another command-line tool to install apps using KaiOS's remote debugging protocol.

To remove unwanted apps from the phone, you can use this fork of Luxferre's AppBuster which lets you disable any apps you don't need and enable them again if you want.