Nebula OS v0 – Windows-first Development Plan

Nebula OS Prototype (Current)

This repository now includes a working v0 Nebula OS prototype in the Tauri frontend (src/) with:

• Lock Screen with controller/keyboard PIN keypad (1234 for v0)
• Home dashboard tile grid (Library, Settings, Power)
• Settings split-pane stub (category list + content panel)
• Library stub view with controller back behavior
• Start/Menu power overlay that traps focus and closes with Back
• Unified input actions (up/down/left/right/accept/back/menu) from keyboard + gamepad

Dashboard refresh (Xbox-inspired Nebula)

The shell now uses a premium horizontal dashboard language inspired by console UI patterns:

• Left-aligned horizontal app tile rail (Library, Settings, Power)
• Dynamic nebula background stack (gradient, starfield, fog, vignette)
• Shared top bar with reactive accent line and profile/time status
• Layered tile focus states (scale, cyan glow, ripple, elevation)
• Smooth page/focus transitions with cubic-bezier motion curves
• Immersive lock screen with large clock/date and input-revealed PIN panel
• Settings redesign with top category rail + card-based content panel

Animation and component architecture notes are in src/styles/shell-guidelines.md.

Install

npm install

Run (dev)

npm run dev

Build

npm run build

Linux prerequisites (Ubuntu/Debian)

Install system dependencies required by Tauri/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

Install Node.js LTS and Rust (if not already installed), then run:

npm install
npm run dev

Controller testing notes (Windows)

• Connect an Xbox-compatible controller before launching dev mode.
• Navigation: D-pad or left stick.
• Actions: A = Accept, B = Back, Start = Menu.
• Keyboard mirror for development: arrow keys, Enter, Escape/Backspace.

Nebula Core integration status

@nebulaproject/core is installed and used through runtime adapters in:

• src/core/input.js
• src/core/nav.js
• src/core/state.js

If Nebula Core exports are available, the shell uses them for input/navigation/glyphs/theme. If not, local fallback adapters keep the shell fully functional.

Local Nebula Core development (Windows-safe)

Current npm package @nebulaproject/core@0.1.3 re-exports internal @nebula/* packages that are not published, so local linking is recommended for active core development.

1. Clone Nebula Core monorepo next to this repo.
2. Build Nebula Core packages.
3. Link from the core repo and consume in this repo:

# In Nebula-Core repo
npm link

# In Nebula-OS repo
npm link @nebulaproject/core

Alternative (more deterministic): use file: dependency in package.json:

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

Then run:

npm install

Linux VM build (high-level)

• Install Rust, Node.js, and the Linux prerequisites above.
• Clone this repo in the Linux VM.
• Run npm install.
• Run npm run dev for integration checks in Linux session.
• Run npm run build to produce Linux artifacts.

Vision

Nebula OS is a controller-first, open source operating system experience built on Linux.

It has two equally important jobs:

1. A custom controller-first way to navigate the OS (like a console shell)
2. An open source library and launcher layer for games and apps

Nebula OS is not a skin that launches Steam. It is an independent UI layer that:

• Acts as the primary controller-first shell for the OS
• Provides a unified Home experience for games, apps, and media
• Integrates first-install Nebula apps such as Nebula Browser and Nebula Launcher
• Exposes system settings through controller-friendly panels
• Manages game libraries directly (Steam, GOG, Epic, and others)

Nebula OS v0 focuses on building the foundation for this console-grade OS shell.

---

Core Principles

1. Controller-first, not controller-compatible
2. Replace proprietary frontends with an open interface
3. Separate system layer from UI layer
4. Build modular infrastructure for long-term independence
5. Develop iteratively, but architect for autonomy

---

What Nebula OS v0 Actually Is

Nebula OS v0 consists of:

• Base OS: Ubuntu LTS (or Ubuntu-based)

• Desktop Environment: KDE Plasma (recommended)

• Display Manager: SDDM

• Two login sessions:

  • Nebula Desktop
  • Nebula Game UI

• Nebula OS (Tauri + HTML/CSS/JS)

• Nebula Library (core application responsible for:

  • Game discovery
  • Installation
  • Updates
  • Launching
  • Compatibility management)

Unlike SteamOS, Nebula OS does not rely on launching Steam Big Picture. Nebula Library is the primary game management layer.

---

High-Level Architecture

Desktop Mode

A standard KDE session for:

• Productivity workflows
• File browsing and system tools
• Development and troubleshooting
• Advanced configuration

Desktop Mode remains a normal Linux desktop.

Game UI Mode

A dedicated login session that launches Nebula OS fullscreen.

Game UI Mode contains:

• Lock screen with controller PIN entry
• Nebula Home dashboard
• Nebula Library
• Controller-friendly Settings
• Power and session controls

Game UI Mode is the console experience for the entire OS.

System Integration Layer (behind the UI)

Nebula OS needs a clean boundary between UI and system operations.

Recommended approach:

• A small privileged backend service (later) that exposes safe operations:

  • Wi-Fi and networking
  • Audio and output device selection
  • Display resolution and scaling
  • Bluetooth pairing
  • Storage overview
  • Power controls

• The UI talks to that layer through a stable API

v0 scope can start with non-privileged read-only data and a few safe commands.

---

Technology Stack

UI Layer

• Tauri
• HTML
• CSS
• JavaScript

Why Tauri:

• Lightweight
• Native system integration via Rust backend
• Cross-platform development
• Efficient resource usage

Controller Input

• Web Gamepad API
• Custom focus/navigation system

Controller mappings:

• D-pad / left stick: navigation
• A: activate
• B: back
• Start: menu
• Shoulder buttons: future navigation layers

Keyboard mirrors controller during development.

---

Nebula OS – The OS UI Layer

Nebula OS is the controller-first OS shell.

It is the primary interface in Game UI Mode and should feel like a console dashboard, not a desktop.

Nebula OS responsibilities:

• Home dashboard (games, apps, recent activity)
• App launcher for integrated Nebula apps (Nebula Browser, Nebula Launcher, Nebula Library, Settings)
• System navigation (network, audio, display, storage, accounts)
• Power menu and session switching (Game UI ↔ Desktop)
• Notifications and downloads (later)
• Controller-first focus navigation everywhere

Nebula OS is built with Tauri + HTML/CSS/JS.

---

Nebula Library – The Game and App Management Layer

Nebula Library is the content manager inside Nebula OS.

It is not a bridge to proprietary UIs. It should eventually handle:

• Steam installs via SteamCMD and/or open APIs
• GOG installs via open or community tooling
• Epic installs via open tooling (for example Legendary)
• Proton/Wine configuration and per-title settings
• Game launch parameters and runtime selection
• Updates, integrity checks, and metadata

Initial v0 scope:

• Library UI skeleton and data model
• Local entries (manual add)
• Launch local executables
• Foundation for compatibility and store backends

Long-term direction:

Nebula Library becomes a unified open source platform for managing games and apps.

---

Development Strategy

Nebula OS is developed in two environments:

Windows (Primary UI Development)

Used for:

• Building Nebula OS UI
• Implementing controller navigation
• Designing lock screen
• Designing Library UI
• Building system state architecture

UI and logic are platform-agnostic.

Linux VM (Integration & Replacement Layer)

Used for:

• Building Linux binaries
• Session integration
• SteamCMD integration testing
• Proton/Wine configuration
• System-level testing

Rule:

Develop UI on Windows. Build and test Linux features inside the VM.

---

Phase Roadmap

Phase 1 – Nebula OS (Controller Console Layer)

Objective: Build a polished, console-grade Game UI independent of store integration.

Deliverables:

• Lock screen with PIN keypad
• Home dashboard
• Library screen (mock data)
• Settings screen
• Power menu
• Controller navigation grid system
• Fullscreen window behavior

No external integrations yet.

---

Phase 2 – Session Integration

Objective: Make Nebula OS a selectable login session.

Milestones:

• Nebula Game UI appears at login
• Launches fullscreen
• Exiting returns to login
• Controller works reliably

---

Phase 3 – Nebula Library Foundations

Objective: Begin true replacement behavior.

Milestones:

• Launch local Linux games
• Integrate Proton/Wine execution layer
• Add SteamCMD support for installing Steam titles
• Track installed game metadata
• Unified library view

This is where Nebula begins diverging from SteamOS.

---

Phase 4 – Store Integrations

Objective: Add real backend integration without proprietary UI.

Potential directions:

• SteamCMD for Steam installs
• Legendary (Epic CLI) integration
• Heroic backend reuse (without UI dependency)
• OpenGOG community tools

Nebula Library becomes the single UI.

---

Security Strategy

Game UI lock screen:

• Local PIN authentication
• Optional profile system (future)

Linux account authentication remains system-level.

---

What Nebula OS Is Not

• Not a Steam skin
• Not Big Picture mode
• Not a launcher aggregator
• Not dependent on proprietary UIs

It is an open system layer that manages games directly.

---

Immediate Action Plan

1. Build Nebula OS UI on Windows
2. Implement controller navigation framework
3. Build lock screen system
4. Build Library UI skeleton
5. Set up Linux VM
6. Create Nebula Game UI login session
7. Begin local executable launching support
8. Research SteamCMD integration

---

Success Criteria for v0

Nebula OS v0 is successful when:

• You can log into Nebula Game UI
• The entire UI is controller navigable
• Lock screen works
• You can launch locally managed games
• You can return to Desktop Mode

From there, Nebula Library evolves into a true open source game management platform.