Desktop Application

This document covers the architecture, build process, and usage of the MateClaw desktop application (mateclaw-desktop).

Overview

mateclaw-desktop is built on Electron, embedding the Vue 3 frontend in a Chromium window while managing an embedded Spring Boot backend process (with a bundled JRE). Users do not need to install Java or open a browser -- the full MateClaw experience is available immediately upon launching the app.

Architecture

┌──────────────────────────────────────────┐
│            Electron Shell                 │
│  ┌────────────────────────────────────┐  │
│  │      BrowserWindow (Chromium)      │  │
│  │  ┌──────────────────────────────┐  │  │
│  │  │   Vue 3 Frontend (dist/)     │  │  │
│  │  │   Element Plus + Tailwind    │  │  │
│  │  └────────────┬─────────────────┘  │  │
│  └───────────────┼────────────────────┘  │
│                  │ HTTP / SSE             │
│  ┌───────────────▼────────────────────┐  │
│  │   Spring Boot Backend (child proc)  │  │
│  │   localhost:18088                   │  │
│  │   Bundled JRE + H2 File Database    │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │   electron-updater Auto Update      │  │
│  │   GitHub Releases check + download  │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

Key features:

• Native window experience with no browser dependency
• System tray integration for background operation
• Bundled JRE -- users do not need to install Java separately
• Auto update: checks GitHub Releases and downloads updates via electron-updater
• Local-first data storage in the user directory
• Cross-platform support (macOS, Windows, Linux)

Supported Platforms

Platform	Architecture	Status
macOS	Intel (x64)	Supported
macOS	Apple Silicon (ARM64)	Supported
Windows	x64	Supported
Linux	x64	Supported

Prerequisites

Requirement	Version	Purpose
Node.js	18+	Frontend build tooling and Electron development
pnpm / npm	8+ / 9+	Package manager
Java	21+ (recommended)	Backend compilation and dev mode (production builds bundle the JRE)
Maven	3.8+	Backend build

Module Structure

mateclaw-desktop/
├── electron/
│   ├── main/
│   │   └── index.ts             # Electron main process (backend management, auto update)
│   └── preload/
│       └── index.ts             # Preload script (IPC bridge)
├── src/                         # Vue 3 frontend source (renderer process)
│   └── App.vue
├── resources/
│   ├── jre/                     # Bundled JRE (per platform/architecture)
│   └── app.jar                  # Spring Boot backend JAR
├── build/                       # App icons (per-platform formats)
├── electron-builder.json        # electron-builder packaging configuration
├── package.json                 # Contains dev / build / package scripts
└── vite.config.ts               # Vite + vite-plugin-electron configuration

Development Mode

cd mateclaw-desktop
npm install
npm run dev

In development mode:

1. Vite starts the frontend dev server (hot module replacement enabled)
2. The Electron main process starts and opens a BrowserWindow loading the Vite dev URL
3. The main process spawns the Spring Boot JAR as a child process, listening on localhost:18088
4. The frontend communicates with the backend via HTTP/SSE

Frontend code changes trigger hot reload (HMR); Electron main process code changes trigger an automatic restart.

Production Build

cd mateclaw-desktop
npm run build && npx electron-builder --mac   # macOS
npm run build && npx electron-builder --win   # Windows
npm run build && npx electron-builder --linux # Linux

Build artifacts are placed in the release/ directory:

Platform	Output	Notes
macOS	.dmg installer + .zip	Drag to Applications to install
Windows	.exe installer (NSIS)	Standard Windows installation flow with custom install directory
Linux	.AppImage	Add execute permission and run directly, no installation needed

Build Prerequisites

Before building the desktop package, prepare the backend JAR and JRE:

# 1. Build frontend static assets
cd mateclaw-ui
pnpm install && pnpm build

# 2. Build backend JAR (includes frontend assets)
cd mateclaw-server
mvn clean package -DskipTests

# 3. Copy JAR to the desktop project resources directory
cp target/mateclaw-server.jar ../mateclaw-desktop/resources/app.jar

# 4. Download the platform-specific JRE (script downloads and extracts to resources/jre/)
cd ../mateclaw-desktop
bash scripts/download-jre.sh

# 5. Build the desktop installer
npm run build && npx electron-builder

Java Backend Lifecycle Management

The Electron main process manages the Java backend lifecycle through Node.js child_process:

1. Startup: On launch, the main process spawns the Spring Boot JAR using the bundled JRE as a child process and waits for the backend port to become ready
2. Readiness check: Polls http://localhost:18088 until the backend responds, then loads the frontend page
3. Runtime: The frontend communicates with the backend at localhost:18088 via REST APIs and SSE streaming
4. Shutdown: When the user quits, the main process sends a graceful shutdown signal (SIGTERM / taskkill) to the backend, waits for the process to exit, then closes the window

Auto Update

The MateClaw desktop edition integrates electron-updater for automatic detection and download of new versions from GitHub Releases.

Update Flow

1. On startup, the app automatically checks GitHub Releases for a new version
2. When a new version is found, an update notification is displayed in the UI (version number and changelog)
3. After user confirmation, the update package begins downloading with real-time progress display
4. Once downloaded, the user can choose "Install now" or "Install on next launch"
5. During installation, the app exits automatically, replaces files, and restarts

Configuration

The update source is configured in the publish field of electron-builder.json:

{
  "publish": [
    {
      "provider": "github",
      "owner": "matevip",
      "repo": "mateclaw"
    }
  ]
}

Dev Mode Testing

In development mode, electron-updater can still work if a dev-app-update.yml file exists in the project root. Otherwise, auto update is skipped.

Data Storage

The desktop edition uses an H2 file database stored in the user directory:

• macOS: ~/Library/Application Support/MateClaw/data/
• Windows: %APPDATA%/MateClaw/data/
• Linux: ~/.local/share/MateClaw/data/

electron-builder.json Configuration

The packaging configuration is in electron-builder.json, controlling how installers are generated:

Setting	Description
appId	Unique app identifier (vip.mate.mateclaw), used for system registration and code signing
productName	App name shown in the title bar and installer
publish	Auto update source configuration (GitHub Releases)
extraResources	Additional resources to bundle (JRE and app.jar)
mac.target	macOS build targets: dmg + zip, supporting arm64 and x64
win.target	Windows build target: NSIS installer
linux.target	Linux build target: AppImage
mac.hardenedRuntime	macOS hardened runtime (required for code signing and notarization)
nsis.oneClick	Set to false to allow users to choose the install directory

Environment Variables

The desktop app requires API keys for AI functionality:

# macOS / Linux -- add to shell profile
echo 'export DASHSCOPE_API_KEY=sk-your-key' >> ~/.zshrc
source ~/.zshrc

# Windows -- set as system environment variable
setx DASHSCOPE_API_KEY sk-your-key

Alternatively, configure API keys through the Settings page after launching the app.

Troubleshooting

Blank Window

Symptom: The app launches but shows a blank or white window.

Possible causes and solutions:

1. Backend failed to start -- check for a Java process listening on port 18088

   lsof -i :18088         # macOS / Linux
   netstat -ano | findstr 18088  # Windows

2. Port conflict -- stop any process using port 18088 and retry
3. Bundled JRE is corrupted -- try reinstalling the app
4. Check application logs for specific errors

Code Signing

Unsigned apps trigger security warnings on macOS and Windows:

• macOS: On first launch, right-click the app and select "Open" to bypass Gatekeeper. For production distribution, configure an Apple Developer certificate for signing and notarization. See mateclaw-desktop/CODESIGNING.md for details.
• Windows: Users may see a SmartScreen warning. Click "More info" then "Run anyway". For production distribution, obtain an EV code signing certificate.

Desktop App Won't Start

Symptom: Double-clicking the app icon produces no response or a brief flash.

Troubleshooting steps:

1. The installed app bundles its own JRE, so Java does not need to be installed separately. If running a development build from source, verify that java -version shows 21 or higher
2. Review application logs:
   • macOS: ~/Library/Logs/MateClaw/
   • Windows: %APPDATA%/MateClaw/logs/
   • Linux: ~/.local/share/MateClaw/logs/
3. Try launching from a terminal to see console output
4. Confirm that port 18088 is not occupied by another process

WeCom (WeChat Work) Auth Popup

The WeCom QR code authorization flow in the desktop app must open in an in-app popup (not the system browser) to ensure the postMessage callback works correctly. MateClaw handles this in setWindowOpenHandler with special handling for the work.weixin.qq.com domain, automatically opening it as an in-app popup window.

Notes

• The desktop edition uses port 18088 by default; ensure it is not occupied
• First launch takes longer due to database initialization
• Closing the window does not stop the background service; use the system tray to quit
• Data is stored on the local filesystem; back up regularly

Next Steps

• Quick Start -- Local development setup
• Configuration -- Application settings
• Console -- Frontend features