Skip to main content

Building for LG webOS

Hosanna Tools automates webOS bundling, .ipk packaging, install, launch, termination, and inspection. Its guided setup command can register an ares alias and hand off to the official interactive key prompt; LG account sign-in, Developer Mode, Key Server state, and passphrase entry remain vendor-owned.

Hosanna build output moving through first-class webOS staging, IPK packaging, device verification, and the LG release boundaryHosanna build output moving through first-class webOS staging, IPK packaging, device verification, and the LG release boundary

Prerequisites​

  • Node and project dependencies installed from the lockfile.
  • A Hosanna SDK installation managed through hosanna.json and npx hst sdk:install.
  • LG webOS TV CLI commands such as ares-setup-device, ares-package, ares-install, ares-launch, and ares-inspect.
  • An LG Developer account and the Developer Mode app are needed for physical runs, but not for package-only ares-package builds.
  • For device runs, a TV meeting the supported webOS 5.0+ baseline. Neither appinfo.json nor HST enforces that baseline.

Use LG's current Developer Mode guide and webOS TV CLI guide.

Pair the TV​

  1. Sign in to the Developer Mode app and enable Developer Mode and Key Server.
  2. Preview the credential-safe setup flow, then let HST register the ares alias and invoke the official key prompt.
  3. Enter the displayed passphrase directly into ares-novacom; HST does not receive it.
  4. Confirm HST can discover the remembered alias.
npx hst device:setup webos --host 192.168.1.30 \
  --alias living-room --get-key --dry-run
npx hst device:setup webos --host 192.168.1.30 \
  --alias living-room --get-key
ares-setup-device --list
npx hst device:list --type webos --json

Keys and passphrases remain in LG's user-level device store. Do not copy them into .hosanna-tools/run.json, BuildConfig, or a package. HST may merge a project/user friendly alias into inventory, but an offline configured entry is not proof that ares authentication succeeded.

device:setup webos registers the alias with the supplied host, SSH port, and username. --default can select it as the ares default. --get-key invokes ares-novacom --getkey interactively and verifies system access afterward. Repeat the vendor Developer Mode/key flow when the session expires or the remembered key is no longer accepted.

Preview, build, and run​

npx hst run webos dev emulator
npx hst build webos prod device --non-interactive
npx hst run webos dev device --device living-room
npx hst device:inspect webos --device living-room
npx hst device:terminate webos --device living-room

The build uses vite.webos.config.ts, Chrome 68-compatible classic output, relative package URLs, and app-owned appinfo.json. The official webOSTV.js 1.2.13 artifact and Apache 2.0 license are bundled by the host application.

The build command never discovers or contacts a TV. The run command installs and launches; inspection and termination happen only when their explicit commands are invoked. Inspection calls ares-inspect --open for the selected alias and application ID. Inspector availability depends on Developer Mode and the selected TV model. The TV driver does not promise a vendor-native log stream, so use application/MCP logs as the common path.

Development staging selects index.dev.html and replaces its tokens with one exact LAN debugger WebSocket plus exact configured service origins. Production starts package-local and substitutes only exact configured service origins; it contains no debugger origin, wildcard network scheme, or unsafe-eval. Inline styles remain allowed because the Web DOM renderer applies presentation through element style properties.

Pass reviewed origins with repeated --connect-origin arguments, the platform connectOrigins run-config field, or HS_TV_CONNECT_ORIGINS. A physical test can add HS_TEST_MODE=true and a clear fixture root such as HS_TEST_STREAM_BASE_URL=http://<development-machine>:5180. HST derives the exact origin for package policy, carries the base URL into the test launch, and rejects credentials, wildcards, mismatched explicit origins, and unresolved package tokens.

Application metadata​

The application owns its stable ID/version/vendor/title, icons, main, handlesRelaunch, disableBackHistoryAPI, and audio-guidance declaration. The same stable appinfo.json identity is used for development and production; only the staged HTML/CSP differs. All package paths must be relative; a leading / can appear to work in Developer Mode and fail in a release package.

In the physical test harness, no-argument hs.app.relaunch() terminates and launches the package through the webOS driver, then waits for MCP reconnection. Changing test rigs uses MCP ReloadPage with a query-only URL bounded to the current packaged file. This is test navigation, not an ares-launch deep-link claim.

Device release checklist​

Run the sample Web TV Platform Contract rig with a LAN-reachable testStreamBaseUrl. For each application release, verify native HLS/MP4, configured PlayReady content, track selection, WebVTT sync, storage after cold restart, Magic Remote behavior, audio guidance toggled after launch, lifecycle relaunch/resume, and MCP reconnection on representative target models. Complete LG's current store checklist before submission.

Talk to us