Hero OS

A desktop environment framework built with Dioxus (Rust → WASM) that serves as the host for Hero Archipelago islands. Provides macOS-style window management, context switching, and theming for dynamically loaded WASM applications.

Architecture

hero_os/
├── crates/
│ ├── hero_os/ # CLI — registers services with hero_proc
│ ├── hero_os_server/ # OpenRPC state server (desktop state, windows, layout)
│ ├── hero_os_sdk/ # Type-safe async Rust SDK client
│ ├── hero_os_admin/ # HTTP server — serves WASM assets over admin.sock
│ ├── hero_os_app/ # Dioxus desktop environment (web/mobile/desktop)
│ └── hero_os_examples/ # Example programs using the SDK
├── schemas/ # OSchema definitions
└── tests/ # Playwright E2E tests

Sockets

All services use Unix domain sockets exclusively (no TCP ports).

Service	Socket Path
hero_os_server	$PATH_SOCKET/hero_os/rpc.sock
hero_os_admin	$PATH_SOCKET/hero_os/admin.sock

Service Communication

Browser
 └─ hero_os_app (WASM, served by hero_os_admin)
 └─ hero_router → /hero_osis_<domain>/rpc → per-domain RPC sockets

hero_os CLI (--start/--stop)
 └─ hero_proc (process supervisor)
 ├─ hero_os_server (desktop state, OpenRPC)
 └─ hero_os_admin (HTTP asset server)

Running

Prerequisites: hero_proc_server must be running.

Via nushell (recommended)

service os start --update --reset
service os stop
service os status

Frontend dev (hot reload)

cd crates/hero_os_app
env -u RUSTC_WRAPPER dx serve --platform web

Key Concepts

Contexts

A context is a workspace/namespace that isolates data (e.g., herozero, geomind). Each context has its own desktop state and theme.

Themes

A theme defines visual appearance (colors, typography, spacing). Stored in the backend, referenced by context.

Islands

Islands are self-contained WASM applications loaded as web components from Hero Archipelagos. Each island registers as a custom HTML element, receives configuration via attributes, and makes API calls to the backend.

Testing

cargo test --workspace

Playwright E2E specs live under tests/.

Related Documentation

Document	Purpose
docs/ARCHITECTURE.md	Detailed system architecture
docs/ANDROID.md	Android/Volla OS setup
docs/MOBILE.md	Mobile layout and sizing
docs/DIOXUS.md	Dioxus configuration