Orion OS — Technical Overview (v1 Architecture)

1. Purpose & Vision

Orion OS is a lightweight, modern operating system designed to:

• Boot fast
• Provide a simple, unified application environment
• Integrate AI deeply into the user experience
• Support both user-friendly and developer-friendly editions
• Allow the OS to develop itself from within (self-hosting)
• Be packaged as a UEFI-bootable ISO with a first-boot wizard

It is intentionally minimal, modular, and easy to extend.

2. Target Platform (v1)

• Architecture: x86_64
• Firmware: UEFI only
• Boot milestone: QEMU disk image → USB-bootable ISO
• Base system: Alpine Linux minimal rootfs
• Kernel: Alpine-provided kernel artifact (vendored into build/)
• Init: Custom init.sh as PID 1 (no systemd/OpenRC)

This keeps the system small, predictable, and easy to reason about.

3. Root Filesystem Layout

The rootfs includes:

Core binaries

• ai-backend (AI HTTP server)
• ai-ui (WebView wrapper for AI backend)
• internet-hub
• doc-editor
• image-editor
• custom-browser
• terminal (wrapper around real terminal emulator)
• first-boot (UI)
• first-bootd (daemon)
• about, settings, log-viewer

Core services

• net-status (network health)
• update-checker (metadata only)
• compositor-watchdog (fallback UI trigger)
• first-bootd (wizard backend)

Configuration

• /etc/myo/edition (developer | user)
• /etc/myo/theme
• /etc/myo/user
• /etc/myo/firstboot-done

Developer workspace

• Developer edition: /home/user/src/os (empty tree + first-boot clone)
• User edition: omitted

4. Editions (Runtime-Selectable)

A single rootfs supports two modes:

Developer Edition

• Dev tools profile installed (git, build tools, rust, code wrapper)
• Workspace present
• Hub shows Development section
• AI intents include:
  • open dev terminal
  • open os workspace
  • open editor
  • open source

User Edition

• No dev tools
• No workspace
• Hub hides development tiles
• AI intents limited to user-facing apps

Edition is determined by /etc/myo/edition.

5. Boot Sequence

1. Kernel loads
2. init.sh starts
3. Core services start:
   • net-status
   • update-checker
   • compositor-watchdog
   • ai-backend
4. If /etc/myo/firstboot-done missing:
   • start compositor
   • start first-bootd
   • start first-boot UI
5. Otherwise:
   • start compositor
   • start session-launcher
   • session-launcher opens Hub or AI UI depending on edition

This keeps boot fast and predictable.

6. First-Boot Wizard

Two-component design

• first-bootd (daemon)
• first-boot (UI)

API (localhost only)

• POST /set-edition → { "edition": "developer" | "user" }
• POST /set-username → { "username": "..." }
• POST /finish → { "theme": "light" | "dark" }
• GET /state → returns wizard progress + partial values

Security

• Binds to 127.0.0.1
• Port via FIRST_BOOTD_LISTEN
• Validates username + edition enum
• Exits after /finish

7. Catalog-Driven Application Model

Apps are defined in catalog/apps.yaml.

AppEntry fields

• id
• name
• binary
• category
• description
• install
• hidden (optional)
• autostart (optional)
• download_behavior (package | process)

New system apps added

• about
• settings
• log-viewer
• first-boot (hidden, not hub-visible)

Install semantics

• install: true + download_behavior.mode: process → ship binary in rootfs
• install: true + download_behavior.mode: package → SAL installs package

8. Hub Integration

Hub reads catalog entries and edition flag.

System section

• About
• Settings
• Log Viewer

Developer section (developer edition only)

• OS Workspace
• Dev Terminal

Hub tiles resolve by catalog id, not hardcoded commands.

9. AI Intent System

A unified table in ai/backend/src/intent.rs defines:

• phrases (exact match)
• normalized form
• mapped SAL action
• help text

System intents

• help
• ping
• network status
• power
• gpu
• packages

App intents

• open ai
• chat
• open browser / browse / open web
• open internet hub
• open doc editor
• open image editor
• write a document
• draw something

System polish intents

• about
• open settings
• open logs / log viewer

Developer intents

• open dev terminal
• open os workspace
• open editor
• open source

10. Networking

net-status service

• Localhost HTTP server
• Checks:
  • IP presence
  • DNS
  • HTTP reachability
• SAL augments sal.network.status with these fields
• Never blocks boot (short timeouts)

11. Update Checker

• Periodic metadata fetch
• Writes /var/lib/myo/update-status.json
• No auto-update logic in v1
• Hub Settings can show update status

12. Compositor Fallback Mode

• compositor-watchdog monitors compositor
• On failure:
  • logs error
  • launches fallback UI or emergency shell
• Ensures system remains usable even if graphics fail

13. Installer (v1)

• Linux-only installer running inside live ISO
• TUI interface
• Steps:
  • Choose disk
  • Choose edition
  • Install rootfs
  • Install bootloader
  • Reboot

14. Build Pipeline

Directory structure

Code
build/
  rootfs/
  iso/
  installer/
  profiles/
  scripts/

Pipeline outputs

• Rootfs image
• Kernel + bootloader config
• UEFI-bootable ISO
• Installer environment

15. Extensibility

Developers can build on Orion OS by:

• Adding new apps to catalog/apps.yaml
• Adding new intents to the unified table
• Adding new services under services/
• Adding new UI apps under apps/
• Extending Hub sections
• Adding new profiles to SAL
• Adding new first-boot steps
• Adding new update channels

The system is intentionally modular and easy to extend.