Skip to content
ecklfPublic

About

A native launcher for rooted LG webOS TVs

Topics

Resources

Stars

417 stars

Watchers

3 watching

Forks

Latest commit

 

History

482 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Luma

A native launcher for rooted LG webOS TVs, inspired by Apple TV.

luma-preview.mp4
Screenshots
Luma native Home screen, desktop preview Luma native app library, desktop preview
Luma native General settings, desktop preview Luma native input pills, desktop preview

Features

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

Compatibility

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 ✅

Installation

Homebrew Channel

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.

SSH

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_IP

In the TV's root shell:

luna-send -i luna://com.webos.appInstallService/dev/install \
  '{"id":"com.ecklf.luma","ipkUrl":"/tmp/luma.ipk","subscribe":true}'

Replacing LG Home

Takeover Method

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" disable

To enable the takeover run:

APP=/media/developer/apps/usr/palm/applications/com.ecklf.luma
sh "$APP/home.sh" enable

To see the status or disable the home override use:

sh /var/lib/luma-home/home.sh status
sh /var/lib/luma-home/home.sh disable

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

Autostart Method

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 enable

Use 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 disable

Optional power-on and Back/Exit policy (webOS 5/6)

Requires 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 off

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

LG Input Hook Method

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.

Development

Setup & Building

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 package

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

Preview

nix develop
pnpm install --frozen-lockfile
pnpm assets
pnpm dev

The desktop preview uses sample inventory and never calls TV services. To manually exercise a longer app grid:

pnpm dev --test-extra-apps 120

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

License

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.

About

A native launcher for rooted LG webOS TVs

Topics

Resources

Stars

417 stars

Watchers

3 watching

Forks

Releases

Contributors

Languages