✨ KiraAI Launcher

Manage your KiraAI projects from one place

English | 简体中文

KiraAI Launcher is a cross-platform desktop application for managing local and cloud KiraAI instances. It helps you download, configure, start, and open KiraAI without working through the command line for everyday tasks.

Important

KiraAI Launcher is under active development. Features and behavior may change between releases.

🚀 Features

• Add an existing local KiraAI project.
• Download and deploy the latest KiraAI release from the official repository.
• Start and stop local projects; the launcher creates the virtual environment and installs dependencies when needed.
• Connect to a deployed KiraAI WebUI instance.
• Change local WebUI ports and set advanced launch arguments or environment variables.
• Open a project's WebUI inside the launcher or in your system browser.
• Inspect Python, uv, and Node.js environments, and install missing tools from supported versions.
• Choose light, dark, or system theme; select a display language and accent color.
• Minimize to the system tray and receive application updates.

💻 Quick Start

Download the installer for your operating system from Releases, install it, then open KiraAI Launcher.

Use New Project to choose one of the following:

1. Manage a local project — select an existing KiraAI directory containing main.py and requirements.txt.
2. Download and deploy — select a parent folder and project name; the launcher downloads the latest KiraAI release and registers it.
3. Connect a cloud instance — enter the URL of a running KiraAI WebUI. An optional WebUI Access Token is encrypted with the operating system's secure storage before it is saved locally.

The Environment page detects Python, uv, and Node.js and downloads missing tools into the environments directory inside the launcher user data directory. No system package manager or administrator privileges are needed. Python is installed independently of uv; all runtime archives are checked against published SHA-256 checksums.

In Settings → Runtime environment, choose Automatic, Global environment, or Launcher environment. Automatic prefers a launcher-managed installation for each tool and falls back to an existing global installation. The other modes use only the selected source. Global mode uses existing installations; switch to Automatic or Launcher environment to download missing tools. The environment page shows the selected source and lets you uninstall launcher-managed tools after local instances and deployments have stopped. Uninstalling removes all launcher-managed versions of that tool and leaves global tools and project files intact.

The selected tools are available immediately without modifying the system PATH. If a project virtual environment uses a different Python than the newly selected one, the next deployment recreates that virtual environment and reinstalls dependencies.

⚙️ Using a Project

Select a project from Projects and use its actions to:

• Start or stop a local KiraAI instance.
• Open the WebUI or local project folder.
• Change its display name and WebUI port.
• Configure additional launch arguments and environment variables for the next local start.
• Remove it from the launcher. Removing a local project never deletes its files.

In Settings → System behavior, enable Restore local instances on next launch to remember active local instances before quitting and restart them the next time the launcher opens, including launch at login. This option defaults to off. Quitting still stops the instances; minimizing to the tray keeps them running. The session is saved during normal launcher exit; forced termination, power loss, or a system restart that bypasses normal exit may not save it. A failed restore is attempted only once and recorded in the launcher log.

The default local WebUI port is 5267. Stop a project before changing its port.

🧪 Development

Requirements

• Node.js 20+ and npm
• A supported desktop platform: Windows, macOS, or Linux

Run locally

npm ci
npm run dev

This starts Vite and Electron together. The Vite development server uses port 5173.

Build and package

npm run build
npm run dist:win

Use npm run dist:mac or npm run dist:linux for the other supported platforms. Build artifacts are written to release/.

🗂️ Project Structure

KiraAI-Launcher/
  electron/           # Electron main process and preload bridge
  src/                # Vue application and translations
  public/             # Application assets
  build/              # Packaging assets
  .github/workflows/  # Release workflow
  package.json        # Scripts, dependencies, and package settings

🔗 Related Projects

• KiraAI — the AI digital life platform managed by this launcher.
• KiraAI Documentation — deployment and configuration documentation for KiraAI.