A native launcher for rooted LG webOS TVs, inspired by Apple TV.
luma-preview.mp4
- Customizable app drawer with optional names beneath selected non-favorite apps (off by default), input icons and recent app switching.
- Left/right navigation wraps between the first and last app in favorites and the app drawer.
- Movable greeting, weather, stock and crypto widgets.
- Midnight background and custom uploads, with optional rotation.
- Webhook shortcuts and 16 interface languages.
Inputs also lists USB storage reported by webOS. Selecting a storage device opens an installed LG media browser, where you choose the device; it does not switch an HDMI source. USB discovery and media opening still need hardware verification across TV firmware versions.
Personalize your greeting in Settings → Widgets → Greeting → Configure → Name. Use Clear name to return to an unnamed greeting; names are saved only on your TV.
Note
Luma should start on any TV running webOS 4 or newer. The following configurations have been confirmed to work by the community. Home takeover support varies, as noted below:
webOS 4
| TV | Model identifier | Takeover Support |
|---|---|---|
| LG C8 | OLED??C8* |
❌ |
| LG C9 | OLED65C97LA |
Unknown |
| LG UM7450 | UM74507LA |
❌ |
webOS 5
| TV | Model identifier | Takeover Support |
|---|---|---|
| LG UN7100 | 49UN71006LB |
✅ |
webOS 6
| TV | Model identifier | Takeover Support |
|---|---|---|
| LG B1 | OLED65B19LA |
✅ |
| LG C1 | OLED48C1KNB |
✅ |
| LG G1 | OLED65G1RLA |
✅ |
| LG UP8000 | 86UP80009LA |
Unknown |
webOS 24
| TV | Model identifier | Takeover Support |
|---|---|---|
| LG G4 | OLED65G46LA |
✅ |
| LG B2 | OLED65B29LA |
✅ |
| LG QNED81 | 50QNED816RE |
✅ |
webOS 25
| TV | Model identifier | Takeover Support |
|---|---|---|
| LG B5 | OLED77B5PUA |
✅ |
| LG C2 | OLED42C2PSA |
✅ |
| LG C2 | OLED65C2* |
Unknown |
| LG C2 | OLED77C2* |
Unknown |
| LG C4 | OLED42C4* |
✅ |
| LG G3 | OLED??G3* |
Unknown |
| LG NANO77 | 55NANO776RA |
✅ |
| LG QNED86 | 55QNED86T6A |
Unknown |
| LG UT8050 | 50UT8050* |
✅ |
webOS 26
| TV | Model identifier | Takeover Support |
|---|---|---|
| LG C2 | OLED65C2PSA |
✅ |
| LG C3 | OLED65C31LA |
✅ |
| LG C3 | OLED65C36LC |
✅ |
| LG C4 | OLED77C44LA |
✅ |
| LG C5 | OLED55C57LA |
✅ |
| LG C5 | OLED55C5PSA |
Unknown |
| LG C6 | OLED65C6* |
Unknown |
| LG C6 | OLED77C6* |
✅ |
| LG G5 | OLED83G5WUA.BUSYDJR |
✅ |
| LG G5 | OLED77G5WUA.DUSQLJR |
✅ |
Add this custom repository URL to Homebrew Channel:
https://github.com/ecklf/lg-luma/releases/latest/download/repo.json
Upvote the official Homebrew Channel repository PR to help make Luma available by default.
On your computer, replace TV_IP:
scp -O dist/com.ecklf.luma_3.11.0_arm.ipk root@TV_IP:/tmp/luma.ipk
ssh root@TV_IPIn the TV's root shell:
luna-send -i luna://com.webos.appInstallService/dev/install \
'{"id":"com.ecklf.luma","ipkUrl":"/tmp/luma.ipk","subscribe":true}'Note
Takeover is supported on webOS 5, 6, 24, 25 and 26.
On 5, 6 and 24 it replaces the Home executable; on 25 and 26 it mounts Luma's Home app.
The takeover does not delete LG Home: it remains underneath a temporary mount, which is cleared by
a reboot. If Luma is uninstalled first, LG Home returns on reboot, but the separate takeover boot
hook remains and logs an error because it can no longer find Luma. No TV reset is needed. For
clean removal, disable takeover before uninstalling.
Install Luma and verify that it opens normally. Disable any Home-button mapping in LG Input Hook (remove its Home-key action) and any other Home replacement, then run in the TV's root SSH shell:
If you enabled Lumas autostart method earlier, disable it first:
APP=/media/developer/apps/usr/palm/applications/com.ecklf.luma
sh "$APP/autostart.sh" disableTo enable the takeover run:
APP=/media/developer/apps/usr/palm/applications/com.ecklf.luma
sh "$APP/home.sh" enableTo see the status or disable the home override use:
sh /var/lib/luma-home/home.sh status
sh /var/lib/luma-home/home.sh disablerestore is an alias for disable.
Boot log: /var/lib/luma-home/boot.log. See the
development guide for implementation details.
Method for webOS 5 / 6 / 24
On webOS 5, 6 and 24, SAM cannot reread a mounted Home manifest, so home.sh enable instead
bind-mounts Luma's executable over LG's /usr/bin/com.webos.app.home. LG's Home manifest stays
in place and Luma registers with SAM itself, so the Home key brings the running Luma back instead
of restarting it. The commands and the cold-boot hook are the same.
webOS 24 belongs here rather than with 25/26 because its SAM has no releaseBlockSystemApp, so a
mounted Home manifest is never reread and the manifest method fails on that missing method.
On webOS 5/6, a cold boot opens Luma at about 20 s instead of after the Homebrew hook (~50 s or
later). The Homebrew hooks start late, but LG's service hub reads /var/luna-service2 at
core-boot-done. home.sh enable therefore also registers a small root helper there
(com.webos.service.lumahome, a copy of the package's luma-early in /var/lib/luma-home) and adds
a compositor key filter (home-filter.js) to LG's chain. While the TV boots, the filter asks the
helper to mount Luma and then opens Home. If this fails, the cold-boot hook mounts Luma as before.
Keys pass through the filter unchanged, and home.sh disable removes both. The early-boot timing
has not been verified on webOS 24.
On webOS 5/6, Home takeover preserves the TV's input policy. An experimental power-on and Back/Exit policy can open Luma instead of the last input; tested on webOS 5.6.2 only, not verified on webOS 24.
Method for webOS 25 / 26
Mounts Luma over the system Home app and reapplies the mount at cold boot. The launch splash uses a centered Luma logo on a dark-gray background, independent of your selected wallpaper. Normal app launches and staged Home launches use the same static image, with no runtime splash updates. LG Home's original files remain underneath, using the same approach as Glasshouse Home.
Open Luma 25 seconds after a full cold boot. Run in the TV's root SSH shell:
sh /media/developer/apps/usr/palm/applications/com.ecklf.luma/autostart.sh enableUse this when takeover is disabled. It launches Luma as a regular app and does not remap the Home button.
Disable before enabling takeover or uninstalling Luma:
sh /media/developer/apps/usr/palm/applications/com.ecklf.luma/autostart.sh disableRequires executable Home takeover; this command is not supported on webOS 25/26's manifest method. On webOS 25, LG provides Settings → General → System → Additional Settings → Home Settings → Power On Screen → Home for startup selection (LG guide). That setting does not configure Back/Exit behavior or guarantee Luma launches after takeover.
Home takeover alone preserves the TV's input policy. After enabling Home takeover, owners who want Luma instead of the last TV input at power-on and after leaving apps can explicitly run:
sh /var/lib/luma-home/home.sh startup-home on
# Restore the saved power-on and Back/Exit input while keeping Home takeover:
sh /var/lib/luma-home/home.sh startup-home offSelect the desired fallback TV input before opting in. This experimental policy pins EIM's
last-input file read-only; tested on webOS 5.6.2 only. Disabling takeover also restores the saved
input. Existing draft installations without a saved prior setting use the input recorded in
EIM's appId as their migration fallback.
You can use LG Input Hook, configure an Execute action with this one-line command:
/usr/bin/luna-send -n 1 -w 5000 luna://com.webos.service.applicationmanager/launch '{"id":"com.ecklf.luma"}'Test on a spare button first. Disable the mapping in Input Hook to restore normal Home behavior.
From the repository root, with Nix flakes enabled:
nix develop
pnpm install --frozen-lockfile
pnpm sdk
export WEBOS_NDK="$PWD/.build/toolchain/arm-webos-linux-gnueabi_sdk-buildroot"
pnpm run packageThe first native runtime preparation also downloads a
checksum-pinned SDL-webOS library; both downloads are cached under .build/.
Output:
dist/com.ecklf.luma_3.11.0_arm.ipk
dist/sha256sums
dist/repo.json
dist/app-icon-large.png
Open webOS Dev Manager, connect to the TV's
IP on port 22 as root, and install the IPK. Open Luma from the TV menu. Homebrew
Channel must be elevated; on webOS 26 use 0.8.0-rc1 or newer for its lunabus.query mapping.
The native package uses com.ecklf.luma. Preferences are stored in local JSON files
separately for each installation.
Wait for installation success; Ctrl+C closes an ongoing subscription. Fully close and reopen Luma after updating. The development guide has a jailed launch command that exposes errors hidden by the normal menu launch.
nix develop
pnpm install --frozen-lockfile
pnpm assets
pnpm devThe desktop preview uses sample inventory and never calls TV services. To manually exercise a longer app grid:
pnpm dev --test-extra-apps 120Preview preferences are separate from normal preferences. See development.md for controls, vector rendering, diagnostics, tests and the source layout.
SDL-recognized game controllers can navigate with the D-pad or left stick, select with Cross / A, go back with Circle / B, and open options with Options / Start. Controller availability, including PS5 DualSense USB/Bluetooth connections, depends on TV firmware and the SDL backend and requires verification on your TV.
Luma's code is licensed under MIT. Bundled Breezy Weather icons
are separately licensed under LGPL-3.0.
Luma is not affiliated with LG, Apple, or any other brands shown in its UI.