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 becoming a native Qt shell; the repo still contains a Tauri/HTML v0 prototype for early UI work. Sign-in and session choice happen at the OS login screen, not inside Bigscreen.

Current v0 features include:

• Lock screen with PIN keypad in the Tauri prototype only (OS login replaces this in the target design)
• 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:

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:

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:

NebulaOS
├── Bigscreen Mode
│   ├── Nebula Home
│   ├── Nebula Library
│   ├── Controller Settings
│   ├── Power Menu
│   └── Profile status (signed-in user; no OS login)
│
├── Desktop Mode
│   ├── KDE Plasma
│   ├── Nebula desktop theme
│   ├── Controller-friendly SDDM login
│   ├── Session entries (Bigscreen / Desktop)
│   ├── 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
• Tauri prototype lock screen (superseded by planned OS login)
• 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 building Bigscreen Mode (Qt shell) and Desktop Mode (KDE Plasma customization) in parallel. A controller-friendly OS login (SDDM + sessions) is part of Desktop/system work so Bigscreen does not handle account creation or sign-in.

---

Install

npm install

---

Run in Development

npm run dev

---

Build

npm run build

---

Linux Prerequisites

For Ubuntu, Debian, and related distributions, install the system dependencies required by Tauri and WebKit:

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:

npm install
npm run dev

---

Controller Testing

For development, connect an Xbox-compatible controller before launching the app.

Controller Mapping

D-pad / left stick: Navigate
A: Accept
B: Back
Start: Menu

Keyboard Mirror

Arrow keys: Navigate
Enter: Accept
Escape / Backspace: Back

---

Nebula Core Integration

NebulaOS uses @nebulaproject/core through runtime adapters.

Current adapter files:

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.

# In Nebula-Core repo
npm link

# In NebulaOS repo
npm link @nebulaproject/core

Alternative deterministic setup using file: dependency:

{
  "dependencies": {
    "@nebulaproject/core": "file:../Nebula-Core/packages/core"
  }
}

Then run:

npm install

---

Development Strategy

NebulaOS is currently developed across two environments.

Windows

Used for:

• UI development
• Controller navigation
• Bigscreen UI prototyping (legacy Tauri lock screen is not target architecture)
• 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:

Design and build the UI on Windows.
Test OS-level behavior in Linux.

---

Roadmap

Phase 1: Desktop Mode and OS login (in progress)

Goal: Build the KDE-based desktop layer and a controller-friendly login experience.

Deliverables:

• KDE Plasma Nebula theme and look-and-feel
• Controller-friendly SDDM login (account picker, sign-in)
• Nebula Bigscreen and Nebula Desktop session entries
• First-run / account setup at the OS layer (not inside Bigscreen)
• Desktop-to-Bigscreen and Bigscreen-to-Desktop switching
• Basic Nebula desktop tools

---

Phase 2: Bigscreen Qt shell

Goal: Build a polished controller-first game shell that starts after OS login.

Deliverables:

• Native Qt/QML Bigscreen app
• Home dashboard
• Library screen
• Settings screen
• Power menu (including log out to OS login)
• Controller navigation
• Fullscreen mode
• Basic app launching

Bigscreen does not deliver in-shell login, PIN lock, or account creation.

---

Phase 3: Session polish

Goal: Make NebulaOS feel like a real OS from boot to shell.

Deliverables:

• Reliable gamepad support on SDDM and in Bigscreen
• Bigscreen launches fullscreen into the signed-in session
• Exit to desktop or return to login
• Consistent Nebula visual identity across login, Bigscreen, and Desktop

---

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
• OS login works with controller and keyboard (SDDM; not an in-Bigscreen lock screen)
• 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.