Desktop Host (Electron)

Relevant source files

• apps/desktop/build/entitlements.mac.plist
• apps/desktop/build/icon.png
• apps/desktop/electron-builder.config.ts
• apps/desktop/scripts/build-sidecar.ts
• apps/desktop/src/main/crash-screen.ts
• apps/desktop/src/main/index.ts
• apps/desktop/src/main/reset-state.ts
• apps/desktop/src/main/service.ts
• apps/desktop/src/main/settings.ts
• apps/desktop/src/main/sidecar.ts
• apps/desktop/src/main/updater-state.test.ts
• apps/desktop/src/main/updater-state.ts
• apps/desktop/src/preload/index.ts
• apps/desktop/src/shared/server-settings.ts
• apps/desktop/src/shared/update.ts
• apps/desktop/src/sidecar/server.ts
• e2e/AGENTS.md
• e2e/desktop-packaged/stale-launchd-registration.test.ts
• e2e/desktop-vm/console-renders.test.ts
• e2e/desktop/reset-state.test.ts
• e2e/recordings/stale-launchd-fast-boot.mp4
• e2e/scripts/cli.ts
• e2e/scripts/verify-linux-desktop-attach.ts
• e2e/selfhost/detected-auth-immutable-ui.test.ts
• e2e/setup/desktop-linux.globalsetup.ts
• e2e/setup/desktop-macos.globalsetup.ts
• e2e/setup/desktop-vm.ts
• e2e/setup/desktop-windows.globalsetup.ts
• packages/plugins/desktop-settings/src/client.tsx
• packages/plugins/desktop-settings/src/server.test.ts
• packages/plugins/desktop-settings/src/server.ts
• packages/react/src/api/server-profiles.test.ts
• packages/react/src/components/update-card.tsx
• packages/react/src/hooks/desktop-update.ts

The Desktop Host is an Electron-based wrapper for the Executor platform. It bundles the core SDK, a React-based frontend, and a production-grade CLI binary to provide a local-first, native experience. Its primary responsibilities include managing the lifecycle of the local server (Sidecar), supervising background daemons for persistent MCP access, handling auto-updates, and providing diagnostic tools for troubleshooting.

1. Process Architecture

The application follows a standard Electron multi-process model, but introduces a third tier: the Sidecar.

• Main Process: Manages window lifecycle, system menus, auto-updates, and supervises the Sidecar process.
• Renderer Process: Displays the React-based Console UI, communicating with the Main process via a secure IPC bridge.
• Sidecar Process: A standalone instance of the Executor server (bundled CLI binary) that provides the actual API and Tool execution environment.

Data Flow: Process Interaction

The following diagram illustrates how the Electron Main process orchestrates the startup and connection between the UI and the local server.

Diagram: Desktop Process Orchestration

Sources: apps/desktop/src/main/index.ts90-104 apps/desktop/src/main/sidecar.ts4-11 apps/desktop/src/preload/index.ts10-116

---

2. Sidecar Lifecycle & Supervised Daemon

The application manages two types of local server connections defined in SidecarConnection apps/desktop/src/main/sidecar.ts65-85:

1. Managed Sidecar: A child process spawned directly by Electron using spawn apps/desktop/src/main/sidecar.ts199-228 It is terminated when the app quits.
2. Supervised Daemon: A persistent background service (e.g., launchd on macOS or systemd on Linux) that outlives the desktop window. This ensures MCP tools remain available to AI clients even if the UI is closed apps/desktop/src/main/sidecar.ts76-81

Service Management

The service.ts module interfaces with the bundled CLI to control these background daemons:

• installSupervisedService: Shells out to executor install to register the OS-level service apps/desktop/src/main/service.ts126-137
• supervisedServiceStatus: Checks if the daemon is registered and running by parsing the output of executor service status apps/desktop/src/main/service.ts107-124

Sources: apps/desktop/src/main/sidecar.ts65-85 apps/desktop/src/main/service.ts13-25 apps/desktop/src/main/service.ts107-161

---

3. IPC Bridge and Settings Plugin

The preload/index.ts file defines the ExecutorBridge, which exposes a limited set of Main process functions to the React frontend via contextBridge.exposeInMainWorld("executor", api) apps/desktop/src/preload/index.ts118

Desktop Settings

Settings like the server port are persisted using electron-store in settings.ts apps/desktop/src/main/settings.ts1-16 The application also includes a dedicated desktop-settings plugin that allows users to:

• Change the local server port apps/desktop/src/main/settings.ts29-35
• Rotate the local auth token (via rotateLocalAuthToken) apps/desktop/src/main/settings.ts42
• Export diagnostic bundles for support apps/desktop/src/preload/index.ts65-67

Sources: apps/desktop/src/preload/index.ts1-120 apps/desktop/src/main/settings.ts1-49

---

4. Auto-Updater and Recovery

The host uses electron-updater for background updates. The state machine in updater-state.ts tracks transitions from checking to downloaded apps/desktop/src/main/updater-state.ts

Crash Screen

If the Sidecar fails to start or exits unexpectedly, the Main process replaces the web UI with a native-looking "Crash Screen" apps/desktop/src/main/crash-screen.ts1-7 This screen is a data: URL that retains access to the IPC bridge, allowing users to:

• Restart Server: Attempts to re-spawn the sidecar apps/desktop/src/main/crash-screen.ts172-180
• Check for Updates: Triggers a manual update check to heal a broken installation apps/desktop/src/main/crash-screen.ts181-190
• Reset Data: A last-resort recovery that moves the existing .executor data directory to a backup location and starts fresh apps/desktop/src/main/reset-state.ts46-47

Sources: apps/desktop/src/main/index.ts18-20 apps/desktop/src/main/crash-screen.ts112-169 apps/desktop/src/main/reset-state.ts1-50

---

5. Packaging and Bundling

The desktop app is packaged using electron-builder. A critical step in the build pipeline is staging the sidecar binary.

Sidecar Bundling

The script scripts/build-sidecar.ts compiles the apps/cli package into a standalone binary and copies it into the Electron resources/executor directory apps/desktop/scripts/build-sidecar.ts1-15 This ensures the Desktop app always has a compatible version of the execution engine.

Configuration

The electron-builder.config.ts handles:

• Extra Resources: Including the bundled CLI binary apps/desktop/electron-builder.config.ts15-21
• Notarization: Automatic macOS notarization using Apple API keys apps/desktop/electron-builder.config.ts32-40
• Multi-arch builds: Handling x64 and arm64 via GitHub Actions matrix flags rather than pinning in config to avoid arch mismatch errors apps/desktop/electron-builder.config.ts22-28

Sources: apps/desktop/scripts/build-sidecar.ts34-56 apps/desktop/electron-builder.config.ts1-63

---

6. Technical Implementation Summary

Component	Code Entity	Responsibility
Main Entry	index.ts	Bootstraps Electron, manages BrowserWindow.
Lifecycle	sidecar.ts	Spawns/monitors the executor CLI process.
IPC Bridge	ExecutorBridge	Secure communication between React and Node.js.
Service Control	service.ts	Manages launchd/systemd registrations.
Persistence	settings.ts	Manages settings.json via electron-store.
Diagnostics	diagnostics.ts	Collects logs and crash dumps for export.

Diagram: Sidecar Readiness Contract This diagram shows the specific string-based handshake used to synchronize the Electron process with the Bun/CLI sidecar.

Sources: apps/desktop/src/main/sidecar.ts38-42 apps/desktop/src/sidecar/server.ts142-144 apps/desktop/src/main/index.ts141-146