Skip to content

Sideloading and debugging third‐party applications

Jump to bottom
Bùi Minh Đức edited this page Jun 11, 2024 · 46 revisions

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 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 need

  • a phone running KaiOS 2.5 (again, KaiOS 3 users should NOT follow this guide);
  • a x86_64 computer running Windows, macOS or Linux;
  • an USB cable with data transferring capability;
  • an Internet connection for both your phone and computer;
  • an archiver: built-in file manager on macOS/Linux, 7-Zip or WinRAR on Windows;
  • latest version of Android Debug Bridge (ADB): Windows, macOS, Linux
  • Mozilla got rid of the old WebIDE since Firefox 59, so we'll have to install an older version of Firefox:
    • Waterfox Classic: the most recently maintained browser which still has old WebIDE
    • Pale Moon 28.6.1 (Windows/Linux): a popular fork of Firefox with older user interface, legacy Firefox add-on support and always runs in single-process mode.
    • Firefox 59 (ESR 52.9): the last official Firefox version to be bundled 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 here.

Turn on debugging mode & ADB

  1. Turn on debugging mode on your phone.
    • This step will vary for each device, from as simple as dialing debug codes *#*#33284#*#* on Qualcomm devices and *#*#0574#*#* on Spreadtrum devices, change the hidden Debugging setting to ADB and DevTools, or as complicated as modifying the filesystem on MediaTek devices.
    • It's recommended to take a look at your specific phone in Devices page on BananaHackers Wiki.
  2. Connect your phone to the computer with the USB cable.
  3. On the computer, install or download the SDK tools on Android Developers' website, which contains ADB.
    • Extract the downloaded archive to a folder. On macOS or Linux, you can double-click the file and let the file manager do the job; on Windows, right-click the file, select 7-Zip's or WinRAR's context menu, then choose Extract here.
    • Open the extracted platform-tools folder using Command Prompt or Terminal. On macOS or Linux, open Terminal, navigate to the folder with cd Downloads/platform-tools (or wherever you extracted the folder). On Windows, open the platform-tools folder with Explorer, select the address bar, type cmd and press Enter.

  1. Type adb devices to start the ADB daemon. ADB will automatically detect your phone in debugging mode. If you see a device, you're good to go! Otherwise:
    • if the operating system states that adb is not a valid command, check if you're in the right folder and/or if platform-tools was properly added in PATH. You may need to specify ./adb.exe devices to tell the OS where to look for ADB, or make ADB an executable: chmod +x adb.
    • if ADB executes but nothing appears under "List of devices attached" (as shown below), check if your phone is properly connected to the computer. On Windows, you may need to open Driver Manager (Win + R, devmgmt.msc) and look for any USB peripherals with missing drivers, and install accordingly.
    • if you’re connecting to a Linux-based computer, you may need to go to Settings, Storage and turn on USB Storage on the phone for udev to properly register your phone as an USB peripheral with external storage. An icon in the status bar will appear indicating storage access via USB. (If you don't wish to do this, see Setting up USB access on Linux below.)
    • on macOS and Linux, udev and lsusb are your friends to troubleshoot any USB connection issues here
    • if a device appears as unauthorized, it means that you need to approve the ADB connection to your phone with a pop-up on your phone's screen. Except... KaiOS does not have such thing! You're pretty much stuck here until someone figures out how to get your phone accessible by ADB; this should already be reflected on the Devices page.
$ adb devices
* daemon not running; starting now at tcp:5037  
* daemon started successfully  
List of devices attached


// there should be a device with random ID above

Connect to ADB over Wi-Fi

If you happen to be on the go without any USB cables, it is possible to connect to your phone over Wi-Fi for debugging as well, although the connection will be less reliable and apps may take a longer time to be installed. (WIP)

Set up & connect to WebIDE

  1. We'll use Waterfox Classic for WebIDE, as this is the most recently maintained browser to-date, but setting up WebIDE on other browsers should be similar. 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.

  1. Open the browser and press the hamburger menu button at the right end of the toolbar, select Developer (tenth option from top to bottom, left to right), WebIDE (or press its shortcut: Shift + F8) to open the WebIDE window.

  1. Your phone’s name should appear in the right pane as an option under USB Devices. Click it to connect.
    • If you don't see any devices, either because you're setting up WebIDE for the first time, or your browser doesn't have a working adbd daemon, type this into Command Prompt or Terminal to forward ADB access to TCP socket 6000: adb forward tcp:6000 localfilesystem:/data/local/debugger-socket
    • Then, click Remote Runtime in the right pane, leave it as default at localhost:6000 and press OK.
    • If you see a yellow banner stating "Operation failed: Connecting to Remote Runtime"... it simply means that your phone rejected DevTools access. Did you miss any steps when getting your phone debug-enabled? Otherwise, you're stuck here until someone figures out how to get it accessible by DevTools.

If you’re using older browsers to access WebIDE such as Firefox v59 or Pale Moon <28.6.1, at this point you may 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.

Ready to sideload apps

  1. To sideload an application, download a packaged file (you can find great apps on BananaHackers Store and GitHub!) and extract it into a dedicated folder.
    • Again, on macOS or Linux, you can double-click the downloaded archive and let the file manager do the rest. On Windows, right-click the archive, select 7-Zip's or WinRAR's context menu, and choose Extract to [filename]...
    • Make sure that there's a manifest.webapp at the root of the extracted folder. If you see an application.zip (which indicates that the app was packaged for OmniSD), extract it.

  1. In WebIDE, select Open Packaged App in its left sidebar and navigate to the root of the app folder you just extracted (again, make sure that there's a manifest.webapp at its root!)

  1. Once you get the app loaded with no errors, press the triangle Install and Run in the top bar to sideload.

Feel free to ignore this warning: "app submission to the Marketplace requires a [size in px] icon". if you were to upload your apps to the Firefox Marketplace, a 128px icon is required to display your app in the splash screen. While KaiStore also requires app icons to be in certain sizes, a 128px icon is no longer necessary, only 56px and 112px.^6 You can get rid of this error by including a 128px icon in the app's manifest.

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.

This documentation page is written on the courtesy of the BananaHackers team, 2018–present.

Clone this wiki locally