LuneOS
LuneOS is an open-source mobile operating system based on the webOS Open Source Edition (OSE), developed by the webOS Ports community to provide a community-driven platform for modern open hardware devices.[1] It builds on the Linux kernel and incorporates updated components such as Qt6 for its user interface, Wayland for compositing, and Chromium for web applications, emphasizing multitasking through a card-based metaphor inherited from the original webOS.[1] Originally forked from HP's Open webOS, which was open-sourced in 2012 after the discontinuation of Palm's webOS mobile platform, LuneOS was first released on September 1, 2014, under the codename "Affogato" by the webOS Ports project.[2] The project has since produced 29 updates, with significant development focusing on porting to new architectures and improving core components; the most recent stable version, Eiskaffee, was released on February 15, 2024, following a major internal rework that addressed build system challenges and migrated 125 components to webOS OSE 2.23.0.[2][1] Development is hosted on GitHub and supported by a community forum at webOS Ports, with ongoing efforts to enhance security through features like the App Container Guard (ACG) and to integrate newer web technologies such as Chromium 108.[1] Key features of LuneOS include its gesture-based navigation, support for web applications via the Web App Manager (WAM), and compatibility with mainline Linux kernels, enabling it to run on devices like the PinePhone, PinePhone Pro, and PineTab2 from Pine64, as well as emulated environments such as QEMU x86-64 and select Android-based hardware through Halium.[1] It prioritizes open-source principles, with installation guides available for supported hardware and plans for further expansions to devices like Raspberry Pi 3/4, while legacy webOS hardware support has shifted to the separate LunaCE project.[2][1] As of November 2025, with Eiskaffee remaining the latest stable release, LuneOS serves as a niche alternative in the mobile Linux ecosystem, with focus on usability improvements in audio, multimedia, and camera functionality.[1]History
Origins from webOS
Palm launched webOS in January 2009 as a successor to the Palm OS, introducing a Linux-based mobile operating system designed for smartphones with innovative features such as card-based multitasking and the Synergy integration system for seamless data sharing across accounts like email, social media, and messaging.[3][4][5] The first webOS device, the Palm Pre, debuted in June 2009 on Sprint, highlighting the platform's gesture-based navigation and just-type search capabilities.[5] In April 2010, Hewlett-Packard (HP) announced its acquisition of Palm for $1.2 billion to bolster its mobile computing efforts, including full control over the webOS platform.[6] The deal closed in July 2010, allowing HP to integrate webOS into its hardware lineup, such as the Pre 3 smartphone and TouchPad tablet.[7] However, facing market challenges and poor sales, HP discontinued all webOS hardware development in August 2011, halting production of devices like the TouchPad just weeks after its launch.[8] In response to the hardware cancellation, HP pledged to support webOS software and announced plans to open-source it in December 2011.[9] This culminated in the release of Open webOS in August 2012 under the Apache 2.0 license, providing the core codebase—including the Enyo framework and key services—for community development without proprietary hardware ties.[10] Following the open-sourcing, early community efforts focused on porting Open webOS to new devices, with the webOS Ports project emerging as a key initiative to revive the platform on modern hardware.[11] The webOS Ports project achieved a significant milestone with its Alpha 2 release on June 26, 2013, serving as a direct predecessor to LuneOS and demonstrating initial viability on devices like the HP TouchPad.[11] Transitioning the original webOS components to contemporary environments presented challenges, particularly in adapting the Mojo application framework—originally built for webOS's HTML5/JavaScript apps—to newer Linux kernels and avoiding outdated dependencies.[12] Developers addressed these by rewriting core elements, such as the LunaSysMgr window manager, to leverage modern technologies like Qt 5, QML for UI rendering, and WebKit 2 for web content, ensuring compatibility with evolving kernel versions while preserving webOS's multitasking and integration paradigms.[13]Establishment of WebOS Ports
The WebOS Ports community emerged in early 2013 from developers previously involved in the webOS Internals group, which had been active since 2009 in enhancing HP's webOS hardware.[14] This initiative built on HP's 2012 release of Open webOS, aiming to port the operating system to Android-compatible hardware by leveraging libhybris—a compatibility layer that allowed webOS to utilize Android's hardware abstraction layer and drivers on Linux kernels.[14][13] The community's formation was driven by the need to sustain webOS after HP's withdrawal from mobile devices, with initial efforts focusing on devices like the Samsung Galaxy Nexus and Google Nexus 4 to demonstrate viability on modern touchscreens.[14] By mid-2013, the project achieved an Alpha 2 release on June 26, marking progress toward a functional port, though stability remained a challenge.[2] The core goals centered on reviving webOS as an open-source mobile operating system optimized for touchscreen devices, emphasizing community-driven development to provide a lightweight alternative for smartphones and tablets without aiming to rival established platforms like Android or iOS.[15] These objectives included ensuring compatibility with legacy webOS applications while adapting to contemporary hardware, prioritizing basic functionality such as telephony, connectivity, and a responsive interface.[15] On September 1, 2014, the WebOS Ports team launched the first official release of LuneOS, codenamed Affogato, rebranding from the cumbersome "WebOS Ports Open webOS" to better reflect its independent evolution—subsequent releases would follow a coffee-themed naming convention.[15] This rolling-release distribution targeted the Google Nexus 4 as its primary device, with support for the HP TouchPad and limited compatibility for the Galaxy Nexus and Nexus 7 (2012 WiFi edition).[15] Affogato represented a milestone in achieving bootable images with core services operational, though it required ongoing monthly updates to refine performance.[13] Early development faced significant technical hurdles, particularly in bridging the original webOS's legacy components with modern frameworks. A key challenge was rewriting the LunaSysMgr window manager—replaced by Luna Next—to support hardware acceleration and cross-device portability, necessitating the integration of Qt 5.2 and QML for the user interface while preserving compatibility with existing Enyo-based webOS applications.[15] This transition addressed inefficiencies in the original codebase, such as outdated graphics handling, but demanded extensive testing to avoid regressions in multitasking and input responsiveness on Android-derived hardware.[15] Despite these obstacles, the use of libhybris enabled successful abstraction of hardware components like sensors and cameras, laying the groundwork for broader device support.[14]Development
Community and contributions
LuneOS development is driven by the WebOS Ports volunteer community, a small but dedicated group of developers maintaining the operating system through collaborative efforts. The community operates without formal corporate backing, relying on individual contributors to handle thousands of components, including bug fixes and feature enhancements.[16] Community interaction primarily occurs on forums such as forums.weboslives.eu, where members discuss development, share testing feedback, and report issues for devices running LuneOS. These forums serve as the central hub for volunteer testers to provide input on stability and usability, following the closure of the previous primary forum at webosnation.com in late 2022. Additionally, announcements and testing threads are integrated with PivotCE, a community blog that coordinates updates and solicits participation from volunteers.[17][18][1] Key contributors include the core WebOS Ports team, who oversee major integrations and releases, with milestones such as the adoption of PivotCE for streamlined communication and testing coordination enhancing community efficiency. Contributions are welcomed via GitHub repositories like webOS-ports/luneos-releases, where developers submit pull requests after cloning the codebase; approvals require review by at least one core developer, and initial contact can be made through the project's communications channels.[19][16][20] Development primarily involves coding in C, C++, QML, JavaScript, and related technologies like Qt and Node.js, focusing on areas such as UI enhancements, kernel adaptations, and build system tweaks using tools like Yocto. Licensing follows open-source standards: the core components, derived from webOS Open Source Edition, are under the Apache License 2.0; the Linux kernel adheres to the GNU General Public License version 2; while applications and build recipes typically use the MIT License for permissive distribution.[16][21]Tools and build system
LuneOS utilizes the OpenEmbedded build framework in conjunction with the Yocto Project to construct its system images, enabling modular and reproducible builds tailored for embedded devices.[22] The core of this infrastructure is the meta-luneos layer, which provides recipes, configurations, and distro-specific settings for assembling complete LuneOS images, including components like the luneos-image for reference builds and the luneos-sdk for generating installable toolchains.[22] This layer integrates with other OpenEmbedded layers to handle dependencies and ensure compatibility across supported hardware.[23] For package management, LuneOS employs Preware, an on-device homebrew installer that handles the installation, updating, and removal of applications via IPKG-based .ipk files.[24] The underlying service, org.webosports.service.ipkg, facilitates this process as the primary package management mechanism for webOS-derived systems like LuneOS.[25] Integration with the Halium project provides a unified hardware abstraction layer, allowing LuneOS to leverage minimal Android images and ports from ROMs such as LineageOS for device-specific hardware support on Linux-based mobile platforms.[26] Developers contribute to Halium to standardize middleware interactions with device hardware, though LuneOS primarily uses the project's base Android HAL components for porting.[26] The development workflow centers on BitBake, the task executor of the Yocto Project, which orchestrates the build process for creating custom images.[27] Developers set up the environment by fetching required layers and then invoke BitBake commands, such asMACHINE=<device> bitbake luneos-dev-image, to generate deployable images.[27] Cross-compilation is supported natively for ARM architectures, with the luneos-sdk producing toolchains that enable building applications and components on host systems for target devices.[22] This setup requires a compatible host like Ubuntu and essential packages for the build environment, ensuring efficient targeting of ARMv7 and ARMv8 hardware.[27]
Architecture
Core components
LuneOS is built upon the Linux kernel, leveraging device-specific configurations that align with upstream long-term support (LTS) releases to ensure stability and security updates. For ports targeting mainline hardware like the PinePhone, it incorporates kernels such as Linux 5.15 from the Yocto Project's Kirkstone branch, while Halium-based ports adapt older device kernels (typically 3.10 or later) from Android lineages to maintain compatibility with legacy hardware.[28] In the February 2024 Eiskaffee release, LuneOS was rebased on webOS Open Source Edition (OSE) 2.23.0, migrating 125 core components while retaining 15 custom ones. This update enhanced security through the App Container Guard (ACG) for the Luna Service 2 (LS2) bus and adopted LG's Web App Manager (WAM) integrated with a Chromium fork (version 94).[1] At the system services layer, LuneOS includes the Media Indexer, a service that scans media files across internal and external storage devices, extracting metadata for audio, video, and images in a manner compatible with the original webOS API. This enables efficient content organization and supports playback functionalities for multimedia through integrated daemons. Essential networking is handled by ConnMan, a lightweight daemon initially focused on WiFi connectivity in early implementations but later expanded to include broader internet management for embedded devices.[15][29] Hardware integration in LuneOS relies on the Halium project for abstraction layers derived from Android, utilizing libhybris to interface with graphics, telephony, and sensor hardware via the minimal Android System Image (ASI). This approach allows LuneOS to run on Android-sourced devices by bridging the Linux userspace with proprietary drivers without full Android dependency. The base operating system recipes, encompassing these core daemons and services, are distributed under the MIT license to facilitate open community contributions.[30][26]User interface framework
LuneOS employs Qt 6 (version 6.5.2 as of the February 2024 release) as its primary graphical framework, enabling developers to create declarative user interfaces through QML, a JavaScript-based language that facilitates rapid prototyping of interactive and visually rich applications.[1][31][12] This approach allows for separation of UI logic from business logic, promoting modular and maintainable codebases for mobile environments. Qt's cross-platform capabilities ensure compatibility across supported hardware while optimizing for touch-based interactions.[32] Central to the user interface management is LunaSysMgr, the system manager responsible for window compositing, input handling, and gesture recognition tailored to touchscreen devices.[32] It supports direct manipulation paradigms, such as card-based layouts and swipe gestures, which define the webOS-inspired interaction model in LuneOS. In the February 2024 Eiskaffee release, the project adopted LG's luna-surfacemanager as the Wayland compositor, replacing the earlier Luna Next initiative, to leverage enhanced modularity and integration with webOS OSE components.[1][31][33] For display protocols, LuneOS integrates Wayland as its compositor backend, supplanting the legacy X11 system to provide more efficient rendering, reduced latency, and better security through isolated client-server communication.[32][31] This shift enables seamless hardware acceleration and supports the direct rendering of QML elements without intermediate layers, improving overall responsiveness on resource-constrained devices. LunaSysMgr, and its successor luna-surfacemanager, operates as the Wayland compositor, managing surface allocation and input events to ensure fluid transitions between application cards.[22] Web content rendering in LuneOS is handled by Qt WebEngine, a Chromium-based module integrated into Qt, which allows embedding of HTML5 applications and web views within native QML contexts.[34] This component supports modern web standards, including accelerated graphics and secure sandboxing, enabling hybrid apps that blend web and native elements without performance degradation.[35] Native QML-based applications exemplify the framework's strengths, such as the phone dialer, which leverages QML for its interface to deliver faster load times and more reliable touch responses compared to traditional HTML5 implementations.[34] By compiling QML to native code via Qt's just-in-time compiler, these apps achieve near-native performance, reducing overhead and enhancing battery efficiency on mobile hardware.[31]Features
Multitasking and UI elements
LuneOS employs a card-based multitasking system inherited from webOS, where running applications are represented as individual "cards" that users can swipe horizontally to switch between. This paradigm allows seamless navigation without relying on traditional app switchers or icon grids, enabling users to maintain context across multiple tasks. To close an app, users perform a leftward swipe on its card, which dismisses it from the view while preserving system resources by minimizing background processes. Apps continue running in a minimized state until a timeout triggers the termination of associated JavaScript services, optimizing performance on resource-constrained devices.[36][37] Universal Search in LuneOS, known as Just Type, provides quick system-wide access to applications, contacts, media, and other content through a single, live-updating search field. Activated by tapping the search bar or typing on a connected keyboard, it queries multiple databases in real-time with each keystroke, delivering relevant results without requiring users to open specific apps first. This feature enhances discoverability and efficiency, integrating searches across the OS for a unified experience.[36][38] Gesture support in LuneOS emphasizes intuitive touch interactions, including a back swipe from the screen's edge to trigger app-specific navigation actions, such as clearing search inputs or returning to previous views. Swipe gestures also facilitate info-flow between applications, allowing users to drag content like text or media from one card to another for seamless sharing. The Human Interface Guidelines prioritize public and private channels for data movement, where public channels enable visible content sharing among apps while private channels support discreet, user-controlled exchanges to promote privacy and fluid interactions.[36][39]Application support
LuneOS supports the development of applications using both HTML5-based web apps through the Enyo JavaScript framework and native applications built with QML (Qt Modeling Language) for the Qt framework.[40] Enyo enables cross-platform HTML5 apps that leverage web technologies for interactive user experiences, with many core system applications in LuneOS developed using versions of Enyo up to 2.7.[41] QML apps, on the other hand, provide native-like performance and integration with the system's Luna UI components, allowing developers to create responsive interfaces using declarative syntax and C++ for backend logic. As of the Eiskaffee release in February 2024, LuneOS has migrated to Qt 6.5.2, enhancing support for QML-based native applications and integrating with the Luna UI components.[1][40] For legacy compatibility, LuneOS maintains partial support for webOS applications via the Preware installer, which distributes IPK packages from the original webOS ecosystem; however, full Mojo runtime emulation for first-generation webOS apps is not available, limiting compatibility primarily to Enyo-based apps from webOS 2.x and later.[42][24] This allows users to access thousands of community-maintained legacy apps, such as utilities and games, without a central repository.[43] Unlike proprietary mobile OSes, LuneOS lacks an official app store, relying instead on community-driven distribution through Preware feeds hosted on platforms like pivotCE, where developers submit and users discover homebrew applications, patches, and themes.[15][22] Development for LuneOS apps utilizes Qt Creator as the primary IDE for QML-based native applications, supporting desktop emulation and integration with LuneOS-specific components like luna-next-cardshell for UI testing.[40] For HTML5 and Enyo apps, developers can leverage remnants of the original webOS SDK for packaging and cross-platform building, combined with standard web tools, enabling deployment to LuneOS alongside other Linux-based systems.[44]Supported hardware
Compatible devices
LuneOS initially provided official support for the Google Nexus 4 (codenamed Mako), a 2012 flagship smartphone featuring a Qualcomm Snapdragon S4 Pro quad-core ARM processor, 2 GB RAM, and 8 GB or 16 GB internal storage options.[45][46] This device served as a primary target for early LuneOS ports, leveraging its Android-compatible hardware for the operating system's minimal Android System Image.[15] Support has expanded as of the February 2024 Eiskaffee release to modern open hardware devices, including the PinePhone, PinePhone Pro, PineTab2, Raspberry Pi 2, and Raspberry Pi 3, which utilize mainline Linux kernels and integrate seamlessly with LuneOS through community efforts (alpha stage for these devices).[1][46] Additionally, Halium-based ports enable compatibility with a range of LineageOS-supported smartphones, such as the Google Nexus 5, Nexus 7 (2012), Xiaomi Redmi Note 4X, and Xiaomi Mi A1, by utilizing existing Android HAL layers for hardware abstraction.[26][46] These ports allow LuneOS to run on devices with established LineageOS ROMs, broadening accessibility without requiring full hardware redesign.[47] Legacy webOS hardware, including the HP TouchPad tablet and older Palm/HP smartphones, is excluded from LuneOS support and instead maintained by the separate LunaCE project, which focuses on preserving the original webOS ecosystem for those devices.[2][48] LuneOS targets touchscreen mobile and tablet devices equipped with ARM processors and a minimum of 1 GB RAM to ensure basic functionality, though optimal performance is observed on systems with 2 GB or more.[46] Hardware features like cameras, GPS, and NFC receive partial support, depending on the device port and driver availability, with full integration varying by community contributions.[49] Installation methods for these compatible devices are outlined in the dedicated installation process section.Installation process
Installing LuneOS requires specific prerequisites depending on the target hardware, primarily an unlocked bootloader for devices originally running Android, as this allows flashing custom images. Many ports rely on a Halium-compatible Android ROM as the base layer to handle hardware abstraction, providing necessary drivers for components like the GPU and modem before overlaying the LuneOS root filesystem. Users must also have access to a computer with Linux (recommended for compatibility with build tools) and basic command-line proficiency.[28] The primary installation methods involve flashing pre-built images or constructing custom ones. For Qualcomm-based devices like the Nexus series, fastboot is commonly used: boot the device into fastboot mode, then execute commands such asfastboot flash [boot](/page/Boot) luneos-boot.img followed by fastboot flash [system](/page/System) luneos-system.img to install the kernel and rootfs.[50][51] SD card-based installation applies to mainline hardware like PinePhone or PineTab2; images are written to the card using dd if=luneos-image.img of=/dev/sdX bs=4M or tools like Balena Etcher, after which the card is inserted and the device boots from it. For tailored installations on unsupported or specific hardware, users build custom images via the Yocto Project, initializing the environment with repo init -u https://github.com/webOS-ports/manifest -b master -m luneos.xml, sourcing the setup script, and running bitbake luneos-image for the target machine.[50][51]
Following installation, the device reboots into LuneOS, where initial setup involves connecting to WiFi through the System Settings app under Network & Connectivity, entering credentials, and confirming the connection. Gestures for the LunaSysMgr user interface may require calibration via the Just Type or Gestures settings panel to ensure smooth card-based navigation and multitasking. Troubleshooting common issues often centers on graphics drivers; for instance, if the display fails to render properly, verify Mesa and kernel module compatibility, potentially reflashing the Halium boot image or applying patches from the device's port repository. Other frequent problems include WiFi adapter recognition, resolved by loading firmware modules post-boot.[52][53]
As LuneOS remains in alpha stage for most ports, users should anticipate incomplete functionality, particularly telephony (e.g., calls and SMS may not initialize due to modem integration gaps) and hardware acceleration (video playback or GPU-intensive tasks could fallback to software rendering, impacting performance). These limitations stem from ongoing Halium adaptations and are device-specific; consult the official issue tracker for updates before proceeding.[54][46]