luma-home/README.md

luma-home

Replaces the LG webOS Home screen with Luma on webOS 5/6 TVs rooted via Homebrew Channel.

How it works

LG Home (com.webos.app.home) is a native QML app. This project bind-mounts a transparent web page over its directory so SAM sees a web-type Home. The web page immediately calls WebOSServiceBridge to launch Luma. A background watcher provides a fallback redirect via luna-send subscription.

Components

File	On TV at	Purpose
overlay/appinfo.json	/media/developer/luma-home/overlay/	Home manifest — web type, transparent, no splash
overlay/index.html	same	Minimal page that launches Luma via WebOSServiceBridge
boot-hook.sh	/media/developer/luma-home/	Homebrew Channel boot hook — mounts overlay, restarts SAM, launches Luma
watcher.sh	same	Background watcher — subscribes to foreground events, redirects Home→Luma

Boot flow

1. Homebrew Channel runs boot-hook.sh at cold boot
2. Bind-mount replaces /usr/palm/applications/com.webos.app.home (RAM only — reboot without the hook restores stock)
3. SAM restarts and reads the web manifest
4. Luma launches as the initial app
5. Watcher starts in the background

Home button flow

1. User presses Home → system opens com.webos.app.home (our transparent web page)
2. index.html JS fires WebOSServiceBridge → launches Luma
3. Watcher catches the foreground change as backup → also launches Luma

Requirements

• LG webOS TV rooted with Homebrew Channel (tested on webOS 6.5.3)
• Luma v2.1.0+ installed as com.ecklf.luma
• Telnet or SSH access to the TV

Install

# Copy files to TV
scp -r overlay/ boot-hook.sh watcher.sh root@<TV_IP>:/media/developer/luma-home/

# SSH into TV and install the boot hook
chmod +x /media/developer/luma-home/boot-hook.sh /media/developer/luma-home/watcher.sh
ln -sf /media/developer/luma-home/boot-hook.sh /var/lib/webosbrew/init.d/10-luma-home

# Run it now (or reboot)
sh /media/developer/luma-home/boot-hook.sh

Uninstall

# Remove boot hook
rm /var/lib/webosbrew/init.d/10-luma-home

# Kill watcher
kill $(cat /tmp/luma-watcher.pid 2>/dev/null)

# Unmount overlay (or just reboot)
umount /usr/palm/applications/com.webos.app.home

Known limitations

• Brief visual transition when pressing Home (web page loads before Luma appears)
• blockSystemApp API (used by Luma's built-in Home integration for webOS 25/26) does not exist on webOS 5/6, so we use systemctl restart sam instead
• Native Home replacement (Luma binary as Home directly) does not work on webOS 6 — SAM handles native system apps differently

Future

Fork Luma and patch home.cjs to support webOS 5/6 natively — replace the version check and blockSystemApp calls with the systemctl restart sam approach proven here.

Tested on

• LG 65NANO813PA, webOS 6.5.3-47 (kisscurl-koli)
• Luma v2.1.0
• Homebrew Channel v0.7.3