Embedded app shell

hex-browser - embedded app shell for native Flutter, web apps, QML, plugins, and RTSP

hex-browser is an embedded app shell for systems that need a stable, purpose-built user surface. Built on the Qt 6/QML stack, it runs multiple tabs and brings together native Flutter, web apps, QML apps, <so> plugins, and RTSP streams, so application teams can stay inside their own ecosystem instead of rebuilding embedded UI plumbing for every device.

Embedded app shellMulti-tab kiosk shellOptimized for low-RAM targetsWeb apps included

One application shell: Use a single shell for operator panels, local applications, service tools, remote content, and fullscreen web workflows.
Low-memory embedded tuning: Background web tabs can be discarded, renderer process count is capped, and Chromium low-end device flags are applied for constrained hardware.
Ecosystem and service: Developers stay in their own application ecosystem while VNC, watchdog integration, startup splash handling, keyboard control, popup policy, and dark mode stay in the shell.

App shell first, browser included

hex-browser is better understood as an embedded app shell and kiosk starter than as a browser wrapper. Web apps are one supported content path beside native Flutter, QML scenes, <so> plugins, and RTSP streams.

One configuration, mixed content

The same deployment can combine native Flutter, remote web applications, local QML apps, plugin-based native code, and live video feeds without switching shells.

Configuration space for field deployment

Fullscreen behavior, rotation, popup policy, persistent storage, navbar behavior, keyboard handling, screenshots, VNC, and debugging switches are configuration-driven. In combination with ttmdaemon, the surrounding configuration space grows much further.

Web apps when needed

Integrated web engine, popups, fullscreen control

Web apps remain one supported path inside the same shell, with dynamic tabs, navigation, overlay dialogs, and kiosk-specific popup behavior.

QML apps and native plugins

Local or remote QML plus <so> plugins

hex-browser routes URLs to web views, QML views, RTSP streams, or native plugins loaded through <so> or file-based .so targets.

Native Flutter Plugin

Flutter interfaces directly in the shell

Flutter-based user interfaces run natively through a plugin behind the shell. They remain real Flutter applications and are not rendered as a classic browser tab.

RTSP/RTSPS streams

Live video for camera and monitoring scenarios

RTSP and RTSPS sources can be displayed as their own content paths directly inside the shell. Camera feeds, monitoring views, and media sources can be integrated into kiosk workflows in a controlled way.

Embedded-Integration und Robustheit im hex-browser mit ttmdaemon, VNC und Watchdog

Embedded integration and resilience

ttmdaemon, VNC, watchdog, reset thresholds

Teams can focus on their own code ecosystem while hex-browser handles kiosk behavior. In combination with ttmdaemon, configuration, launch behavior, recovery, and service access become broader and easier to manage.

Prepared for real operator screens

hex-browser fits environments where operators need a dedicated flow, clear state, and predictable recovery.

Industrielle Maschinensteuerung im hex-browser

Industrial machine control

Machine HMIs, line-side dashboards, alarm states, and touch-first operator screens for industrial automation.

Haus- und Gebäudeautomation im hex-browser

Home and building automation

Wall panels, energy dashboards, room control, and connected-device orchestration with a dedicated kiosk surface.

Browser-im-Browser-Workflows im hex-browser

Browser-in-browser workflows

Nested web tools, service consoles, and controlled popup flows inside a managed kiosk shell.

Feature screencast

A clean stage for navigation, tab switching, plugin loading, remote access, and other browser capabilities in motion.

Built for unattended devices

The current codebase is explicitly shaped for embedded app hosting rather than general desktop browsing. Low-end Chromium flags are enabled early, operational behavior is configurable, and recovery paths are designed for long-running kiosk installations.

Background web tabs can be discarded to deterministically release WebEngine RAM on constrained targets.
Qt WebEngine is started with renderer-process limiting, low-res tiling, and low-end device mode for embedded hardware.
Configuration covers fullscreen, rotation, virtual keyboard, persistent web storage, screenshot paths, popup policy, and remote debugging.
Optional VNC service, systemd watchdog integration, reset-threshold monitoring, and the wider ttmdaemon setup simplify commissioning and field service.

Plugins and extension path

hex-browser exposes a native plugin path so teams can extend the shell for their own devices, protocols, media paths, and application models.

Reference plugin on GitHub

The public example repository shows the HexBrowserPluginInterface entry path for native extensions and QML-backed plugin UIs.

Open example repository

Native Flutter plugin

Flutter is integrated as a native plugin behind the shell. To the application team it stays a Flutter application, not a browser app.

Plugins for your own stack

Plugins loaded through <so> let you integrate custom protocols, device control, media pipelines, or project-specific applications into the same shell.

Supported content paths

The routing layer distinguishes the main content types directly from the configured URL.

Web appshttp:// and https:// content rendered in the integrated Chromium-based web view.

QML viewsLocal file-based QML or remote <qml> URLs routed into a dedicated QML view.

Native pluginsNative plugins loaded through <so>... URLs or file-based .so paths via the hex-browser plugin interface.

RTSP streamsrtsp:// and rtsps:// sources displayed directly in kiosk tabs for live camera and monitoring use cases.

Source-mapped JSON configuration reference

This table is based on the keys that are actually wired in the current hex-browser source, not just on the sample config file. It covers startup keys, tab parsing, runtime UI, WebEngine behavior, persistence, VNC, and recovery switches.

Source basis: gui/main.qml, gui/PanelView.qml, gui/Custom*View.qml, misc.cpp, StartupLogoResolver.cpp.

JSON key	Accepted values	Applied in	Feature / behavior
`Tabs`	Array or object map	PanelView tab parser	Primary tab model. If it is missing or resolves to no usable entries, the runtime falls back to legacy tab keys and finally to a built-in default web tab.
`tabs`Alias	Array or object map	PanelView tab parser	Lowercase alias for `Tabs`.
`URL_Tab_*`Legacy	String URL per tab id suffix	Legacy top-level tab parser	Legacy tab definition. The suffix becomes the tab id, entries are sorted, and matching `Info_Tab_*` values are used as labels.
`Info_Tab_*`Legacy	Optional string label	Legacy top-level tab parser	Optional label/title partner for a `URL_Tab_*` entry.
`Tabs[].id \| name \| key`	String	Per-tab metadata	Stable tab identifier. If duplicates appear, PanelView appends suffixes. The first parsed tab becomes the preferred initial tab.
`Tabs[].label \| title`	String	Per-tab metadata	Visible label used in the navbar and tab lister.
`Tabs[].url \| URL \| Url \| startURL \| startUrl \| start_url \| src \| source \| path \| href`	String URL or source path	Per-tab content route	Actual tab target. `http(s)` becomes a Chromium tab, `rtsp(s)` becomes the RTSP player, `file://.qml` or `<qml>...` becomes a QML tab, and `file://.so` or `<so>...` becomes a native plugin tab.
`Tabs[].enabled \| disabled`	Boolean-like value	Per-tab entry filter	Lets you skip a tab without removing it. The parser accepts booleans, numbers, and strings such as `true/false`, `1/0`, `yes/no`, or `on/off`.
`SpecialURL`Not wired	String URL	PanelView special config route	A `specialURL` property still exists in QML with a default of `http://localhost/conf/`, but JSON application is commented out in `main.qml`, so this key is currently not active.

JSON key	Accepted values	Applied in	Feature / behavior
`isNavbarSlidable`	true \| false	InputEventHandler / navbar gesture layer	Enables the slide gesture that opens and closes the navbar.
`isNavbarShownAtStart`	true \| false	Initial navbar state	Starts with the navbar already shown and allows the initial one-time state change path in the input handler.
`isNavbarOverlay`	true \| false	Window layout	Makes the navbar float above content instead of pushing the content area downward.
`isNavbarTransparent`	true \| false	Navbar rendering	Enables partial transparency for the navbar in overlay mode and while dragging in non-overlay mode.
`isGUI3dOptic`	true \| false	Navbar / dialog styling	Turns on the 3D-style optics used by the navbar and tab lister dialog.
`NavbarBaseColor`	CSS-like color string	Derived navbar palette	Seeds the derived color palette used by the shell chrome.
`IconStyle`	`symbol` \| `number` \| `letter` \| `favicon`	Tab icon derivation	Selects how tab icons are generated. With `BackgroundLifecycleState=discarded`, the code forces `symbol` if `favicon` would break discarded tabs.
`isScreenshotButton`	true \| false	Navbar button visibility	Shows or hides the screenshot button.
`isTabListerButton`	true \| false	Navbar button visibility	Shows or hides the tab lister button.
`isHardResetAllButton`	true \| false	Navbar button visibility	Shows or hides the hard-reset-all-tabs button.
`isDownloadAllowed`	true \| false	Download manager	Globally permits or denies browser downloads from web content.

JSON key	Accepted values	Applied in	Feature / behavior
`Lang`	Language or Accept-Language string	Web profile + keyboard locale selection	Sets `httpAcceptLanguage` for web tabs and also seeds the virtual keyboard locale chooser with the best matching available locale.
`KeyboardLocales`	Array or string list	Qt virtual keyboard settings	Restricts the active keyboard locales. Strings may be split by spaces, commas, or semicolons, `-` is normalized to `_`, and an empty result means all locales stay enabled.
`KeyboardWidthPercent`	Integer percent	InputPanel layout	Controls the width of the virtual keyboard panel.
`KeyboardShowMode`	`auto` \| `numpad` \| `full`	Keyboard mode controller	Selects automatic layout, forced numpad, or forced full keyboard. In forced modes the controller injects a `123`/`ABC` toggle key.
`isKeyboardFloating`	true \| false	Window / panel sizing	Makes the keyboard float above content instead of resizing the panel area.
`isKeyboardAlwaysVisible`	true \| false	Window keyboard visibility state	Keeps the virtual keyboard visible even without normal focus-driven show/hide transitions.
`isKeyboardQuirkAutofocus`	true \| false	Web tabs primarily	Injects a focus workaround script for difficult web inputs that otherwise fail to trigger the virtual keyboard.
`isGoBackForwardSwipeable`	true \| false	InputEventHandler	Enables left/right swipe navigation for the active tab.
`isHoverMoveEventsSuppressed`	true \| false	InputEventHandler event filter	Suppresses hover-move event traffic when the platform input stack produces too much pointer noise.
`isTabListerSwipe`	true \| false	InputEventHandler gesture layer	Allows the gesture that opens the tab lister by swipe.

JSON key	Accepted values	Applied in	Feature / behavior
`isDesktopMode`	true \| false	WebEngineProfile	Controls user-agent mode. `true` keeps the desktop user agent, `false` rewrites it to an Android mobile-style agent.
`Scale`	Number	View `zoomFactor` property	Maps directly to WebEngine zoom. Other view types accept the property but do not currently apply a visible scaling behavior.
`VerboseConsole`	true \| false	Web tabs, RTSP view, plugin args	Turns on more verbose runtime logging and is forwarded into native plugin arguments.
`isMicAndDevicesAllowed`	true \| false	Web permission handler	Auto-accepts or denies microphone and device permission requests from web content.
`isUploadAllowed`	true \| false	Web file dialog handler	Allows or blocks upload file dialogs requested by web content.
`DisableContextMenu`	true \| false (`true` suppresses it)	Web context-menu requests	Accepts the context-menu request so the built-in WebEngine context menu does not appear.
`InsaneAllowCertificateError`	true \| false	Web certificate-error handler	Accepts certificate errors in web tabs. The name is accurate: this is intentionally an unsafe bypass.
`isShowScrollbars`	true \| false	WebEngine settings	Turns WebEngine scrollbars on or off.
`isAutoPopupsBlocked`	true \| false	Web popup policy	Blocks non-user-initiated popups when enabled.
`isOpenPopupDialogInOverlay`	true \| false	Web popup/dialog routing	Routes popup dialogs into the overlay path instead of letting them escape as unmanaged windows.
`isOpenPopupWindowInOverlay`	true \| false	Web popup/window routing	Routes popup windows into the overlay path when possible.
`isReloadOnTabChange`	true \| false	Web tabs and RTSP tabs	Reloads the active web tab on activation and reopens RTSP streams when the view becomes visible again. Current QML/plugin views expose the flag but do not implement a separate reload-on-activate path.
`isZoomGestureEnabled`	true \| false	Early Chromium startup flags	When disabled, startup appends `--disable-pinch` so pinch zoom gestures are turned off in Chromium.

JSON key	Accepted values	Applied in	Feature / behavior
`PersistentWebStoragePath`	Directory path	Browser persistent web storage root	Defines where disk cache and persistent web storage live when persistence is enabled. The path is created if needed and rejected if it is invalid or resolves to `/`.
`isPersistentWebStorage`	true \| false	Web profile creation + startup cleanup	Enables disk-backed cache/storage. If false or undefined, hex-browser deletes the persistent web storage tree on startup, while trying to preserve a screenshot directory nested inside it.
`PersistentScreenshotPath`	Directory path	Screenshot storage	Target directory for screenshots.
`BrightnessFilename`	Writable backlight file path, optionally with one `*` wildcard	Browser backlight control	Points to the brightness sysfs file. The code supports one wildcard segment so deployments can survive varying backlight device names.
`DefaultBrightness`	Integer or `-1`	Backlight restore path	Brightness restored after startup or screensaver exit. Empty, invalid, or negative values fall back to the panel max brightness; too-low values are clamped to roughly 10% of max.
`ScreenSaverTimeout`	Minutes	Screensaver timer	Idle timeout before the screensaver becomes visible and the display power-off flow starts.
`RestartTimeout`	Minutes	Screensaver wake path	Measures time spent in screensaver mode. If the timeout is exceeded, leaving the screensaver triggers a hard reset of all tabs.
`ScreenSaverSuspendLevel`	`0` \| `1` \| `2` \| `3` \| `4`	Display power-off / suspend path	Selects how aggressive screensaver power handling becomes: `0` only drives brightness to zero, `1` also requests display power-off, `2` uses the watch-mode restart path, and `3/4` attempt system suspend with fallback if needed.
`BackgroundLifecycleState`	`active` \| `frozen` \| `discarded`	Background web tabs	Defines how inactive Chromium tabs are treated. `discarded` is the strongest memory-saving mode and is the default in current QML.

hex-browser - embedded app shell for native Flutter, web apps, QML, plugins, and RTSP

App shell first, browser included

One configuration, mixed content

Configuration space for field deployment

Prepared for real operator screens

Industrial machine control

Home and building automation

Browser-in-browser workflows

Feature screencast

Built for unattended devices

Plugins and extension path

Supported content paths

Source-mapped JSON configuration reference

Tabs and routing

Shell, navbar, and operator tools

Keyboard, gestures, and input handling

WebEngine and per-view behavior

Storage, brightness, timers, and lifecycle

Startup, system integration, and splashscreen

Reload, VNC, and resilience controls

JSON key	Accepted values	Applied in	Feature / behavior
`TimeZone`	Zone name such as `Europe/Berlin`	Process environment (`TZ`)	Exports `TZ` if the matching `/usr/share/zoneinfo/...` file exists, so libc and the runtime use the configured timezone.
`isDarkMode`	true \| false	Window colors, Qt style hints, Chromium startup flags	Switches the shell between light and dark, updates `Qt.styleHints.colorScheme`, and appends a Chromium blink override so `prefers-color-scheme` behaves as intended.
`ScreenRotation`	`0` \| `90` \| `180` \| `270`	Window/root rotation and startup environment	Rotates the visible UI and also feeds the early startup rotation state used by the application and VNC path.
`StartupSplashscreenMaxTimeoutSec`	Seconds, clamped to `0..180`	StartupLogo resolver	Maximum startup splash duration. `0` disables the splash entirely.
`ttm.logo-custom`	true \| false	StartupLogo resolver	Enables custom splash loading, but only matters when the splash timeout is above zero.
`ttm.logo-partuuid`	Partition UUID string	StartupLogo resolver	Selects the mounted partition from which a custom splash logo may be loaded. Empty values fall back to the built-in default PARTUUID in source.
`ttm.logo-path`	Safe relative path on that partition	StartupLogo resolver	Relative path to the custom splash image. The resolver rejects unsafe paths and only accepts readable PNG or BMP files.
`isRemoteDebuggingEnabled`	true \| false	Early Chromium startup environment	Enables Qt WebEngine remote debugging on `0.0.0.0:9222`.

JSON key	Accepted values	Applied in	Feature / behavior
`ReloadPageInterval`	Seconds	Periodic reload timer	Reloads the active reloadable tab on an interval. Web tabs prefer `ReloadAndBypassCache` so periodic refreshes do not pile up HTTP cache growth.
`ReloadPageIntervall`Legacy	Seconds	Periodic reload timer	Legacy misspelled key that still maps to the same reload interval as `ReloadPageInterval`.
`isVNCEnabled`	true \| false	VNC server startup	Turns the built-in VNC server on or off. When enabled, startup also reads the related port, password, address, and rotation keys.
`VNCPort`	Integer port, default `5910`	VNC server bind settings	TCP port used by the VNC server.
`VNCPassword`	String, empty allowed	VNC authentication	Password passed into the VNC server. Empty means no password is configured.
`VNCRotation`	`0` \| `90` \| `180` \| `270`	Captured VNC frame rotation	Rotation used for the VNC stream. The code normalizes it against `ScreenRotation` so the captured scene rotation stays absolute.
`isVNCAddressAny`	true \| false	VNC bind address	When true, the VNC server binds to any address. When false, it binds only to localhost.
`ResetThresholdRssMiB`	MiB threshold	ResetThresholdMonitor	RSS memory threshold that can trigger a hard reset of all tabs when the monitor decides the process is over budget.
`ResetThresholdCpuPercent`	CPU percentage threshold	ResetThresholdMonitor	CPU threshold paired with the RSS threshold for automated recovery decisions.