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:

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 / 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

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
• 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:

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.