Orion OS — Developer Handbook

1. Introduction

Orion OS is a minimal, modular, AI-oriented Linux desktop built to be:

• Fast — small init, predictable boot, localhost-first services
• Understandable — thin layers: kernel, init, compositor, session, apps
• Extensible — catalog-driven apps, YAML profiles, JSON-RPC SAL
• Self-hosting-friendly — developer edition can carry tooling for building the OS
• AI-friendly — intent routing and a pluggable AI backend (HTTP)

The shipping stack uses Alpine Linux userland, a custom shell init (init/init.sh installed as /init), Weston (Wayland compositor), and Rust binaries for services and applications. Control and introspection go through SAL (System Abstraction Layer) over JSON-RPC on HTTP.

2. System architecture

Layers from hardware upward:

Hardware
  → Linux kernel (Alpine linux-lts in shipped images)
  → PID 1: init/init.sh (/init)
  → udev, seatd, optional Windows compat daemon, net-status, update-checker
  → Weston (DRM/fbdev) or compositor-watchdog wrapper
  → devtoolsd → SAL (sal-backend-linux) → ai-backend (+ ai-shell), background-loader
  → First-boot flow OR session-launcher → Hub / AI UI / catalog apps

Compositor path. By default init tries compositor-watchdog when USE_COMPOSITOR_WATCHDOG is non-zero and the binary exists; otherwise it starts Weston directly (MYO_COMPOSITOR_BACKEND: auto, fbdev, or drm).

Service pattern. Long-running components are started as background processes from init, with logs under /var/log/myo/services/<name>.log.

Workspace layout (this repository).

3. Boot and init

3.1 Sequence

1. Firmware loads the kernel (installed image or live media).
2. Kernel runs /init (copy of init/init.sh).
3. Init mounts essential filesystems, prepares XDG_RUNTIME_DIR, starts udev and seatd.
4. Optional net-start (firewall / NetworkManager baseline).
5. Compositor (Weston or watchdog).
6. devtoolsd (before SAL, for dev tool forwarding).
7. SAL, ai-backend (loop with optional reload on exit 75), ai-shell, background-loader.
8. If /etc/myo/firstboot-done is missing: first-bootd then first-boot UI; otherwise session-launcher after Wayland is ready.
9. Init stays alive in a sleep loop (PID 1).

3.2 Important environment variables

Documented in the header of init/init.sh. Highlights:

4. Editions

Two editions drive UX and optional tooling:

The active edition is stored in /etc/myo/edition (values user or developer). Image build scripts set this via staging (assemble-rootfs.sh).

5. Core services

Representative services (Rust daemons under services/):

Most speak HTTP on localhost; SAL uses JSON-RPC POST on /rpc (and /).

6. Application model

• Apps are Rust crates under apps/<name>/ (see workspace Cargo.toml members).
• Ship as ELF binaries installed to /usr/bin in the rootfs (via assemble-rootfs.sh).
• UIs use WebView or native stacks as implemented per app.
• Discovery happens through catalog/apps.yaml and the Internet Hub (hub.yaml).

Adding an app means: implement the crate, list it in the workspace, ensure the binary is staged by assemble-rootfs.sh, add a catalog entry, and optionally Hub tiles and AI intents.

7. Catalog and Internet Hub

Catalog (catalog/apps.yaml)

Each app entry commonly includes:

• id, name, description
• command — binary name on $PATH (older docs said binary; this repo uses command in YAML)
• tags — categories / filters
• install, hidden, autostart
• download_behavior — e.g. mode: process vs open_webpage with url

Categories may be listed in catalog/categories.yaml.

Internet Hub

The Hub resolves tiles and sections from internet-hub/hub.yaml (and related assets). Catalog entries tie apps to user-visible launchers; the Hub organizes high-level navigation (system tiles, external links, etc.).

8. AI layer

• Intent router: ai/backend/src/intent.rs maps natural phrases to SAL actions (e.g. start process, SAL calls). Extend phrases for synonyms; keep help strings accurate.
• Backend: Axum HTTP server; default listen 127.0.0.1:8787 (AI_LISTEN). POST /prompt is the integration seam (placeholder semantics as of this handbook).
• UI: ai-ui connects users to the backend.

When adding a feature reachable by voice/text, update intents, catalog, and any Hub entry together so discovery stays coherent.

9. SAL overview

SAL is implemented by sal-backend-linux (crate sal-linux).

• Transport: HTTP POST JSON-RPC to http://127.0.0.1:8750/rpc by default (SAL_LISTEN).
• Semantics: Methods are namespaced strings such as sal.system.ping, sal.process.start, sal.network.status.
• Safety: Mutations that touch disks, packages, kernel modules, or power policy require SAL_DANGEROUS=1 in the environment; otherwise structured blocked responses are returned (see Milestone 4 rules in repo).
• Process and profiles: sal.profiles.*, sal.process.*, sal.services.* integrate with the profile loader and init expectations.

Full method list and request shapes are in Appendix A.

10. First-boot experience

Components

• first-bootd — Axum server on FIRST_BOOTD_LISTEN (default 127.0.0.1:8793), localhost-only.
• first-boot — WebView (or embedded UI) calling that API; FIRST_BOOTD_URL tells the UI where to connect.

Completion marker: /etc/myo/firstboot-done. After it exists, init skips the wizard and starts session-launcher (when Wayland and paths are valid).

Extending the wizard: evolve the first-bootd state machine and matching UI screens; keep endpoints documented in Appendix A.

11. Developing applications

1. Create apps/<name>/ with Cargo.toml and src/main.rs.
2. Register the crate in the workspace root Cargo.toml.
3. Ensure assemble-rootfs.sh copies the binary (see its for b in … list).
4. Add catalog/apps.yaml entry (command matches the installed binary name).
5. Optional: internet-hub/hub.yaml tile; ai/backend/src/intent.rs phrases.

Quality bar: small binaries, explicit errors, respect edition if behavior differs.

12. Developing services

1. Create services/<name>/ with Axum or minimal event loop as needed.
2. Expose a clear localhost HTTP API if other components must call it.
3. Wire startup in init/init.sh via start_bg <logical-name> <binary> … (follow existing patterns; keep logs under /var/log/myo/services/).
4. Documentendpoints beside the crate or in this handbook's appendix if stable.

Guidelines: bounded timeouts, structured JSON responses, no unnecessary global state.

13. Profiles and background loader

• Profiles: YAML under profiles/ (installed to PROFILES_DIR, default /usr/share/myo/profiles).
• Boot profile: BOOT_PROFILE (default minimal) passed to background-loader, which calls sal.profiles.apply over SAL_URL.
• LOADER_REAL_APPLY: when set, loader may perform real package/service operations from the profile (subject to SAL_DANGEROUS gates).

Use profiles to describe “what should be true” after boot without hard-coding every sequence in init.

14. Edition-aware development

Read /etc/myo/edition at runtime:

let edition = std::fs::read_to_string("/etc/myo/edition")?;
if edition.trim() == "developer" {
    // dev-only menus, shortcuts, or SAL paths
}

Avoid baking edition checks into shared libraries unless necessary; prefer feature flags at the app boundary.

15. Debugging and logs

Use the log-viewer app on device. On failure, init prints fallback messages to the configured TTY (MYO_STATUS_TTY, default /dev/tty1) listing useful paths and ps/tail hints.

Host development: scripts/run-dev.sh / scripts/run-dev.ps1 coordinate SAL + loader + AI for local iteration (see script headers).

16. Build and release images

Shipping bootable .raw and .iso is Linux-centric (chroot, grub-install, losetup, …).

• Quick reference: build/SHIP.txt, build/build-prerequisites
• One-shot (Linux): ./build/scripts/build-images.sh [user|developer]
• Docker: Dockerfile.ship + docker-ship.sh (privileged) with build/in/bin mounted

Windows checkout: use WSL2, Docker, or a Linux VM to produce images; native Windows Rust is fine for cargo check of crates but not for full image builds.

Cross-target binaries: build/scripts/build-linux-musl-release.sh (Docker-based musl builds including GUI crates by default).

17. Installer

The installer lives under build/installer/ and targets installation from live media: disk selection, edition, rootfs copy, bootloader setup, reboot. See installer scripts and build/SHIP.txt for install-to-disk.sh usage.

18. Contributing

• Rust 2021, workspace rustfmt consistency where applicable
• Prefer small focused binaries and clear HTTP/JSON contracts
• New user-visible surfaces: update catalog, Hub, and intents together
• Security: never widen SAL_DANGEROUS defaults; document risky flags in init.sh
• PRs should state what changed and how to verify (cargo check, image smoke, manual step)

19. Roadmap themes

Exact milestones live in repo plans and .cursor/rules; treat this table as directional.