> ## Documentation Index
> Fetch the complete documentation index at: https://amd-gaia.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Packaging & Deployment

<Info>
  **Source Code:** [`src/gaia/apps/webui/`](https://github.com/amd/gaia/blob/main/src/gaia/apps/webui/) | [`src/gaia/ui/`](https://github.com/amd/gaia/blob/main/src/gaia/ui/)
</Info>

# Overview

The GAIA Agent UI is distributed as an [npm package](https://www.npmjs.com/package/@amd-gaia/agent-ui) and can also be packaged as an Electron desktop app for Windows and Ubuntu.

<CardGroup cols={2}>
  <Card title="Agent UI Guide" icon="desktop" href="/docs/guides/agent-ui">
    Features, keyboard shortcuts, troubleshooting, and architecture.
  </Card>

  <Card title="Agent UI SDK" icon="code" href="/docs/sdk/sdks/agent-ui">
    Python backend API: FastAPI server, SQLite database, Pydantic models, and SSE streaming.
  </Card>

  <Card title="Custom Installer" icon="box-archive" href="/docs/playbooks/custom-installer/index">
    Ship a branded GAIA build with your agent pre-loaded.
  </Card>
</CardGroup>

***

# Installation

<Warning>
  Prebuilt desktop installers (`.exe` / `.deb`) are being rolled out. To use
  the Agent UI today, install via npm (launcher binary is `gaia-ui`):

  ```bash theme={null}
  npm install -g @amd-gaia/agent-ui
  gaia-ui
  ```

  Or launch from the GAIA CLI: `gaia --ui`. See the
  [Agent UI guide](/docs/guides/agent-ui) for details.
</Warning>

Install GAIA Agent UI on Windows and Ubuntu using the packages from the GitHub
[Releases](https://github.com/amd/gaia/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](https://github.com/amd/gaia/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](https://github.com/amd/gaia/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](https://github.com/amd/gaia/releases).
2. Open a terminal in the download folder, then install with apt:

```bash theme={null}
sudo apt update
sudo apt install ./gaia-agent-ui-*-amd64.deb
```

3. Launch GAIA from your application menu (search for "GAIA") or run `gaia-desktop` from a terminal.
4. On first launch, setup may take a moment. An internet connection is required the first time.
5. Updating: download the newer `.deb` from [Releases](https://github.com/amd/gaia/releases) and reinstall with apt (same command as above).
6. Uninstalling (package name is `gaia-desktop`):

```bash theme={null}
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](/docs/reference/troubleshooting#appimage-on-linux).
Use the AppImage for portable installs or distros without apt.

<Warning>
  **Ubuntu 24.04 LTS minimal** does not ship the FUSE 2 runtime or the
  Chromium system libraries that the AppImage bundles. Install them first:

  ```bash theme={null}
  sudo apt install libfuse2 libglib2.0-0t64 libgtk-3-0t64 libnss3 \
      libasound2t64 libxss1 libxtst6 libatk-bridge2.0-0t64 libgbm1
  ```
</Warning>

1. Download `gaia-agent-ui-<version>-x86_64.AppImage` from [Releases](https://github.com/amd/gaia/releases).
2. Make it executable and run:

```bash theme={null}
chmod +x gaia-agent-ui-*.AppImage
./gaia-agent-ui-*.AppImage
```

3. 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](/docs/reference/troubleshooting#appimage-on-linux)
   for the security implications and recovery steps.
4. 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):

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
# To persist, add the above line to ~/.profile or ~/.bashrc
```

You can verify the shim exists with:

```bash theme={null}
ls -l ~/.local/bin/gaia
```

5. To collect logs for a bug report:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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 13305)
```

## Developer Quick Start

```bash theme={null}
# 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:

* [Gaia Agent UI Guide](/docs/guides/agent-ui) — User guide with features and troubleshooting
* [Agent UI SDK Reference](/docs/sdk/sdks/agent-ui) — Python backend API documentation
* [Agent UI Server Spec](/docs/spec/agent-ui-server) — Technical specification

***

# License

[MIT License](https://github.com/amd/gaia/blob/main/LICENSE.md)

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

***

<small style="color: #666;">
  **License**

  Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.

  SPDX-License-Identifier: MIT
</small>