Desktop Guide

Aikeya Desktop is an application that brings your AI companion to your desktop with a transparent overlay mode. Your companion can float over other applications, always visible while you work.

Currently available for macOS only. Windows and Linux support is planned.

Installation

Download

Head to the GitHub Releases page and download the .dmg disk image for macOS.

Open the .dmg, drag Aikeya to your Applications folder, and you’re good to go.

macOS Gatekeeper: Since Aikeya isn’t signed with an Apple Developer ID, macOS may show a warning when you first open it. See Gatekeeper Warning below for how to resolve this.

Building from Source

If you prefer to build it yourself:

Prerequisites

Node.js 22+
Rust toolchain (for Tauri)
pnpm

# Clone the repo
git clone https://github.com/aikeyaorg/aikeya.git
cd aikeya

# Install dependencies
pnpm install

# Run in development mode
pnpm tauri dev

# Or build a release binary
pnpm tauri build

The dev command launches both a development server and the desktop window. The build command produces an installer for your current platform in src-tauri/target/release/bundle/.

Features

Main Window

The main window provides the full Aikeya experience — same as the web version with all features:

VRM avatar with animations
Chat interface
Settings and configuration
Memory and relationship systems

A blue monitor icon in the top-right corner launches overlay mode.

Overlay Mode

Overlay mode detaches your companion into a transparent, always-on-top window:

Transparent Background: Only the character is visible; everything else is see-through
Always on Top: The companion stays visible over all other windows
Draggable: Click and drag anywhere on the character to reposition
Floating Chat: Click the chat icon at the bottom to expand a chat input
Speech Bubbles: Responses appear as speech bubbles near the character
Status Indicator: The mood/relationship status pill appears above the chat icon

Controls

Action	How
Move character	Click and drag on the character
Open chat	Click the chat icon at the bottom
Send message	Type and press Enter
Close chat	Send a message (auto-collapses)
Exit overlay	Click the X button in the top-right corner
Push-to-talk	`Ctrl+Shift+Space` (global hotkey)
Toggle overlay	`Ctrl+Shift+U` (global hotkey)
Focus chat	`Ctrl+Shift+C` (global hotkey)

Switching Between Modes

Main → Overlay: Click the blue monitor icon in the top-right
Overlay → Main: Click the X button in the overlay’s top-right corner

Both windows share the same data — your conversation, memories, and relationship state persist across modes.

Known Limitations

Some features are still being worked on:

Feature	Status
macOS support	✅ Available
Windows support	⏳ Planned
Linux support	⏳ Planned
Click-through transparency	❌ Disabled (blocks UI)
Global hotkeys	✅ Available
Position persistence	⏳ Planned
System tray	⏳ Planned

Troubleshooting

Gatekeeper Warning

macOS may show “Aikeya is damaged and can’t be opened” or “Aikeya can’t be opened because it is from an unidentified developer” when launching for the first time. This is because the app isn’t signed with an Apple Developer ID certificate.

Option 1 — Right-click to open:

Find Aikeya in your Applications folder
Right-click (or Control-click) the app
Select Open from the context menu
Click Open on the dialog that appears

macOS remembers this choice — you only need to do it once.

Option 2 — Remove the quarantine flag:

If right-click doesn’t work (you see the “damaged” message), run this in Terminal:

xattr -cr /Applications/Utsuwa.app

Then open the app normally.

App won’t start

If you built from source, make sure Rust is installed:

rustc --version

If not installed, run:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

If you downloaded a release binary and it won’t launch, try downloading it again or check the GitHub Issues page.

Overlay background not transparent

This can happen if the renderer isn’t properly configured. Try:

Exit and relaunch the app
Make sure you’re on the latest version from Releases

Character facing wrong direction

The camera is locked in overlay mode. If the character appears rotated, exit overlay and re-enter.

Voice input not working

The desktop app uses Tauri’s webview, which does not support the browser’s Web Speech API. You need a Groq API key for voice input on desktop. Add it in Settings > Character under the Voice Input (STT) section.

Can’t interact with overlay UI

The X button and chat icon should always be clickable. If they’re not responding, the window may have lost focus — click anywhere on the overlay first.

Technical Details

The desktop app uses:

Tauri v2 — Rust-based framework for desktop apps
Same SvelteKit codebase — No fork, shared components
Platform detection — isTauri() checks for Tauri environment
Multi-window — Main window + overlay window managed separately

For architecture details, see Architecture Overview.