ZUI webOS Platform is a rootless management layer and developer-tooling monorepo for ZUI applications on LG webOS TVs. It uses LG Developer Mode and the public webOS CLI; it does not root televisions, patch firmware, modify protected system files, or install privileged daemons.
This community project is not affiliated with or endorsed by LG Electronics or YouTube.
Local modules include ZUI DevMode Keeper, the read-only Device Manager Core, the Verified Package Inspector, the approval-gated installer service, signed artifact distribution, operational staging release tooling, normalized catalog/update intelligence, the local ZUI Web Manager, and ZUI Store STAGING. The Web Manager can inspect, download and verify trusted catalog artifacts, and generate read-only plans, but cannot execute an installation, sign/publish a release, or extend Developer Mode. ZUI Store adds explicitly paired, approval-gated signed staging installation through a separate PC service. Production installs, Store self-update and same-version reinstall remain blocked. The first staging INSTALL has real-TV acceptance; genuine newer-version UPDATE acceptance remains open.
The platform is also the management layer for future device, catalog, installer, release-registry, web-manager, and TV-store components. Product source remains in independent repositories:
| Product | Application ID | Repository |
|---|---|---|
| ZUI IPTV Player | com.zui.player |
ZUI-WebOS/ZUI-IPTV-Player |
| ZUI YouTube for webOS | youtube.leanback.v4 |
ZUI-WebOS/ZUI-YouTube-WebOS |
| ZUI YouTube staging | com.zui.webos.youtube.staging |
same external product repository |
No product source is copied into this monorepo.
ZUI webOS Platform
|-- Devices and shared webOS tooling
|-- DevMode Keeper
|-- Catalog and release registry
|-- Installer / local Manager
|-- Web management portal
|-- TV Store / launcher
`-- External product repositories
|-- ZUI IPTV Player
`-- ZUI YouTube for webOS
The device control plane stays local. Cloud-facing services may publish signed metadata and artifacts later, but they do not receive TV private keys or obtain a hidden command path into the local network.
- Windows 10/11 development host
- Node.js 22 or newer
- pnpm 11.5.0 (declared by the repository)
- LG webOS CLI with a device registered through
ares-setup-device - LG Developer Mode on the target TV
Do not place passwords, tokens, private keys, or device connection details in this repository. DevMode Keeper reuses the webOS CLI device registry and accepts a device alias such as tv; IP addresses are never hard-coded.
Runtime cache and release data default to the process-neutral
%USERPROFILE%\.zui-webos\ root. Set ZUI_WEBOS_DATA_DIR to an absolute path
to configure another shared location. %LOCALAPPDATA% is not used for these
bytes because Windows may virtualize it for packaged applications; encrypted
signing keys and user configuration keep their separately documented paths.
pnpm install --frozen-lockfile
pnpm verifyIndividual gates are available as pnpm lint, pnpm type-check, pnpm test, pnpm build, and pnpm format:check.
Start the real local Web Manager or its deterministic no-TV fixture mode:
pnpm web
pnpm web:mockBoth commands bind only to http://127.0.0.1:4273 by default. Set ZUI_WEB_MANAGER_PORT to a whole number from 1 through 65535 to use another local port; the host remains fixed to 127.0.0.1. If the requested port is occupied, startup stops with an actionable error instead of selecting another port. The browser talks to a narrow local API that reuses the platform services; it has no generic command or filesystem endpoint. Uploaded IPKs are inspected but never executed from the UI.
The catalog correlates current installed inventory with exact registered App IDs, deployment classes, and stable/staging channels. It shows version, trust, remote, and verified-cache states independently. Download & Verify resolves only trusted logical catalog IDs and reuses the signed distribution pipeline; Generate Installation Plan reuses the existing planner and still stops before execution. The platform is local-first and includes no telemetry, analytics, or third-party tracking.
Build or preview the remote-first ZUI Store staging application:
pnpm tv-store:dev
pnpm tv-store:packageThe staging IPK uses com.zui.webos.store.staging. DEMO remains deterministic and non-mutating for CI and offline work. LIVE uses an operator-selected, assigned RFC1918 private PC LAN IPv4, port 4274, and device alias tv; it never exposes the loopback Web Manager and never falls back to demo data. Eligible signed staging products can use a separately armed installation service on port 4275, with short-lived pairing and Cancel-first user review. Do not arm that service on an untrusted LAN.
$env:ZUI_TV_STORE_API_HOST = '<PC LAN IPv4>'
$env:ZUI_TV_STORE_DEVICE_ALIAS = 'tv'
pnpm tv-store:api:live
# In a separate terminal with the same host setting:
pnpm tv-store:package:liveThe separate /api/tv-store/v1 contract remains read-only; installation uses a different narrow contract and the existing InstallerService. See installation flow and operator activation, real-TV staging install acceptance, TV Store architecture, the MVP report, and the live catalog report.
Documentation localization convention: README.md is the canonical English document. A future README_TR.md will be the maintained Turkish user-facing counterpart after its translation-quality gate is defined; no placeholder translation is kept.
Build once, then invoke the CLI through the workspace script:
pnpm build
pnpm exec zui-webos devices list
pnpm exec zui-webos devices inspect --device tv
pnpm exec zui-webos apps list --device tv
pnpm exec zui-webos apps inspect --device tv --app com.zui.player
pnpm exec zui-webos package verify C:\path\to\application.ipk
pnpm exec zui-webos install plan C:\path\to\application.ipk --device tv
pnpm exec zui-webos devmode status --device tv
pnpm exec zui-webos devmode extend --device tv --dry-run
pnpm exec zui-webos devmode extend --device tv
pnpm exec zui-webos devmode ensure --device tv
pnpm exec zui-webos doctor --device tvAdd --json for machine-readable results. Configuration precedence is CLI arguments, environment variables, local user config, then defaults. The local config defaults to %LOCALAPPDATA%\ZUI WebOS Platform\config.json and must not contain secrets.
The public webOS CLI does not expose the resulting Developer Mode expiry timestamp. Keeper therefore reports command acceptance and post-command connectivity separately from expiryVerified; it never invents an expiry or claims that unknown state is measured.
Package inspection never executes an IPK. Installation Plan V2 is canonical, expiring, and approval-bound. Only a repository-pinned staging artifact with current signed distribution trust can become executable, and execution requires its exact digest:
pnpm exec zui-webos install plan C:\path\to\staging.ipk --device tv --save C:\path\to\plan.json
pnpm exec zui-webos install execute C:\path\to\plan.json --approve <exact-plan-digest>Production app IDs are hard-blocked with no override. No scheduler or background service is installed by default.
- Official Developer Mode workflow only.
- Child processes use an executable plus an argument array with
shell: false. - Device aliases are validated before use.
- Commands have timeouts and deterministic structured errors.
- Logs redact connection addresses and credential-like values.
- Package installation, uninstallation, storage reset, rooting, privilege escalation, and firmware mutation are outside DevMode Keeper.
See Threat Model, Catalog Service, Update Evaluation, Package Security, Release Metadata, Artifact Distribution, Approval-Gated Installer, Device Manager, Package Inspector, and Installation Planner.
For staging operators, see Staging Release Runbook, Signing Key Backup, and Release Publisher. Operational signing is local and staging-only; CI receives no long-lived private key.
- DevMode Keeper CLI and rootless device core.
- Local Device Manager and verified installer.
- Signed catalog, release/package registry, and update intelligence.
- Local Web Manager (read-only inspection, verified fetch, and planning).
- TV Store live catalog and real-device state.
- Staging-only TV Store installation flow and Cancel-first approval UX (first INSTALL accepted on real TV).
- Genuine staging UPDATE acceptance, additional app coverage, UX and beta delivery.
Changes should preserve rootless boundaries, add tests for process behavior, and keep external product repositories independent. Production signing/deployment remains unauthorized. Further product work should expand real staging UPDATE, application coverage and user-facing beta UX rather than reopen completed foundation milestones.
Original platform code is licensed under the MIT License. External products retain their own licenses; this repository does not relicense or incorporate their source.