Agent UI - GAIA SDK

Ask your PC to find that contract you downloaded last month. Drop in a spreadsheet and get an instant analysis. Search across thousands of files in seconds. GAIA Agent UI puts a local AI agent in your browser — one that sees your files, understands your documents, and never sends a byte to the cloud.

New to GAIA? Start with the Quickstart for first-time setup, then come back here.

Two commands to get started:

npm install -g @amd-gaia/agent-ui
gaia-ui

Everything installs automatically — Python, the AI model, the backend. No accounts, no API keys, no cloud. Just your machine.

What You Can Do

Find Anything on Your PC

Ask the agent to locate files across your drives — by name, type, content, or recency. No more digging through folder trees.

“Find all Python files in my Downloads folder” “Show me the largest files on my Desktop” “Search my project for files that import pandas”

The agent searches your common folders first, then offers a deep search across all drives if nothing turns up.

Analyze Any Document

Drag files into the chat — or just ask the agent to find them. It indexes the content and lets you ask questions, extract data, compare sections, or get summaries. Works with:

Category	Formats
Documents	PDF, Word, PowerPoint, Excel, TXT, Markdown
Data	CSV, JSON, XML, YAML, HTML
Code	Python, JavaScript, TypeScript, Java, C/C++, Go, Rust, Ruby, Shell
Config	INI, CFG, TOML

“Summarize this PDF in 3 bullet points” “Compare these two contracts and list the differences” “What’s the total spend in this expense report?”

Install

Pick the install path that fits you best:

Desktop installer (easiest)
npm
Python CLI

Prebuilt desktop installers are published on the GitHub Releases page alongside each tagged release. They bundle the Electron shell; Lemonade Server and the default model are downloaded automatically on first launch. This is the simplest path for non-developer end users.Artifact naming (electron-builder.yml): gaia-agent-ui-<version>-<arch>-setup.<ext> — e.g. gaia-agent-ui-0.17.2-x64-setup.exe and gaia-agent-ui-0.17.2-amd64.deb.Windows (.exe):

Download gaia-agent-ui-<version>-x64-setup.exe from Releases.
Double-click to install, then launch “GAIA” from the Start Menu (binary: gaia-desktop).
Update by downloading and running the newer installer.
Uninstall via Windows Settings → Apps → Installed apps → GAIA.

Ubuntu (.deb):

sudo apt install ./gaia-agent-ui-<version>-amd64.deb
gaia-desktop
# Update: apt install the newer .deb the same way.
# Uninstall (apt package name is `gaia-desktop`):
sudo apt remove gaia-desktop

See the Packaging & Distribution page for more detail on the installers, supported platforms, and signing.

The npm package handles everything — on first run it auto-installs Python, the GAIA backend, Lemonade Server, and a minimal model.Requires: Node.js 20+ (winget install OpenJS.NodeJS.LTS on Windows, brew install node@20 on macOS)

npm install -g @amd-gaia/agent-ui
gaia-ui

The Agent UI opens automatically at http://localhost:4200.

Flag	Description
`gaia-ui --port 8080`	Custom port
`gaia-ui --no-open`	Don’t auto-open the browser
`gaia-ui --serve`	Serve frontend only (Node.js static server)
`gaia-ui --version`	Show version

Update:

npm install -g @amd-gaia/agent-ui@latest

If you already have GAIA installed via pip/uv:

gaia --ui

Or equivalently: gaia chat --uiThe Agent UI starts on http://localhost:4200.

Flag	Description
`gaia --ui --ui-port 8080`	Custom port
`gaia --ui --base-url http://192.168.1.100:13305/api/v1`	Connect to Lemonade on another machine

Source/dev installs: The frontend is built during gaia init. If you see a JSON response instead of the UI, run gaia init or manually build (from the repo root):

cd src/gaia/apps/webui && npm install && npm run build

If you see a missing dependencies error, install the UI extras:

uv pip install "amd-gaia[ui]"

Prerequisites (Python path only):The Python CLI path requires you to set up the backend manually:

gaia init --profile chat    # Downloads Lemonade Server + model (~25 GB)
lemonade-server serve       # Start the LLM server

Use --profile minimal for a smaller download (~400 MB).

Uninstall

npm
Python CLI

npm uninstall -g @amd-gaia/agent-ui

To also remove all GAIA data (sessions, config, downloaded models):

# macOS / Linux
rm -rf ~/.gaia

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.gaia"

uv pip uninstall amd-gaia

To also remove all GAIA data:

# macOS / Linux
rm -rf ~/.gaia

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.gaia"

Sessions and Shortcuts

Sessions let you organize conversations by topic. They sync between the CLI (gaia chat) and the Agent UI — start in one, pick up in the other. Export any session as Markdown or JSON from the session menu.

Shortcut	Action
`Enter`	Send message
`Shift+Enter`	New line
`Escape`	Stop agent response
`Ctrl+K`	Search across sessions

Memory

The agent can remember facts, preferences, and decisions across sessions. Memory is opt-in (beta) and disabled by default — see the Agent Memory guide to enable it and learn what the Brain icon’s dashboard exposes.

Policy Alerts and Receipts

When a governance-enabled agent blocks a tool call, the Agent UI shows a non-actionable policy alert instead of an approval prompt. Policy blocks appear as inline Policy Shield activity cards, critical notifications, and a toast with a View receipt link when a receipt ID is available. Policy alerts are durable session history. If you reload the UI or reconnect after a blocked request with no assistant text, the block reason, rule IDs, policy version, and receipt ID remain attached to the assistant message.

Extend with MCP

The agent supports the Model Context Protocol in both directions — connect external tools to expand what the agent can do, or expose the Agent UI itself so other AI tools can drive it.

Add Tools to the Agent

Connect GitHub, Slack, databases, and more via MCP servers

Expose Agent UI to Other Tools

Let Claude Code, Cursor, or any MCP client control GAIA agents

Misconfigured MCP servers can cause slow responses. If you experience timeouts, check ~/.gaia/mcp_servers.json and remove any servers you don’t need. See Troubleshooting for details.

Troubleshooting

Lemonade Server not running

lemonade-server serve

If not installed, run gaia init --profile minimal or follow the Setup Guide.

No model loaded

gaia download --agent chat

Port 4200 already in use

# npm CLI
gaia-ui --port 8080

# Python CLI
gaia --ui --ui-port 8080

Database locked error

Close any other GAIA Agent UI or CLI instances. Only one writer at a time is supported.

Document indexing fails

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

First-run network egress to huggingface.co

The first time you index a document, the embedding model (sentence-transformers) is downloaded from huggingface.co (~100 MB, cached under ~/.cache/huggingface/). Subsequent runs are offline.If your environment blocks huggingface.co, pre-seed the cache on a machine with internet access and copy it to the target machine, or set HF_HOME to point at a pre-populated cache directory before launching the UI.

Frontend shows JSON instead of the UI

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.

LLM response times out or fails

If you see “I wasn’t able to generate a response” errors, check your MCP server configuration. Misconfigured or unreachable MCP servers cause the agent to wait up to 10 seconds per server before responding.Check your config:

# macOS / Linux
cat ~/.gaia/mcp_servers.json

# Windows (PowerShell)
Get-Content "$env:USERPROFILE\.gaia\mcp_servers.json"

If it contains servers you don’t recognize or aren’t running, either remove them or reset the file:

{ "mcpServers": {} }

You can also manage MCP servers through the Agent UI settings panel or with the CLI:

gaia mcp status

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

Hardware: Tested on AMD Ryzen AI MAX+ 395 with Qwen3.5-35B-A3B-GGUF via Lemonade Server. Other configurations may work — report issues here.

​What You Can Do

​Find Anything on Your PC

​Analyze Any Document

​Install

​Uninstall

​Sessions and Shortcuts

​Memory

​Policy Alerts and Receipts

​Extend with MCP

Add Tools to the Agent

Expose Agent UI to Other Tools

​Troubleshooting

​Architecture

​Next Steps

Agent UI SDK Reference

Document Q&A Agent

Build Your First Agent

MCP Server

What You Can Do

Find Anything on Your PC

Analyze Any Document

Install

Uninstall

Sessions and Shortcuts

Memory

Policy Alerts and Receipts

Extend with MCP

Troubleshooting

Architecture

Next Steps