KFMon + NickelMenu: advanced launcher configuration for Kobo

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 a 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 a 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.

Advanced use cases worth setting up

Once you have the basics working, these configurations turn a Kobo into a genuinely powerful reading workstation.

One-tap wireless book sync with Calibre

If you run Calibre with the Content Server on your home network, you can add a NickelMenu entry that opens the Calibre web interface directly in Kobo’s experimental browser at a known IP. Even better, combine it with a script that triggers Calibre’s calibredb command over the network:

menu_item :main :Sync Books via Calibre :cmd_spawn :/mnt/onboard/.adds/scripts/calibre-sync.sh

The script itself can use wget to pull new books from your Calibre server’s OPDS feed and deposit them into the Kobo’s root directory, then trigger a Nickel database refresh. This turns what is normally a plug-in-via-USB workflow into a one-tap wireless sync from the comfort of your reading chair — no cables required.

Screenshot utility

Kobo has a hidden screenshot feature, but it requires tapping the power button and a specific corner of the screen simultaneously — unreliable at best. A NickelMenu entry makes it deterministic:

menu_item :reader :Take Screenshot :cmd_output :500:/sbin/screenshot

This saves a PNG to the device’s root directory without interrupting reading. Pair it with a KFMon launcher that archives screenshots to a Screenshots/ folder on boot, and you have an automatic organization system.

USB networking for SSH access

For advanced users comfortable on the command line, enabling USB networking via NickelMenu opens a full SSH connection to the Kobo over the USB cable. Add this to your NickelMenu config:

menu_item :main :USB Networking :cmd_spawn :/mnt/onboard/.adds/scripts/usbnet-toggle.sh
menu_item :main :SSH Shell :cmd_spawn :/mnt/onboard/.adds/scripts/dropbear-start.sh

The first enables the g_ether USB gadget driver (giving the Kobo a static IP at 192.168.2.2), and the second starts the Dropbear SSH server. From your computer, ssh [email protected] gives you a full BusyBox shell. From there you can edit Nickel configs live, inspect KFMon logs in real time, or run fdisk and mount commands without ever rebooting the device.

Battery stats logger

Kobo’s Nickel UI tells you almost nothing about battery health. This script dumps voltage, charge current, and capacity to a log file every hour when triggered via KFMon:

#!/bin/sh
LOG=/mnt/onboard/battery-log.csv
if [ ! -f "$LOG" ]; then
  echo "timestamp,voltage_mv,current_ma,capacity_pct" > "$LOG"
fi
echo "$(date +%s),$(cat /sys/class/power_supply/battery/voltage_now),$(cat /sys/class/power_supply/battery/current_now),$(cat /sys/class/power_supply/battery/capacity)" >> "$LOG"

Over a few weeks, the resulting CSV reveals real battery degradation trends that the percentage gauge in Nickel never shows.

Troubleshooting quick reference

Here’s a condensed table of KFMon and NickelMenu issues, likely causes, and immediate actions — ordered by how often I’ve seen each one in the field.

Symptom	Likely Cause	First Action
KFMon entries not appearing in Nickel library after install	Kobo firmware update overwrote the `nickel` hook in `/usr/local/Kobo/`	Reinstall KFMon via the one-click package; install NickelMenu alongside it for future-proofing
Launcher PNG visible but nothing happens on tap	Script path in `.ini` is wrong or script lacks execute permissions	Run `chmod +x /path/to/script.sh`; check `kfmon.log` at `/mnt/onboard/.adds/kfmon/log/`
KOReader crashes on launch after months of working	Cache directory has ballooned to hundreds of MB	Delete `/mnt/onboard/.adds/koreader/cache/` and relaunch
Device freezes when returning to Nickel from KOReader/Plato	Framebuffer memory leak from rapid reader switching	Set `do_db_update = 0` in the KFMon `.ini`; add `sleep 2 && pkill -9 nickel` to the script’s exit hook
NickelMenu entry greyed out or not clickable	Config syntax error (missing colon, wrong action type)	Validate against NickelMenu’s official config reference; every entry needs `menu_item :location :label :action`
Script runs but produces no visible result	Output is going to stdout which Nickel discards	Use `cmd_output` instead of `cmd_spawn` for actions that return text; redirect with `>/tmp/script.log 2>&1` to capture errors
Device hangs on white screen after boot	Bad `rcS` hook or init script modification	Boot without the SD card (if applicable) or force recovery: hold power for 20s, release, hold again until LED blinks

Where to go next

If you haven’t installed Plato or KOReader yet, start with our Plato setup guide for Kobo and the advanced KOReader and Plato installation walkthrough. Once those readers are in place, the configurations in this article make switching between them seamless. For NickelMenu-only mods that don’t require KFMon at all — including the developer mode toggle that unlocks hidden Nickel settings — see our developer mode and NickelMenu deep dive.