Desktop Application Shell (Electron)
Relevant source files
The following files were used as context for generating this wiki page:
The Coral Desktop Application Shell is an Electron-based host that supervises the local Coral ecosystem. It manages the coral runtime as a child process and the Reef web server as an Electron utility process. The shell provides a windowed interface for Reef while ensuring Coral services remain available in the background to serve agent clients via the Model Context Protocol (MCP).
Sources: apps/desktop/README.md:1-12, apps/desktop/src/main/index.ts:35-50
Process Architecture
The application operates using a multi-process architecture where the Electron Main process acts as a supervisor. It ensures both the Rust-based runtime and the Node.js Reef server are healthy and correctly networked.
Component Roles
| Component | Execution Context | Responsibility |
|---|---|---|
| Main Process | Electron Main | Supervises lifecycle, manages windows, and handles system integration (tray, updates). |
| Coral Runtime | Child Process | Executes core domain logic, manages the SQLite/Postgres database, and serves MCP. |
| Reef Server | Utility Process | Serves the web interface and API on a loopback address (127.0.0.1). |
Sources: apps/desktop/README.md:3-8, apps/desktop/src/main/index.ts:54-61
Lifecycle and Supervision
The Supervisor component manages the startup sequence and failure recovery. It monitors process exits and restarts components if they fail unexpectedly. If the runtime fails to start due to a locked state (exit code 75), the supervisor retries until it is ready or times out.
The supervisor uses a readiness timeout of 30 seconds for packaged builds and 120 seconds for development builds.
Sources: apps/desktop/README.md:36-45, apps/desktop/src/main/index.ts:25-27, apps/desktop/src/main/index.ts:60-61
Background Execution and System Integration
Coral continues to run after the user closes the last application window to maintain MCP availability for external clients.
Window Management and Dock Behavior
- Window Closing: Closing the last window keeps the processes running. On the first occurrence, the app displays a dialog explaining this behavior.
- macOS Dock: The application only appears in the Dock and app switcher when a window is open. When no windows are present, it resides solely in the menu bar.
- Login Autostart: Users can enable "Start at login," which launches the app with the
--backgroundargument to prevent the main window from appearing at startup.
Sources: apps/desktop/README.md:20-33, apps/desktop/src/main/index.ts:180-210
System Tray and Menus
The application provides a persistent tray icon (or menu bar item on macOS) that offers controls for opening the interface, toggling autostart, and quitting the application completely.
Networking and Configuration
All internal listeners bind to 127.0.0.1 to ensure local-only access.
Port Allocation
Desktop persists specific ports in desktop.json to maintain stable URLs for clients.
- Runtime MCP: Allocated on first launch; stable for agent clients.
- Reef: Allocated on first launch; stable for Run Status Page links.
- Runtime gRPC: Randomly picked at each launch for Reef-to-Runtime communication.
- OAuth Callback: Fixed at port 8779.
Sources: apps/desktop/README.md:14-23, apps/desktop/src/main/index.ts:54-61
Data Persistence
The shell manages a userData directory containing:
runtime/: Core state andcoral.db(SQLite).desktop.json: Port configurations and background notice flags.logs/: Separate log files forcoral,reef, anddesktop.
Sources: apps/desktop/README.md:120-130, apps/desktop/src/main/index.ts:47-52
Local Feedback Pages
When the application is starting or encounters a failure, it serves local HTML pages via data: URLs to provide user feedback.
| Page Kind | Purpose |
|---|---|
| Starting Page | Displays a spinner and the Coral mark while processes initialize. |
| Failure Page | Displays error details, such as "Port in use" or "State locked." |
The UI for these pages matches the Reef "SURFACE" colors (#F0F0F0 for light, #191919 for dark) to provide a seamless transition once Reef loads.
Sources: apps/desktop/src/main/local-pages.ts:7-35
Build and Security Configuration
The application is packaged using electron-builder with specific security "fuses" and platform requirements.
Electron Fuses
The configuration hardens the binary by disabling certain Node.js features:
runAsNode: falseenableNodeOptionsEnvironmentVariable: falseonlyLoadAppFromAsar: true
Sources: apps/desktop/electron-builder.config.ts:77-85
Code Signing and Notarization
- macOS: Requires
Hardened Runtimeandentitlements.mac.plistwith JIT support (required by V8). - Windows: Uses Azure Trusted Signing for binaries and installers.
- Linux: Produces AppImage targets (unsigned).
Sources: apps/desktop/electron-builder.config.ts:87-105, apps/desktop/electron-builder.config.ts:135-143