Electron Desktop Client - Olis Documentation

Overview

The Olis Desktop Client is an Electron-based application that provides a native desktop experience for the Olis AI assistant. It combines Electron’s native capabilities with Next.js for a modern React-based UI.

Technology Stack

Electron

Native desktop wrapper for cross-platform support

Next.js 14

React framework with App Router and static export

TypeScript

Type-safe development across the entire stack

Tailwind CSS

Utility-first CSS framework for styling

Project Structure

apps/electron-client/
├── electron/              # Electron main process
│   ├── main.ts           # Main process entry point
│   └── preload.ts        # Preload script for IPC
├── src/
│   ├── app/              # Next.js App Router pages
│   │   ├── page.tsx      # Main chat interface
│   │   └── settings/     # Settings pages
│   ├── components/       # React components
│   └── lib/              # Utilities and helpers
├── native/
│   └── sidecar/          # Rust native module
├── local-llm/            # Bundled llama-server binaries
├── public/               # Static assets
└── release/              # Build artifacts

Development Setup

Prerequisites

Node.js 18+
pnpm 9.15.4+
Rust (for native sidecar)

Installation

Navigate to the client directory

cd apps/electron-client

Install dependencies

pnpm install

Build native sidecar

pnpm run sidecar:build

This compiles the Rust native module and copies it to native/sidecar/index.node.

Start development server

pnpm run electron:dev

This starts:

Next.js dev server on http://localhost:3000
Electron app that loads the dev server

Available Scripts

Development Scripts

# Run Next.js dev server only
pnpm run dev

# Run Electron + Next.js together (recommended)
pnpm run electron:dev

# Build native Rust sidecar
pnpm run sidecar:build

# Lint code
pnpm run lint

Production Build Scripts

# Build Next.js static export
pnpm run build

# Compile Electron main process
pnpm run build:electron

# Package installers for distribution
pnpm run package

# Rebuild native dependencies
pnpm run install-app-deps

Building for Production

Build the renderer

pnpm run build

Creates a static Next.js export in the out/ directory with:

assetPrefix: "./" for relative paths
trailingSlash: true for file:// protocol
output: "export" for static generation

Compile the main process

pnpm run build:electron

Compiles TypeScript to JavaScript in dist-electron/.

Package the application

pnpm run package

Uses electron-builder to create installers in release/:

Windows: NSIS installer (.exe)
macOS: DMG and ZIP
Linux: AppImage, Snap, DEB

Windows Note: Stop all running Electron instances before packaging. Running instances can lock keytar.node and cause EPERM errors during the build.

Configuration

Environment Variables

Create a .env file in the app root:

# Intent Detection
OLIS_INTENT_MODEL=phi3
OLIS_INTENT_REMOTE_URL=http://localhost:11434
OLIS_INTENT_MODEL_DOWNLOAD_URL=https://example.com/model.gguf
OLIS_INTENT_TIMEOUT_MS=30000

# Document Context
OLIS_DOCS_FOLDER=C:\Users\YourName\Documents\olis-docs

# API Configuration
OLIS_API_URL=http://localhost:8000

For production builds, place .env.production in the resources/ directory.

Next.js Configuration

The next.config.mjs is optimized for Electron:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',        // Static export
  assetPrefix: './',       // Relative paths for file://
  trailingSlash: true,     // Ensures /page.html works
  images: {
    unoptimized: true      // No Image Optimization API needed
  }
}

Electron Builder Configuration

The electron-builder.json5 defines package settings:

{
  "appId": "com.olis.app",
  "productName": "Olis",
  "directories": {
    "output": "release",
    "buildResources": "resources"
  },
  "files": [
    "out/**/*",
    "dist-electron/**/*",
    "native/**/*",
    "local-llm/**/*"
  ],
  "win": {
    "target": ["nsis"],
    "icon": "resources/icon.ico"
  },
  "mac": {
    "target": ["dmg", "zip"],
    "icon": "resources/icon.icns"
  }
}

Features

Intent Detection

The desktop client supports multiple intent detection backends:

Automatic
SLM (Local)
LLM (Remote)
NLP (Fallback)

Chooses the best option based on hardware and configuration:

SLM if available and hardware supports it
LLM if remote service is configured
NLP as fallback

Runs a local language model using bundled llama-server:

Model: GGUF format in local-llm/ directory
No internet required
Privacy-focused
Slower on weaker hardware

Uses a hosted language model:

Faster responses
Requires internet connection
Configurable via OLIS_INTENT_REMOTE_URL
Supports Ollama-compatible APIs

Document Context

Users can configure a document folder for context:

OLIS_DOCS_FOLDER=C:\Users\YourName\Documents\olis-docs

Supported formats:

.txt - Plain text
.md - Markdown
.json - JSON data
.csv - CSV files

Documents are automatically loaded and used as context for queries.

Settings Interface

The settings interface provides three main sections:

General

Theme selection
Language preferences
Default behaviors
Notification settings

Integrations

API connections
Third-party services
OAuth configurations
Webhook settings

Security

Authentication
Encryption settings
Privacy controls
Data retention

Native Sidecar (Rust)

The native sidecar provides high-performance native operations:

// Example: File system operations
#[napi]
pub fn read_file_sync(path: String) -> Result<String> {
  std::fs::read_to_string(path)
    .map_err(|e| Error::from_reason(e.to_string()))
}

Building the Sidecar

cd native/sidecar
cargo build --release

# Copy to correct location
cp ../../target/release/index.node ./

Using in Electron

// In renderer process
const sidecar = require('./native/sidecar/index.node')
const content = sidecar.readFileSync('/path/to/file.txt')

Troubleshooting

Native Module Build Failures

Problem: Errors building Rust sidecarSolution:

# Ensure Rust is installed
rustc --version

# Clean and rebuild
cd native/sidecar
cargo clean
cargo build --release

# Copy manually if needed
cp ../../target/release/index.node ./

Electron Packaging Errors

Problem: EPERM error with keytar.nodeSolution:

Close all Electron instances
Kill any Node processes: taskkill /F /IM electron.exe (Windows)
Run pnpm run install-app-deps
Try packaging again: pnpm run package

Dev Server Not Loading

Problem: Electron opens but shows blank windowSolution:

Ensure Next.js dev server is running on port 3000
Check electron/main.ts loads correct URL
Open DevTools: Ctrl+Shift+I (Windows) or Cmd+Option+I (Mac)
Check console for errors

PowerShell Script Execution

Problem: PowerShell blocks script executionSolution:

# Use .cmd wrapper instead
pnpm.cmd run electron:dev
pnpm.cmd run sidecar:build

# Or enable script execution (admin required)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Best Practices

Development

Use electron:dev for hot reloading
Test on all target platforms
Keep native modules updated
Profile performance regularly

Production

Test packaged builds before release
Code sign applications
Use auto-update mechanism
Monitor crash reports

Security

Enable context isolation
Disable Node integration in renderer
Validate all IPC messages
Use secure storage (keytar)

Performance

Lazy load components
Optimize bundle size
Cache expensive operations
Use native modules wisely

Next Steps

API Server

Learn about the backend API

Intent Detection

Deep dive into intent detection

​Overview

​Technology Stack

Electron

Next.js 14

TypeScript

Tailwind CSS

​Project Structure

​Development Setup

​Prerequisites

​Installation

​Available Scripts

​Building for Production

​Configuration

​Environment Variables

​Next.js Configuration

​Electron Builder Configuration

​Features

​Intent Detection

​Document Context

​Settings Interface

General

Integrations

Security

​Native Sidecar (Rust)

​Building the Sidecar

​Using in Electron

​Troubleshooting

​Best Practices

Development

Production

Security

Performance

​Next Steps

API Server

Intent Detection

Overview

Technology Stack

Project Structure

Development Setup

Prerequisites

Installation

Available Scripts

Building for Production

Configuration

Environment Variables

Next.js Configuration

Electron Builder Configuration

Features

Intent Detection

Document Context

Settings Interface

Native Sidecar (Rust)

Building the Sidecar

Using in Electron

Troubleshooting

Best Practices

Next Steps