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_ui/           # HTTP server — serves WASM assets + RPC proxy
│   ├── hero_os_app/          # Dioxus desktop environment (web/mobile/desktop)
│   ├── hero_os_web/          # Bootstrap shell WASM UI (alternative)
│   └── hero_os_examples/     # Example programs using the SDK
├── schemas/                  # OSchema definitions
├── tests/                    # Playwright E2E tests
├── Makefile
└── buildenv.sh

Sockets

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

Service	Socket Path
hero_os_server	~/hero/var/sockets/hero_os_server.sock
hero_os_ui	~/hero/var/sockets/hero_os_ui.sock

Service Communication

Browser
  └─ hero_os_app (WASM, served by hero_os_ui)
       └─ /rpc/{context} → hero_os_ui (proxy)
            └─ Unix socket → hero_osis_server

hero_os CLI (--start/--stop)
  └─ hero_proc (process supervisor)
       ├─ hero_os_server (desktop state, OpenRPC)
       └─ hero_os_ui (HTTP + RPC proxy)

Running

Prerequisites: hero_proc_server must be running.

# Install and start all services
make install       # Build release binaries → ~/hero/bin/
make start         # Register and start via hero_proc

# Development
make installdev    # Build debug binaries → ~/hero/bin/
make run           # Start + stream logs (Ctrl-C to stop)
make web           # Dioxus dev server with hot reload

# Management
make stop          # Stop all services
make restart       # Stop + start
make status        # Show hero_proc status
make logs          # Server logs
make logs-ui       # UI logs

Full stack (dev)

# Terminal 0: hero_proc (if not already running)
hero_proc_server

# Terminal 1: Backend servers
make run

# Terminal 2: Frontend with hot reload
make web

Platforms

Platform	Command	Notes
Web	make web	Default, Dioxus dev server
iOS	make ios	Requires Xcode
Android	make android	Requires Android SDK
Desktop	make desktop	Native desktop app

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

make test          # Unit tests
make test-all      # Full test suite
make e2e           # Playwright E2E tests (local)
make e2e-remote    # E2E against live VM

Related Documentation

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