Skip to main content
Source Code: src/gaia/apps/webui/ | src/gaia/ui/

​
Overview

The GAIA Agent UI is distributed as an npm package and can also be packaged as an Electron desktop app for Windows and Ubuntu.

Agent UI Guide

Features, keyboard shortcuts, troubleshooting, and architecture.

Agent UI SDK

Python backend API: FastAPI server, SQLite database, Pydantic models, and SSE streaming.

Custom Installer

Ship a branded GAIA build with your agent pre-loaded.

​
Installation

Prebuilt desktop installers (.exe / .deb) are being rolled out. To use the Agent UI today, install via npm (launcher binary is gaia-ui):
npm install -g @amd-gaia/agent-ui
gaia-ui
Or launch from the GAIA CLI: gaia --ui. See the Agent UI guide for details.
Install GAIA Agent UI on Windows and Ubuntu using the packages from the GitHub Releases page (when available). Artifact names follow gaia-agent-ui-<version>-<arch>-setup.<ext> (see electron-builder.yml).

​
Supported platforms

  • Windows 11 (64-bit) - Full GUI and CLI support
  • Linux: Ubuntu 22.04 LTS or 24.04 LTS (64-bit) - Full GUI and CLI support

​
Windows (.exe)

  1. Download gaia-agent-ui-<version>-x64-setup.exe (e.g. gaia-agent-ui-0.17.2-x64-setup.exe) from Releases.
  2. Double-click the installer and follow the prompts.
  3. Launch GAIA from the Start Menu (search for “GAIA”) or the desktop shortcut. The underlying binary is gaia-desktop.
  4. On first launch, setup may take a moment. An internet connection is required the first time.
  5. Updating: download the newer gaia-agent-ui-<version>-x64-setup.exe from Releases and run it.
  6. Uninstalling: Windows Settings → Apps → Installed apps → find “GAIA” → Uninstall.

​
Ubuntu (.deb)

  1. Download gaia-agent-ui-<version>-amd64.deb (e.g. gaia-agent-ui-0.17.2-amd64.deb) from Releases.
  2. Open a terminal in the download folder, then install with apt:
sudo apt update
sudo apt install ./gaia-agent-ui-*-amd64.deb
  1. Launch GAIA from your application menu (search for “GAIA”) or run gaia-desktop from a terminal.
  2. On first launch, setup may take a moment. An internet connection is required the first time.
  3. Updating: download the newer .deb from Releases and reinstall with apt (same command as above).
  4. Uninstalling (package name is gaia-desktop):
sudo apt remove gaia-desktop

​
Ubuntu (.AppImage)

Both the AppImage and the .deb ship with --no-sandbox to work around Ubuntu 24.04.1+‘s AppArmor-restricted unprivileged-userns policy (kernel.apparmor_restrict_unprivileged_userns=1), which otherwise aborts Chromium with a FATAL sandbox error on first launch — see the security note in Troubleshooting → AppImage on Linux. Use the AppImage for portable installs or distros without apt.
Ubuntu 24.04 LTS minimal does not ship the FUSE 2 runtime or the Chromium system libraries that the AppImage bundles. Install them first:
sudo apt install libfuse2 libglib2.0-0t64 libgtk-3-0t64 libnss3 \
    libasound2t64 libxss1 libxtst6 libatk-bridge2.0-0t64 libgbm1
  1. Download gaia-agent-ui-<version>-x86_64.AppImage from Releases.
  2. Make it executable and run:
chmod +x gaia-agent-ui-*.AppImage
./gaia-agent-ui-*.AppImage
  1. On Ubuntu 24.04.1+, the AppImage runs with --no-sandbox by default to work around the distro’s AppArmor userns restriction. See Troubleshooting → AppImage on Linux for the security implications and recovery steps.
  2. If you downloaded the AppImage (portable) variant, the desktop app creates a small user shim so you can run the gaia CLI from a terminal. The shim is written to ~/.local/bin/gaia when the bundled Python backend is installed and no other gaia binary exists on your PATH. If gaia is still not found after installation, add ~/.local/bin to your PATH (shell restart may be required):
export PATH="$HOME/.local/bin:$PATH"
# To persist, add the above line to ~/.profile or ~/.bashrc
You can verify the shim exists with: 
ls -l ~/.local/bin/gaia
  1. To collect logs for a bug report:
gaia diagnostics
Attach the resulting ~/.gaia/diagnostics-*.tgz to your GitHub issue.

​
Troubleshooting — zombie backend processes

If the Electron front-end crashes or is force-quit, the Python backend process may remain running (listening on a random port). The AppImage now attempts to clean up stale backends on startup, but you can inspect and terminate any leftover processes manually: 
# List running GAIA backend processes
ps aux | grep -E 'python.*gaia' | grep -v grep

# Terminate a PID (SIGTERM then SIGKILL if needed)
kill <pid> || sudo kill -9 <pid>
If you repeatedly see leftover backends, please attach the diagnostics bundle produced by gaia diagnostics to your issue and include the output of ps aux | grep -E 'python.*gaia'.

​
Arch Linux and AppImage notes

Arch and some rolling-release distros may ship significantly newer glibc or system libraries than the Ubuntu runner used to produce the AppImage. If the AppImage binary is not compatible on Arch you have these options:
  • Use the browser-based UI by running the backend manually:
lemonade-server serve
python -m gaia.ui.server
# Open http://127.0.0.1:4200
  • Install from source or via the project npm package and run the UI in development mode (see Developer Quick Start).
  • Report the incompatible AppImage on GitHub so we can extend the CI build matrix to produce an Arch-compatible artifact.
When filing an Arch/AppImage issue, include your ldd --version, cat /etc/os-release, and the AppImage stdout/stderr from a terminal run so we can diagnose glibc mismatches.

​
Gaia Agent UI Architecture

The Gaia Agent UI is a privacy-first desktop chat application built with a Python FastAPI backend and a React/TypeScript frontend, packaged as an Electron desktop app.

​
Key Features

  • Privacy-first: All data stays local — no cloud, no telemetry
  • Document Q&A: Drag-and-drop 50+ file formats for RAG-powered search
  • Session management: Create, rename, export, and delete conversations
  • Streaming responses: Real-time SSE streaming from local LLMs
  • Shared CLI/UI state: Same SQLite database as gaia chat CLI
  • Modern frontend: React + TypeScript SPA with Zustand state management

​
Architecture

Gaia Agent UI
  Electron Shell (optional) or Browser
    |
    v
  FastAPI Backend (Python, port 4200)
    - REST API + SSE streaming
    - SQLite database (WAL mode)
    |
    v
  GAIA Core SDKs
    - AgentSDK, RAGSDK, LemonadeClient
    |
    v
  Lemonade Server (port 8000)

​
Developer Quick Start

# 1. Start Lemonade Server
lemonade-server serve

# 2. Start Agent UI backend
python -m gaia.ui.server

# 3. Open http://127.0.0.1:4200 in your browser
For full documentation, see:

​
License

MIT License Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved. SPDX-License-Identifier: MIT