Overview
ryOS is a web-based desktop environment that brings the nostalgia of classic operating systems to modern browsers. Experience the charm of Mac OS X Aqua, System 7, Windows XP, and Windows 98—all running in your browser with 27 fully-functional apps, an AI assistant, and a complete virtual file system.
Whether you're exploring the retro aesthetics, building HTML applets, or chatting with Ryo (the AI assistant), ryOS offers a unique blend of nostalgia and modern web technology.
July 2026
Weather & location tools
Ryo fetches live forecasts and asks for precise location with an in-chat Allow / Don't Allow card.
See what's new →
July 2026
Save anywhere
Create root folders in Finder and save documents to any writable path across apps.
See what's new →
Quick Start
| I want to... | Go to |
|---|---|
| Learn about the apps | Apps Overview |
| Understand the architecture | Architecture |
| Understand the API layer | API Architecture |
| Build with the framework | Application Framework |
| Work with AI features | AI System |
| Use the APIs | API Reference |
Key Features
- Multi-Theme Support: system7/System 7, macosx/Aqua, xp/XP, win98/98
- Built-in Apps: Finder, TextEdit, Paint, iPod, Infinite Mac, Winamp, Calendar, Dashboard, Contacts, Maps, Books (EPUB reader), and more
- AI Assistant (Ryo): Chat, tool calling, app control, code generation
- Virtual File System: IndexedDB-backed with lazy loading and cloud sync
- Real-time Chat: RESTful rooms with AI integration
- Audio System: Synthesizer, soundboard, TTS, and UI sounds
- Component Library: shadcn/ui + custom components with i18n
- Cloud Sync: Journal-based Cloud Sync v2 with per-key documents, realtime sync ops, lazy legacy import, and S3-compatible blob storage
- Unified API Layer: Shared
apiHandler+ middleware utilities for consistent CORS, method routing, auth, and error handling - Usage Analytics: Lightweight per-day API analytics with admin dashboard
- Runtime Reliability & Performance: App/desktop error boundaries, typed app event bus primitives, lazy-loaded non-default locales, and worker-offloaded Spotlight indexing
Tech Stack
| Category | Technologies |
|---|---|
| Frontend | React 19, TypeScript, Tailwind CSS v4, shadcn/ui, Motion |
| State | Zustand with localStorage/IndexedDB persistence |
| Audio | Tone.js, WaveSurfer.js, Web Audio API |
| 3D | Three.js (shaders) |
| Text Editor | TipTap |
| Storage | IndexedDB, LocalStorage, Redis (Upstash REST / standard), S3 compatible object storage |
| API Runtime | Standalone Bun server (Node-style handlers) |
| AI | OpenAI, Anthropic, Google via Vercel AI SDK |
| Real-time | Pusher or local WebSocket (with Redis pub/sub fanout) |
| Package Manager | Bun ([email protected] in package.json; CI/Docker currently use Bun 1.3.9) |
| Build | Vite, Bun |
| Desktop | Electron + electron-builder (macOS and Windows release builds; Linux AppImage target configured) |
| Deployment | Docker / Coolify (standalone Bun server), Electron releases |
Project Structure
├── api/ # Node-style API endpoints (standalone Bun server)
│ └── _utils/ # Shared API utilities (api-handler, request-auth, redis, storage, realtime, analytics, etc.)
├── index.html # Vite entry / app shell
├── electron/ # Electron main/preload/menu/updater
├── public/ # Static assets
├── tests/ # bun:test suites
├── src/
│ ├── api/ # Frontend API clients (auth, rooms, admin, songs, listen, core, telegram, irc)
│ ├── apps/ # 27 app modules
│ ├── components/ # Shared React components
│ ├── config/ # App registry
│ ├── hooks/ # ~75 custom hooks
│ ├── lib/ # Libraries (including locales/)
│ ├── lib/locales/ # i18n translation files (11 languages)
│ ├── services/ # VFS and realtime service facades
│ ├── shared/ # Contracts, sync helpers, domain types
│ ├── stores/ # 40 Zustand store modules
│ ├── styles/ # CSS
│ ├── sync/ # Cloud Sync v2 client engine
│ ├── themes/ # 4 theme definitions
│ ├── types/ # TypeScript types
│ ├── utils/ # Utility functions
│ └── workers/ # Web workers
├── Dockerfile # Coolify / GHCR image
└── scripts/ # Build scripts