KFMon + NickelMenu: advanced launcher configuration for Kobo

· 3 min readJailbreakKobo#kobo#kfmon#nickelmenu

KFMon (Kobo File Monitor) and NickelMenu are the two most popular launchers on jailbroken Kobos, but most people stop after installing KOReader. There’s a lot more you can do once you understand how these two tools compose. Here’s an advanced guide to configuring both for a fully customized Kobo experience.

KFMon: how it actually works

KFMon watches a directory — typically /mnt/onboard/.adds/kfmon/ — for PNG files with embedded configuration metadata. When you tap a “book” in Nickel that KFMon generated, it reads the PNG’s config block, finds the associated shell script or binary, and executes it. Every KFMon entry needs two things: a launcher PNG (the visual “book” in your library) and a watch configuration file.

The default install places configs in /mnt/onboard/.adds/kfmon/config/. Each .ini file defines one launcher entry. Here’s a minimal example that launches Plato, the alternative reader:

[plato]
filename = /mnt/onboard/.adds/plato/plato.png
action = /mnt/onboard/.adds/plato/plato.sh
do_db_update = 0

The do_db_update = 0 line tells KFMon not to re-scan Nickel’s database after the app exits — this avoids Kobo’s slow “importing content” screen when you switch back.

Custom launch entries: adding your own scripts

You can add arbitrary shell scripts as KFMon launchers. This opens up automation that Nickel doesn’t natively support. Examples:

Toggle Wi-Fi script: Create a script at /mnt/onboard/.adds/scripts/toggle-wifi.sh:

#!/bin/sh
STATE=$(lipc-get-prop com.lab126.wifid cmState)
if [ "$STATE" = "CONNECTED" ]; then
    lipc-set-prop com.lab126.wifid cmState "OFF"
else
    lipc-set-prop com.lab126.wifid cmState "ON"
fi

Pair it with a KFMon .ini and a square PNG icon, and you have a one-tap Wi-Fi toggle in your Nickel library. Create similar launchers for rebooting into KOReader directly, dumping battery stats to a log file, or running rsync backups over Wi-Fi.

Dark mode toggle: Kobo’s Nickel doesn’t have a quick dark mode switch, but you can toggle it via the developer settings database:

#!/bin/sh
CURRENT=$(sqlite3 /mnt/onboard/.kobo/KoboReader.sqlite \
  "SELECT InvertScreen FROM GeneralSettings WHERE DeviceID='default'")
if [ "$CURRENT" = "true" ]; then
    sqlite3 /mnt/onboard/.kobo/KoboReader.sqlite \
      "UPDATE GeneralSettings SET InvertScreen='false' WHERE DeviceID='default'"
else
    sqlite3 /mnt/onboard/.kobo/KoboReader.sqlite \
      "UPDATE GeneralSettings SET InvertScreen='true' WHERE DeviceID='default'"
fi

Auto-start apps on boot

KFMon doesn’t auto-start apps, but NickelMenu can. Add an entry to your NickelMenu config that triggers a script on Nickel launch:

menu_item :main :Start KOReader :cmd_spawn :/mnt/onboard/.adds/koreader/koreader.sh

To auto-launch KOReader immediately after boot (skipping Nickel entirely), modify the system startup by creating a custom rcS hook in /etc/init.d/. This is more invasive — it prevents Nickel from loading — but gives you a pure KOReader or Plato device that boots directly into your alternative reader in under 10 seconds. Use the Kobo Start Menu package for a cleaner implementation of this without editing init scripts by hand.

Troubleshooting common KFMon failures

“KFMon not showing up in Nickel”: This usually means the Kobo firmware updated and overwrote the KFMon hook in /usr/local/Kobo/nickel. Reinstall KFMon using the one-click installer package. Future-proof this by installing NickelMenu alongside KFMon — NickelMenu doesn’t rely on Nickel hooks and survives most updates.

“Launcher PNG appears but nothing happens when tapped”: Check that the script path in the .ini file is absolutely correct and the script is marked executable (chmod +x). KFMon logs to /mnt/onboard/.adds/kfmon/log/kfmon.log — read this file for the exact error.

“KOReader crashes on launch”: If KOReader was working and suddenly isn’t, check available disk space. KOReader’s cache can grow to hundreds of megabytes. Clear /mnt/onboard/.adds/koreader/cache/ and try again.

“Device freezes after switching back to Nickel”: This is usually a memory leak in the framebuffer driver. Set KFMon’s do_db_update = 0 and avoid rapidly switching between readers. If it persists, add a sleep 2 && pkill -9 nickel to your script’s exit hook to force a clean Nickel restart.

Combining NickelMenu with KFMon

NickelMenu provides quick-access menu entries, while KFMon provides library-tappable launchers. Use both: NickelMenu for utilities you access from the reading screen (dictionary switcher, dark mode, screenshot), and KFMon for full alternative reader launches. Together they give you a Kobo that feels like a custom Linux handheld rather than a locked-down e-reader — and the risk level stays low since neither modifies the system partition.

Advertisement
Ad