Skip to content

README.md

Latest commit

 

History

History
573 lines (399 loc) · 21.2 KB

README.md

File metadata and controls

573 lines (399 loc) · 21.2 KB

Samaris OS

SAMARIS OS

Mountain Lake — Alpha One

The Native WebOS

Bootable. Performant. Beautiful.
In your pocket.

🌐 Website · 📚 Documentation · 🚀 Quickstart · 🗺️ Roadmap · 📝 Changelog

License x86_64 Rust Kernel B Electron Shell Orbit AI Boot Time Built Solo

⚡ Public Alpha — a working, bootable Native WebOS prototype. VM-tested and booted on a Mac Mini Late 2012 in around 40 seconds. Ready for exploration.

🧠 Abstract

Samaris OS is a bootable operating system where the desktop experience is built entirely with web technologies — but runs as a first-class native environment inside a real OS, not inside a browser tab.

Linux underneath.
Web technologies on top.
Native OS behaviour in between.

This is not a website. Not a mockup. Not a Linux rice.

This is a working operating system that boots from a USB key, launches a full graphical desktop, runs native apps, connects to WiFi, persists sessions, and hosts a fully local AI assistant — all in around 5 GB for x86-64, or 10.68 GB for the universal x86-64 + ARM image.

And YES, it even runs DOOM.

📑 Table of Contents

🔥 What Is Samaris OS?

Samaris OS is a bootable operating environment that starts directly into a custom native desktop.

This is not a website.
Not a mockup.
Not a browser tab.
Not a Linux rice.

Samaris OS boots. It launches its own graphical experience. It runs a custom desktop shell. It opens apps. It manages windows. It persists sessions. It manages files. It runs system services. It talks to AI.

It behaves like a real operating environment.

Linux kernel → systemd → Node.js bridge → Rust accelerator → Electron shell → React desktop

Alpha One is the first public step.

🎬 Videos

Samaris OS Alpha One — Demo

Samaris OS Alpha One — Demo

Boot → desktop → apps → Orbit AI. See the full experience in action.


Samaris OS Alpha One — Proof of Boot

Samaris OS Alpha One — Proof of Boot

Mac Mini Late 2012 Intel · Boot → Onboarding → Desktop

🖼️ Screenshots

Samaris OS Desktop Samaris OS Lock Screen

The Samaris desktop and lock screen — fullscreen Electron shell with glass-design UI.

Finder Settings Orbit AI

Finder filesystem browser · System Settings · Orbit AI assistant

Peregrine Browser Photos Videos

Peregrine web browser · Photos · Videos player

Music Notes App Store

Music player · Notes · App Store with community apps

🌌 The Vision

Modern computing has become dependent on accounts, subscriptions, cloud lock-in, fragmented ecosystems, heavy desktop environments, and impersonal interfaces.

Samaris OS explores another direction.

A portable operating environment that boots from a USB key, opens into its own fullscreen desktop, keeps your session persistent across reboots, and gives you a beautiful, local-first workspace — all running on commodity hardware.

No mandatory cloud.
No forced account.
No telemetry-first design.
No bloated ecosystem.

Your desktop. Your files. Your apps. Your environment. In your pocket.

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────┐
│ LAYER 6: APPLICATIONS                                            │
│ 26 built-in apps · Wine · Orbit AI · Web Apps · jsdos            │
├──────────────────────────────────────────────────────────────────┤
│ LAYER 5: DESKTOP SHELL                                           │
│ Electron 28 · React 18 FSD · Window Manager · AirBar · Dock      │
├──────────────────────────────────────────────────────────────────┤
│ LAYER 4: KERNEL A — Node.js (:9999)                              │
│ 33 system services · WebSocket router · Auth · IPC · Volt Unifier│
├──────────────────────────────────────────────────────────────────┤
│ LAYER 3: VOLT RUNTIME — Rust Daemons (SBP binary protocol)       │
│ VRM (RAM) · VGM (GPU) · VUM (USB) · DWP (Scheduler) · ASC (HW)   │
│                         Tesseract Engine (Kernel B)              │
├──────────────────────────────────────────────────────────────────┤
│ LAYER 2: INIT & BOOT                                             │
│ systemd · Plymouth splash · OverlayFS · Live filesystem          │
├──────────────────────────────────────────────────────────────────┤
│ LAYER 1: DEBIAN TRIXIE BASE                                      │
│ Linux 6.12 · WiFi/BT/GPU firmware · X.Org · NetworkManager       │
└──────────────────────────────────────────────────────────────────┘

The operating system is built from a modular ISO pipeline:

debootstrap → Debian packages → module overlays → Rust daemons → Node.js kernel → Electron shell → React desktop

All compressed into a single SquashFS filesystem inside a bootable ISO.

Full architecture documentation →

✨ Key Capabilities

🚀 1. Native Boot — Real OS, Real Hardware

From a USB key or ISO, Samaris boots directly into its own fullscreen desktop.

No cloud streaming.
No virtual machine required.
No browser dependency.

The live filesystem uses OverlayFS for persistence, allowing the user session to survive reboots.

Boot time: around 47 seconds in QEMU
Hardware boot: around 40 seconds on Mac Mini Late 2012 Intel

🧬 2. Dual-Kernel Architecture

Kernel Language Role
Kernel A Node.js Central WebSocket server on :9999; manages filesystem, WiFi, Bluetooth, audio, battery, AI, sessions, permissions, encryption, firewall, mail, printing, and more
Kernel B Rust Native acceleration daemon; SBP v5 binary protocol, priority scheduler, thermal watchdog, GPU canvas, compute bridge, and security sandbox

The two kernels communicate through Volt Unifier, which bridges desktop events to SBP binary messages through bridge modules and IPC clients.

Kernel A → · Kernel B → · Volt Unifier →

🦀 3. Six Native Rust Daemons

Every major system resource is managed by a dedicated Rust daemon communicating through the SBP binary protocol.

Daemon Role Key Features
VRM RAM Manager 3-tier memory, ZSTD + LZ4 compression, SHA-256 deduplication, pressure zones
VGM GPU Manager Wgpu, Vulkan, Metal backends, VRAM tiering, shader cache, thermal watchdog
VUM USB Manager RAM-first FUSE filesystem, WAL journal, CRC32, I/O scheduler, safe eject
DWP Worker Pool Adaptive priority scheduler, 5 priority levels, desktop frame guard, Orbit burst control
ASC Adaptive Config Hardware detection at boot, policy compiler, daemon configuration generation
VDM Display Manager xrandr-based detection, hotplug, rollback, safe mode, HiDPI scaling

All daemons → · SBP Protocol →

🖥️ 4. Desktop Shell — Electron + React 18

The desktop is a fullscreen React application rendered by Electron.

It provides:

  • 🪟 Window Manager — z-order, resizing, snapping, animations, close guards
  • 🧭 Dock — application launcher with running indicators
  • 📡 AirBar — system status panel for clock, WiFi, battery, and volume
  • 🔎 Spotlight Search — Cmd/Ctrl + Space global search
  • 🎨 Theme System — light/dark mode, accent colours, density, font scale
  • 🗂️ Desktop Icons — draggable organised grid
  • 🔒 Lock Screen — authentication overlay

Desktop architecture → · UI architecture → · Window system →

💾 5. Session Persistence

All user data survives reboots:

  • files
  • settings
  • app state
  • credentials
  • session metadata

The live system uses an OverlayFS filesystem, while sessions are tracked by sessionFeaturesService.

Encrypted user storage is managed through:

.volt/users/

📦 Built-in Applications

26 applications ship with Alpha One, organised into four categories.

🧰 System & Desktop

App App App App App
Finder Terminal Settings App Store Notes
Text Editor Downloads Trash Utilities About

🌐 Network & Security

App App App App
Network Firewall Encryption Permissions Manager

🎵 Media & Productivity

App App App App
Music Photos Videos PDF Viewer
Mail Archive Peregrine Browser Orbit AI

🕹️ Compatibility

App Description
Wine Launcher Windows compatibility layer
DOOM Runs through jsdos

📦 App Store & Wine — Extend Samaris OS

🛒 Samaris App Store

The App Store is the simplest way to grow your system. It connects directly to GitHub repositories that publish Samaris-compatible apps.

  • One-click install from the store interface
  • Community-driven — anyone can host an app on GitHub
  • No terminal, no dependency hunting — the store handles cloning, building, and integration
  • Fast iteration — install apps as quickly as you would preview a React component

The store lists categories such as utilities, media, developer tools, and games. Future versions will support automatic updates.

🍷 Wine — Windows Compatibility

Wine is integrated at the system level, allowing Samaris OS to run Windows .exe applications alongside native Samaris apps.

  • Launch .exe files directly from Finder or the terminal
  • Seamless window management — Windows apps resize, snap, and focus like native apps
  • No virtual machine required — Wine runs natively on Samaris OS
  • Compatibility with classic and productivity apps — older Windows software, utilities, and some games

💡 Note: Wine is a compatibility layer, not an emulator. Performance and compatibility vary by application.

Why both?

System Purpose
App Store Fast, safe, community-built apps
Wine Compatibility with existing Windows software

Together, they make Samaris OS a practical daily environment for exploration without locking the user into a single ecosystem.

App Store docs → · Wine launcher docs → · Adding an app to the store →

🧠 Orbit AI — Your Local Brain

No cloud. No accounts. No telemetry. No phone-home.

Samaris ships with a complete local AI stack running entirely on your hardware, powered by llama.cpp with GPU acceleration through Metal, CUDA, or Vulkan.

Model Size Purpose
Qwen3-1.7B-Q8_0.gguf 1.7 GB LLM — conversation, reasoning, code
ggml-small.bin 465 MB Speech-to-text with Whisper
OuteTTS-0.2-500M-Q8_0.gguf 512 MB Text-to-speech
WavTokenizer-Large-75-F16.gguf 124 MB Audio vocoder

Voice Mode

Press mic → speak → Whisper transcribes → Qwen3 generates → OuteTTS speaks → loop

Orbit can be interrupted mid-sentence. It stops and responds.

Orbit can be summoned with:

Cmd/Ctrl + Space

It operates with burst priority through the DWP scheduler — a dedicated 100 ms window with 75% worker reservation ensures responsive AI even under load.

Orbit AI docs → · AI Stack →

📊 Performance

Metric Value
Boot time in QEMU 47.0s
Kernel boot 7.99s
Userspace boot 39.05s
graphical.target 38.4s
Memory at idle ~715 MB / 7.8 GB
Available RAM 7.1 GB
Kernel panics 0
Failed units 0
Active VOLT services 9
x86-64 FULL ISO 5.1 GB
SquashFS filesystem 4.88 GB
Universal ISO 10.68 GB

Full benchmark report → · ISO size breakdown →

⬇️ Download

Two ISO variants · Free · No account · No telemetry

Variant Architecture Size Download Description
Samaris OS Alpha One RC — x86_64 FULL x86_64 5.1 GB Download ISO Full desktop experience for Intel/AMD systems with Orbit AI, 26 applications, Electron desktop shell, and 9 native Rust daemons
Samaris OS Alpha One RC — Universal x86_64 + aarch64 10.68 GB Download ISO Dual-architecture release containing both Intel/AMD and ARM64 root filesystems in a single bootable image

Official Website →

ℹ️ The Universal ISO includes two complete SquashFS root filesystems: one for x86_64 and one for aarch64, allowing the same image to boot on both Intel/AMD and ARM64 systems.

🧪 Try It

1. Download

Get the ISO from:

https://samaris.tech

2. Run in QEMU or a Virtual Machine

qemu-system-x86_64 \
  -m 4096 \
  -smp 4 \
  -cdrom Samaris-OS-Alpha-One-RC.iso \
  -vga virtio \
  -display cocoa

3. Explore

  • 🖥️ Desktop — fullscreen shell, dock, window management
  • 🗂️ Finder — filesystem browser
  • ⚙️ Settings — theme, appearance, security
  • 🧠 Orbit AI — Cmd/Ctrl + Space to launch the assistant
  • 🦅 Peregrine — built-in web browser
  • 🛒 App Store — install apps from GitHub

System Requirements

Component Minimum
CPU 2 cores, x86_64
RAM 4 GB
Storage 16 GB
GPU Intel HD or basic GPU

Quickstart → · Installing the ISO → · First Boot →

❌ What Samaris OS Is Not

Samaris OS Alpha One is:

  • not a finished OS
  • not a Windows replacement
  • not a macOS replacement
  • not a daily-driver recommendation
  • not production-ready
  • not hardware-certified
  • not a traditional Linux desktop distribution It is a serious experimental operating system prototype.

⚠️ Known Issues (Alpha One)

  • WiFi: works on some hardware, not all. Firmware missing for certain chips.
  • App Store: works with standard React/Vite GitHub repos. Edge cases in progress.
  • Wine: present but not extensively tested.
  • Peregrine downloads: occasional bugs under investigation.

Alpha Two will address all of the above. And more.

👨‍💻 Built By

Khaled Ben Taieb — OS Architect

  • PharmD, MBA
  • Built solo
  • Zero budget
  • AI-assisted development
  • Built in around 1 month
  • Development machine: MacBook Air M3

"Computers are supposed to be fun. That's why I made you this OS; it's tailored to your taste. Love you, dad."

⚖️ License

Samaris OS — Copyright © 2026 Khaled Ben Taieb

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Upstream open-source components — Linux kernel, GRUB, Chromium, Node.js, React, systemd, Electron, and others — retain their respective licenses (GPLv2, MIT, Apache 2.0, BSD, etc.).

samaris.tech · GitHub · contact.samaris.os@gmail.com

Some OSes manage windows. Samaris reimagines them.

Samaris OS — The Native WebOS
Boot it. Build the future with it.

Copyright © 2026 Khaled Ben Taieb