Skip to main content
GAIA Agent UI is a desktop interface for running AI agents 100% locally on your AMD hardware. Use agents to analyze documents, generate code, answer questions, and accomplish tasks on your PC — all without sending data to the cloud.
This guide assumes you have completed the Quickstart and have GAIA installed.
Tested Configuration: The Agent UI has been tested exclusively on AMD Ryzen AI MAX+ 395 processors running the Qwen3.5-35B-A3B-GGUF model via Lemonade Server. Other hardware or model combinations may work but are not officially verified.If you encounter issues on a different configuration, please open a GitHub issue and include:
  • Your processor model (e.g., Ryzen AI 9 HX 370, Ryzen AI MAX+ 395)
  • RAM and available memory
  • The LLM model you are using
  • Operating system and version
  • Steps to reproduce the issue

​
Getting Started

​
Prerequisites

The Agent UI requires two backend services:
  1. Lemonade Server — serves the LLM locally (port 8000)
  2. A downloaded model — the LLM the agent uses to reason
Using the npm install? gaia-ui handles prerequisite #1 and #2 automatically on first run (installs Lemonade Server and downloads a minimal model). You can skip to Install and Launch.
If you’re using the Python CLI path, or want the full-size model, run: 
gaia init --profile chat
This downloads Lemonade Server and the recommended model (~25 GB). Use --profile minimal for a smaller download (~400 MB). Then start the server: 
lemonade-server serve

​
Install and Launch

Choose one of the two install paths:

​
What You Can Do

​
Search and Browse Files

The agent has access to your local file system. Ask it to find files, explore directories, or locate specific content across your projects — no manual browsing required.

​
Analyze Documents

Once the agent finds files — or you drag them into a session — it can index and analyze their content. Ask it to summarize, compare, extract data, or answer questions about any supported format:
  • Documents: PDF, Word, PowerPoint, Excel, TXT, Markdown, CSV, JSON, HTML, XML, YAML
  • Code: Python, JavaScript, TypeScript, Java, C/C++, Go, Rust, Ruby, Shell
  • Config: INI, CFG, TOML, YAML, JSON, XML

​
Session Management

Create, rename, search, export (Markdown/JSON), and delete sessions. Sessions persist across the CLI (gaia chat) and the Agent UI.

​
Keyboard Shortcuts

ShortcutAction
EnterSend task / message
Shift+EnterNew line
EscapeStop agent response
Ctrl+KFocus sidebar search

​
MCP Server

The Agent UI includes a built-in MCP (Model Context Protocol) server that exposes the full Agent UI as a set of tools. This lets external AI assistants — like Claude Code, Cursor, or any MCP-compatible client — interact with GAIA agents through the same backend that powers the web UI. Conversations initiated via MCP appear in the browser UI in real time, so you can watch tool execution and agent activity as it happens. The MCP server provides 15 tools for managing sessions, sending messages, indexing documents, browsing files, and more. See the Agent UI MCP Server guide for setup instructions and usage examples.

​
Troubleshooting

Start Lemonade with lemonade-server serve. If Lemonade is not installed, follow the initialization steps in the Quickstart.
Download models with gaia init --profile chat. See the Quickstart for details.
# npm CLI
gaia-ui --port 8080

# Python CLI
gaia --ui-port 8080
Close any other GAIA Agent UI or CLI instances. Only one writer at a time is supported.
  • Ensure the file is a supported format and not password-protected
  • Keep file size under 100MB
  • For PDF image extraction, download the VLM model: gaia download --agent chat
The Agent UI frontend has not been built.npm install (gaia-ui): This is handled automatically — gaia-ui tells the Python server where to find the pre-built frontend. If you still see this error, try reinstalling: npm install -g @amd-gaia/agent-ui@latest Then restart with gaia-ui.Source/dev installs (git clone): Run gaia init to build it automatically, or manually (from the repo root):
cd src/gaia/apps/webui && npm install && npm run build
Then restart gaia chat --ui.pip/PyPI installs (without gaia-ui): Use the npm install path — the pip package does not include frontend source files.

​
Architecture

For the REST API reference and backend classes, see the Agent UI SDK Reference.

​
Next Steps

Agent UI SDK Reference

REST endpoints, database schema, and Python backend API

Document Q&A Agent

CLI-based document agent with RAG, debug mode, and chunking strategies

Build Your First Agent

Create a custom agent with tools in minutes

MCP Server

Connect Claude Code, Cursor, or any MCP client to the Agent UI