Hero OS

A web-based operating system with a macOS-inspired interface, built with Rust and Bootstrap 5.

Features

• macOS-like Interface: Clean, minimal design with dark mode as default
• Window Management: Draggable, resizable windows with minimize/maximize/close controls
• Dock: Quick app launcher with active indicators
• Start Menu: Searchable app menu with theme toggle
• Proxy Server: Bypass X-Frame-Options for embedding external sites

Quick Start

# Build and run
make run

# Open in browser
open http://127.0.0.1:6438

Applications

Built-in Apps (No External Dependencies)

These apps are fully implemented within Hero OS and work out of the box:

App	Description
Browser	Web browser with proxy support for external sites
Calendar	Monthly/daily calendar view with events
Contacts	Contact management with search
Tasks	Task list with priorities
AI Assistant	Chat interface (mockup)

External Apps (Require Running Services)

These apps embed external services via iframe. You must start these services separately for them to work.

App	URL	Proxy	Description
Hero Editor	http://0.0.0.0:2769	No	Code editor
Hero Embedder	http://127.0.0.1:3752	No	Context embedding tool
Hero Voice	http://localhost:2756	No	Voice transcription
Hero Books	http://127.0.0.1:9567	Yes	Digital library with search
Hero Admin	http://127.0.0.1:3521	No	System administration

Proxy System

Hero OS includes a built-in HTTP proxy (/proxy?url=...) to bypass X-Frame-Options and CSP headers that prevent iframe embedding.

How Proxy Works

1. Automatic for Browser App: The built-in browser proxies all external URLs
2. Optional for Local Apps: Local apps (localhost, 127.0.0.1) are NOT proxied by default
3. Force Proxy: Set force_proxy = true in config for apps that need it (e.g., Hero Books)

What Gets Rewritten

The proxy rewrites URLs in:

• HTML attributes: src, href, action, srcset
• CSS: url() references
• JavaScript: ES module imports (from "./file.js", import("./file.js"))

Configuration

Edit config.toml to customize apps and settings:

[server]
host = "127.0.0.1"
port = 6438

[theme]
mode = "dark"
accent_color = "#007AFF"

[[apps]]
id = "my-app"
name = "My App"
icon = "star"           # Bootstrap Icons name
url = "http://localhost:3000/"
category = "productivity"
resizable = true
default_width = 800
default_height = 600
force_proxy = false     # Set true to force proxy even for local URLs

App Configuration Options

Option	Type	Description
id	string	Unique identifier
name	string	Display name
icon	string	Bootstrap Icons name (without bi- prefix)
url	string	URL to embed (omit for built-in apps)
builtin	bool	True for built-in apps (Browser, Calendar, etc.)
category	string	App category for organization
resizable	bool	Allow window resizing
default_width	int	Default window width in pixels
default_height	int	Default window height in pixels
force_proxy	bool	Force proxy even for local URLs

Starting External Services

Before using external apps, start their respective services:

# Example: Start Hero Editor on port 2769
cd /path/to/hero-editor && cargo run

# Example: Start Hero Books on port 9567
cd /path/to/hero-books && cargo run

# Then start Hero OS
cd /path/to/hero_os && make run

Project Structure

hero_os/
├── Cargo.toml           # Rust dependencies
├── config.toml          # App configuration
├── Makefile             # Build commands
├── src/
│   └── main.rs          # Axum server with proxy
├── templates/
│   └── index.html       # Askama HTML template
└── static/
    ├── icons/
    │   └── hero-os.svg  # App icon/favicon
    ├── css/
    │   └── hero-os.css  # macOS-inspired styles
    └── js/
        ├── window-manager.js  # Window drag/resize/focus
        └── apps.js            # Built-in app implementations

Development

make check    # Check compilation
make fmt      # Format code
make clippy   # Run linter
make verify   # Run all checks
make watch    # Watch for changes

Keyboard Shortcuts

Shortcut	Action
Cmd/Ctrl + W	Close active window
Cmd/Ctrl + M	Minimize active window

Requirements

• Rust 1.92+
• External services for integrated apps (optional)

License

MIT