# NebulaOS NebulaOS is an open source Linux-based operating system experience built around two modes: 1. **Bigscreen Mode**: a controller-first console-style interface for games, apps, media, settings, and system navigation. 2. **Desktop Mode**: a clean KDE-based desktop experience for productivity, development, file management, and advanced system control. NebulaOS is not just a launcher, Steam skin, or Big Picture replacement. It is a full OS experience designed to make Linux feel native on gaming PCs, handhelds, TV setups, and eventually dedicated console-like hardware. The goal is to combine the best parts of console UX, desktop Linux, and modern operating system design into one flexible system. --- ## Vision NebulaOS is designed around a simple idea: > A gaming OS should feel like a console when you are gaming, and like a real desktop when you need one. Most gaming-focused Linux setups are either: * Too desktop-oriented for controller use * Too launcher-dependent * Too tied to Steam * Too limited when the user needs full desktop control NebulaOS aims to solve that by providing both: * A polished controller-first Bigscreen interface * A proper Linux desktop mode The long-term goal is to create an OS that can work as: * A Steam Deck-style handheld interface * A living room gaming console UI * A gaming PC frontend * A full Linux desktop * A foundation for future Nebula hardware --- ## Modes ### Bigscreen Mode Bigscreen Mode is the main console-style experience. It is designed for: * Controllers * TVs * Handhelds * Game launching * App launching * System settings * Power controls * Profiles * Media-focused workflows Bigscreen Mode is built as a fullscreen Nebula shell using Tauri, HTML, CSS, JavaScript, and a controller-first navigation system. Current v0 features include: * Lock screen with controller and keyboard PIN keypad * Home dashboard tile grid * Library screen * Settings screen * Power overlay * Unified input actions from keyboard and gamepad * Xbox-inspired horizontal dashboard layout * Dynamic nebula background visuals * Controller focus states and smooth transitions Read more in: ```text bigscreen/README.md ``` --- ### Desktop Mode Desktop Mode is the full Linux desktop experience. It is intended for: * File browsing * Productivity * Web browsing * Development * System configuration * Troubleshooting * Advanced settings * Desktop gaming workflows The recommended Desktop Mode foundation is KDE Plasma because it is flexible, themeable, controller-adaptable, and already well-suited to Linux gaming environments. Desktop Mode should feel clean, modern, and polished, with a design direction inspired by the clarity and smoothness of macOS while keeping the flexibility of Linux. Read more in: ```text Desktop/README-Desktop.md ``` --- ## What NebulaOS Is NebulaOS is: * A Linux-based gaming operating system experience * A controller-first shell for Bigscreen use * A KDE-based desktop experience for normal computer use * A unified game and app launcher * A modular platform for Nebula apps * An open alternative to proprietary gaming frontends * A foundation for future console-like hardware --- ## What NebulaOS Is Not NebulaOS is not: * A Steam skin * A Steam Big Picture clone * A launcher-only project * A proprietary console OS * A replacement for Linux itself * A locked-down gaming environment NebulaOS should work with Steam, GOG, Epic Games, local apps, native Linux games, Proton, Wine, and other tools without depending on one company’s frontend. --- ## Core Principles 1. **Controller-first, not controller-compatible** Bigscreen Mode should be designed from the ground up for controller navigation. 2. **Desktop when needed** Users should always be able to access a proper desktop environment. 3. **Open and modular** NebulaOS should be built from replaceable, understandable components. 4. **Independent from proprietary launchers** Store integrations should exist, but NebulaOS should have its own interface. 5. **Console feel, PC freedom** NebulaOS should feel simple and polished without removing user control. 6. **Built for iteration** v0 should be simple, but the architecture should leave room for long-term growth. --- ## High-Level Architecture NebulaOS is split into several layers: ```text NebulaOS ├── Bigscreen Mode │ ├── Nebula Home │ ├── Nebula Library │ ├── Controller Settings │ ├── Power Menu │ └── Profile / Lock Screen │ ├── Desktop Mode │ ├── KDE Plasma │ ├── Nebula desktop theme │ ├── Desktop apps │ └── Advanced system tools │ ├── Nebula Core │ ├── Input │ ├── Navigation │ ├── Theme │ ├── Glyphs │ └── Shared UI logic │ └── System Integration Layer ├── Game discovery ├── App launching ├── Store integrations ├── Proton / Wine handling ├── Network settings ├── Audio settings ├── Display settings └── Power controls ``` --- ## Technology Stack ### Bigscreen Mode * Tauri * HTML * CSS * JavaScript * Rust backend through Tauri * Web Gamepad API * Nebula Core ### Desktop Mode * Linux * KDE Plasma * SDDM * Custom Nebula theme * Custom session configuration * Optional Nebula desktop tools ### Game and App Layer Planned integrations include: * Native Linux apps * Local executables * Steam * SteamCMD * Proton * Wine * GOG * Epic Games * Legendary * Heroic backend concepts * Local metadata databases --- ## Current Repository Status This repository currently contains the early NebulaOS v0 prototype. Current features include: * Tauri frontend shell * Controller and keyboard input mapping * Lock screen * Home dashboard * Library stub * Settings stub * Power overlay * Nebula Core adapter structure * Xbox-inspired dashboard refresh * Windows-first development setup * Linux build pathway The project is currently focused on building the Bigscreen shell first, while planning Desktop Mode as the second major pillar of the OS. --- ## Install ```bash npm install ``` --- ## Run in Development ```bash npm run dev ``` --- ## Build ```bash npm run build ``` --- ## Linux Prerequisites For Ubuntu, Debian, and related distributions, install the system dependencies required by Tauri and WebKit: ```bash sudo apt update sudo apt install -y \ libwebkit2gtk-4.1-dev \ libappindicator3-dev \ librsvg2-dev \ patchelf \ build-essential \ curl \ wget \ file \ libssl-dev \ libgtk-3-dev ``` You will also need: * Node.js LTS * Rust * npm Then run: ```bash npm install npm run dev ``` --- ## Controller Testing For development, connect an Xbox-compatible controller before launching the app. ### Controller Mapping ```text D-pad / left stick: Navigate A: Accept B: Back Start: Menu ``` ### Keyboard Mirror ```text Arrow keys: Navigate Enter: Accept Escape / Backspace: Back ``` --- ## Nebula Core Integration NebulaOS uses `@nebulaproject/core` through runtime adapters. Current adapter files: ```text src/core/input.js src/core/nav.js src/core/state.js ``` If Nebula Core exports are available, NebulaOS uses them for input, navigation, glyphs, and theme handling. If they are unavailable, local fallback adapters keep the shell functional during development. --- ## Local Nebula Core Development For active local development, clone Nebula Core next to this repository. ```bash # In Nebula-Core repo npm link # In NebulaOS repo npm link @nebulaproject/core ``` Alternative deterministic setup using `file:` dependency: ```json { "dependencies": { "@nebulaproject/core": "file:../Nebula-Core/packages/core" } } ``` Then run: ```bash npm install ``` --- ## Development Strategy NebulaOS is currently developed across two environments. ### Windows Used for: * UI development * Controller navigation * Lock screen work * Library UI * Settings UI * Frontend architecture ### Linux VM Used for: * Linux builds * Session testing * KDE integration * Fullscreen shell testing * Proton and Wine experiments * System service experiments The current workflow is: ```text Design and build the UI on Windows. Test OS-level behavior in Linux. ``` --- ## Roadmap ### Phase 1: Bigscreen Shell Goal: Build a polished controller-first shell. Deliverables: * Lock screen * Home dashboard * Library screen * Settings screen * Power menu * Controller navigation * Fullscreen mode * Basic app launching --- ### Phase 2: Desktop Mode Foundation Goal: Create the NebulaOS desktop environment experience. Deliverables: * KDE Plasma setup * Nebula theme * SDDM login configuration * Bigscreen and Desktop session entries * Desktop-to-Bigscreen switching * Basic Nebula desktop tools --- ### Phase 3: Session Integration Goal: Make NebulaOS feel like a real OS experience. Deliverables: * Bigscreen session selectable from login * Desktop session selectable from login * Bigscreen launches fullscreen * Exit to desktop or login * Controller works reliably in Bigscreen Mode --- ### Phase 4: Nebula Library Foundation Goal: Begin true game and app management. Deliverables: * Local app database * Installed games database * Manual game adding * Local executable launching * Metadata structure * Cover art and banner support * Store backend abstraction --- ### Phase 5: Store and Compatibility Integrations Goal: Turn Nebula Library into a real open game manager. Potential integrations: * SteamCMD * Proton * Wine * Legendary for Epic Games * GOG tooling * Heroic backend concepts * Per-game compatibility settings --- ## Success Criteria for v0 NebulaOS v0 is successful when: * Bigscreen Mode can be launched fullscreen * The entire shell is controller navigable * The lock screen works * The Home dashboard works * The Library can display and launch local entries * Settings has a usable controller-first structure * Power controls exist * Desktop Mode remains accessible * Bigscreen and Desktop feel like two parts of the same OS --- ## Long-Term Goal NebulaOS should become a gaming OS that feels native, polished, and open. A user should be able to: * Turn on a machine * Pick up a controller * Navigate the whole system * Launch a game * Switch to Desktop Mode when needed * Manage apps, games, settings, and profiles * Use the system without needing Steam Big Picture or a traditional desktop launcher NebulaOS is the bridge between a console experience and a real computer.