Agent UI

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 is one chat window for the GAIA agent. It runs on your PC by default, and uses a cloud provider (Fireworks AI or the AMD LLM Gateway) only when you pick one of its models.

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

The first time it opens, the app sets itself up: it installs GAIA’s local model server, downloads the models and checks they load, with each step shown in the window. No accounts or API keys are needed to run locally.

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.

Continue Work Across Turns

In-process chat agents retain file reads, tool calls and tool results for later questions, including after the server restarts. Complete older turns leave the model’s context only when its estimated history budget fills; the transcript and stored evidence remain on your machine. When more older turns leave the model’s view — a long chat, or a switch to a smaller model — the chat shows one quiet line before the reply — “Older messages are now out of the model’s view (N turns)” — and the TUI shows the same line in its transcript. Ask GAIA to recall anything from before it. A Hub-installed GAIA agent relayed from the Agent UI sees only the last 5 exchanges, and the chat says so once, when the sixth one lands. Earlier conversations saved before this feature retain text only. If the current prompt leaves no history budget, GAIA warns and sends no older turns; saved evidence remains intact. Switching to a model without native tool calling replays recorded calls and results as text. For Fireworks, AMD gateway, and catalog-discovered cloud models, history admission uses a conservative 64K budget, independent of local device settings and GAIA_CTX_SIZE; this is not a claim about the remote model’s actual context capacity. Claude uses its provider budget. With a cloud model selected, the model chip and the sidebar’s location line name the provider (for example Fireworks AI) instead of Local. They say Local only when GAIA confirms the chat is answered on this PC, and make no claim when it can’t tell. Hover either for what is sent: the whole conversation, including anything read out of files, documents or memory, which themselves stay stored on your machine.

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 Install GAIA for Windows from amd-gaia.ai (gaia-<version>-win-x64-setup.exe) and run it.
Tick Desktop app on Choose Components (and the terminal too, if you want it), then launch “GAIA” from the desktop or Start Menu (binary: gaia-desktop).
Update by running the newer installer; it keeps your choices.
Uninstall via Windows Settings → Apps → Installed apps → GAIA.

See Install GAIA for silent installs. The desktop app’s own installer, gaia-agent-ui-<version>-x64-setup.exe, is still on Releases for scripted installs of the app alone.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@22 on macOS)

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

The Agent UI opens automatically at http://127.0.0.1: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://127.0.0.1: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, run the install command it prints — it targets the Python that GAIA runs in. For the one-line installer’s environment (which has no pip and is not activated) that is:

uv pip install --python ~/.gaia/venv/bin/python "amd-gaia[ui]"
# Windows: uv pip install --python "$env:USERPROFILE\.gaia\venv\Scripts\python.exe" "amd-gaia[ui]"

First run: no separate setup command is needed. When the app opens on a PC that is not set up yet, it shows the same steps gaia init runs (install the local model server, download the models, check they load) and runs them for you. Running gaia init yourself beforehand also works.

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"

The window

The app opens straight to an empty chat: a message box, the model it will use, and where that model runs.

Sidebar: New chat, search, Memory, Scheduled tasks, Documents, then your chats grouped by Today, Yesterday, Previous 7 days and older. At the bottom: where answers are generated right now (for example Local · Gemma-4-E4B-it-GGUF or Fireworks AI · glm-5p3-flash), notifications, mobile access and Settings. Collapse it with Ctrl+B.
Message box: + attaches files (or drag them in), the shield picks the permission mode, the model chip picks the model, and Send turns into Stop while GAIA is working.
Tool steps show as one quiet line (“3 steps · 1 tool”) you can open for the detail. “Steps” is the agent’s own count, the same figure the TUI and evals report.
The line under an answer shows its time and the tokens the whole turn read and wrote, across every model call. Files the answer names by full path, such as a saved deliverable, open in your file explorer when clicked.
“Getting GAIA ready… 12s” under the message box means a local model is reading GAIA’s instructions ahead of your first message, so that message gets a quick answer. You can type and send meanwhile; a message sent early waits for it to finish rather than starting over.

Every chat runs the GAIA agent. Chats made by the retired chat, doc and file agents stay readable but can’t be continued; start a new chat instead.

Models and where they run

Open Settings → Model (or the model chip in the message box):

Provider	What it needs	Where your chat goes
Local	Nothing; pick CPU, GPU or NPU for new chats	Stays on this PC
Fireworks AI	An API key	Sent to Fireworks AI (usage may be charged)
AMD LLM Gateway	A gateway key (and URL, if not the default)	Sent to your gateway

Keys are masked, go only to GAIA’s local model server and your OS credential store, and are refused over mobile access. When a key is already set (in the environment or from the TUI) the screen says so; leave the field blank to keep using it. Forget key removes it here and for future sessions.
Recommended Fireworks models are ranked first, each with the benchmark result behind the pick.
The model you choose is remembered across restarts (shared with the TUI). If it can’t be restored, a one-line notice says why and asks you to pick one.
Switching from a local model to a cloud one shows the privacy note first.

When GAIA’s model server runs

Local chat runs on GAIA’s own Lemonade Server, the one gaia init installs. GAIA manages it for you, and it gives its memory back when you stop using GAIA:

When	What happens
You open the app (desktop, `npx @amd-gaia/agent-ui`, or `gaia-tui`)	GAIA’s background service starts the server if it is not running
You close the last GAIA app	Every model is unloaded, so your GPU memory is free again. The server itself stays up for a quick next launch
Another GAIA process is still using it, or a request is in flight	Nothing is unloaded until it is done
No GAIA process has held it, and it has served no request, for 15 minutes	The server stops entirely
A GAIA process sends a request after it stopped	It starts again and the request goes through, after a cold model load
`gaia daemon stop`	The server stops, including the one first-time setup started

Every GAIA process that talks to the server holds a lease on it while it runs: the app, each gaia command, sidecar agents, and a process started with another GAIA_HOME that points LEMONADE_BASE_URL at this server. The server is never stopped while a lease is held or a request is in flight. The server keeps the same port from one start to the next, and moves only if another program has taken it. Its API key still changes on every start; read the current one from ~/.gaia/lemonade/env.sh (env.ps1 on Windows). Fifteen minutes balances giving the GPU memory back to other apps against the cost of a cold model load, about 20 to 60 seconds, the next time you use GAIA. Change it, or turn the timeout off with 0:

gaia config set lemonade_idle_timeout_minutes 30

The new value applies within seconds; no restart is needed. None of this applies to a Lemonade Server you run yourself and point GAIA at with LEMONADE_BASE_URL: GAIA never unloads its models or stops it.

Which server and which GPU backend

Settings → Advanced → Model server shows what is actually running:

Server: GAIA’s own Lemonade or yours (another Lemonade on this PC, or one on another machine), with its version.
Address: the URL and port GAIA talks to.
Chat model and Runs on: the loaded model and its llama.cpp backend (Vulkan, ROCm, CPU), NPU, or Remote (cloud). “Lemonade’s default” means the load did not name a backend and Lemonade picked it. unknown means this Lemonade does not report it.
Context window and the Embedding model with its backend.

To choose the backend, pick Auto, Vulkan, ROCm or CPU under llama.cpp backend for chat models. Only backends Lemonade can run on this PC are listed; one marked “downloads on first use” is fetched by Lemonade the first time it loads (ROCm is about 4 GB). The choice applies the next time the chat model loads; Reload chat model now applies it at once. The embedding model keeps its own backend. The same setting from a terminal:

gaia config set llamacpp_backend rocm   # vulkan | rocm | metal | cpu | auto

Change model opens Settings → Model. To use a different server, set LEMONADE_BASE_URL.

Permissions

GAIA asks before it changes files, runs commands or uses tools that act for you. The question appears above the message box with three answers:

Allow once
Always allow this exact action in this chat (offered only when the action is narrow enough to name, e.g. write_file on notes.md)
Deny

When the same question comes back after you allowed it once, the prompt says so and highlights Always allow. It never answers for you, and a different tool or a riskier call gets no hint. Pick Full access from the shield to let a chat run everything without asking (you confirm once). Settings → Permissions lists every chat with full access or “always allow” answers and lets you revoke them. Grants end when GAIA restarts. A Hub-installed GAIA, which runs as its own process, follows the chat’s mode too, from agent contract 2.14. It stops asking, but its shell guardrails stay on. If the mode can’t be passed on when a turn starts, that turn stops with an error, so it never runs with full access you turned off.

Settings

One window with General (appearance: Light, Dark, Match system; shortcuts), Model, Permissions, Skills (what GAIA can load, with Use to try one), Connectors, Memory, Privacy and Advanced (model server and llama.cpp backend, context size, custom model ID, beta options, MCP servers, version and roll back). Settings → Advanced → Model server switches between GAIA’s own Lemonade Server and one you already run: enter its address (and its API key, if it needs one) and choose Use this server. The setup screen offers a Lemonade it finds running the first time. GAIA never changes your server’s setup: connecting a cloud provider uses the one your server already has, and says so if it has none. Use GAIA’s own is refused, with nothing changed, when GAIA’s own server isn’t installed; gaia init --gaia-lemonade installs it and switches. See Use a Lemonade you already run.

Roll back to a previous version

If an update introduces a regression, you can roll back to a specific earlier release directly from the app — no need to hunt down an old installer on GitHub. How to roll back (desktop installer only):

Open Settings → Advanced.
Click “Roll back to a previous version”.
The app fetches the list of published releases from GitHub and shows them newest-first, with your currently installed version marked.
Click an older release to open a confirmation step.
Confirm — the app downloads the selected version and shows a native “Restart now?” prompt when ready. Click Restart and the older version launches.

Version pinning (AC2): After a manual rollback, auto-update is automatically paused. The About section shows “Auto-update paused (pinned to vX.Y.Z)” so you know it’s held. Click Resume updates in the same section to re-enable normal auto-updates.

Platform support

Platform	Rollback support
Windows (NSIS installer)	Full — download + reinstall works end-to-end
macOS (DMG/ZIP, signed builds)	Works on signed release builds; unsigned dev builds download but cannot apply the update
Linux AppImage	Supported (self-replacing)
Linux .deb	Not supported via in-app rollback — use `sudo apt install ./gaia-agent-ui-<version>-amd64.deb` from Releases

The rollback list only shows releases that have an installer for your current platform. Releases without a matching artifact are filtered out automatically.

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 chats
`Ctrl+Shift+O`	New chat
`Ctrl+B`	Show or hide the sidebar
`Ctrl+,`	Settings

When GAIA asks permission, the prompt takes focus and Enter does nothing, so a message you were typing can’t approve it. Escape denies (it takes priority over stopping the reply); Tab to Allow once or Always allow and press Enter or Space to approve. The prompt counts down the time the agent will wait, and GAIA denies when it runs out.

Long Responses

A chat reply has no time limit while the agent is making progress: model output, a tool starting or finishing, any step. A running tool, or a question or permission prompt waiting on you, also counts, since each has its own time limit. A model that stops sending is handled by GAIA’s model-stall check, which ends and retries the request. GAIA stops a reply only after 75 minutes with no progress at all, and the reply says so: “This turn ran for 75 minutes without progress, so GAIA stopped it.” Anything finished before then is kept; send “continue” to pick up where it left off. Change the window with GAIA_STREAM_TIMEOUT, set before GAIA starts:

export GAIA_STREAM_TIMEOUT=7200   # seconds without progress; whole number from 1 to 86400
gaia chat --ui

An invalid value (not a whole number, or out of range) stops the Agent UI server at startup with an error naming the variable, rather than quietly using the default.

Memory

The agent can remember facts, preferences, and decisions across sessions. Memory is on by default (beta) — see the Agent Memory guide to learn more. Turn it off in Settings → Memory, and open Memory in the sidebar to search, edit or forget what GAIA remembers.

Scheduled Tasks

Run a prompt on a recurring schedule — “every morning at 9, summarize my inbox” — without leaving the UI. Click Scheduled tasks in the sidebar to open the Schedule Manager. Describe the schedule in natural language; the parser previews the interpretation live before you create it:

Input	Meaning
`every 30m`	Every 30 minutes
`every 6 hours`	Every 6 hours
`daily at 9pm`	Once a day at 21:00
`every monday at 8am`	Weekly on Mondays at 08:00
`every hour from 8am to 6pm`	Hourly inside a time window

Each schedule runs in its own chat session, so the full history of runs (prompt + response per run) is one click away via the session list. Pause, resume, or delete schedules from the panel; run counts and the next-run countdown update live. Behavior notes:

Scheduled runs use the GAIA agent and the model you picked; with a local model nothing leaves your machine.
Runs are suspended while mobile access (tunnel) is active, matching the autonomous agent loop’s security posture. Set GAIA_AUTONOMOUS_ALLOW_TUNNEL=1 to override.
One run executes at a time; overlapping schedules queue.
Per-run timeout defaults to 300 s; override with GAIA_SCHEDULE_TIMEOUT.
Times are your local time, taken from the browser’s time zone, and stay put across daylight-saving changes. A time skipped when clocks jump forward runs just after the jump; a time repeated when they fall back runs once. Schedules made before this was fixed were read in UTC; they move to this PC’s time zone on the next start.

The REST API lives at /api/schedules (create/list/get), /api/schedules/{name} (pause/resume/cancel via PUT, delete via DELETE), /api/schedules/{name}/results (run history), and /api/schedules/parse (natural-language preview).

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

You shouldn’t have to start the model server yourself — gaia daemon starts and supervises it. So the question is why that didn’t happen.

gaia daemon status            # the daemon reports the model server it supervises
gaia daemon start             # if no daemon is running
gaia daemon logs --lines 100  # daemon up but no model server — the reason is here

The usual cause is that GAIA isn’t set up yet. The app shows its setup steps in that case; gaia init from a terminal does the same.

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 does not need a password to open (PDFs with only permission restrictions index fine)
Keep file size under 100MB
For PDF image extraction, download the VLM model: gaia download --agent chat

Access denied: path must be within one of ...

Documents can only be read from an allowed root. By default that is your home directory — a file elsewhere on disk is rejected with HTTP 403.This bites on service accounts and CI runners, whose home (C:\Windows\System32\config\systemprofile) is not where their files live. Add the extra directory before starting the server:

# POSIX — separate multiple roots with ':'
export GAIA_DOCUMENT_ROOTS=/srv/corpus

# Windows — separate multiple roots with ';'
$env:GAIA_DOCUMENT_ROOTS = "C:\actions-runner\_work\gaia\gaia\eval\corpus"

Each entry must be an absolute path to a directory that exists; a relative or missing one fails the request with HTTP 500 rather than being ignored. The containment check still applies — declaring a root widens access to that root only, never to its parent, and a symlink escaping it is still rejected.Two limits worth knowing before you set this:

A declared root is browsable and previewable, but not searchable. File search and “open in file manager” still only look at your home directory, so files under a declared root are reachable by path but will not turn up by name.
The roots apply to every client of the backend, including one reaching it over the tunnel feature. Declare only what you would be comfortable serving remotely.

First-run network egress to huggingface.co

The first time you index a document, Lemonade Server pulls the embedding model (user.embeddinggemma-300m-GGUF, ~334 MB) from huggingface.co, cached under ~/.cache/huggingface/hub/. 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.

Getting Started

C++ Framework

Python Framework

What You Can Do

Find Anything on Your PC

Continue Work Across Turns

Analyze Any Document

Install

Uninstall

The window

Models and where they run

When GAIA’s model server runs

Which server and which GPU backend

Permissions

Settings

Roll back to a previous version

Platform support

Sessions and Shortcuts

Long Responses

Memory

Scheduled Tasks

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

​Continue Work Across Turns

​Analyze Any Document

​Install

​Uninstall

​The window

​Models and where they run

​When GAIA’s model server runs

​Which server and which GPU backend

​Permissions

​Settings

​Roll back to a previous version

​Platform support

​Sessions and Shortcuts

​Long Responses

​Memory

​Scheduled Tasks

​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

Continue Work Across Turns

Analyze Any Document

Install

Uninstall

The window

Models and where they run

When GAIA’s model server runs

Which server and which GPU backend

Permissions

Settings

Roll back to a previous version

Platform support

Sessions and Shortcuts

Long Responses

Memory

Scheduled Tasks

Policy Alerts and Receipts

Extend with MCP

Troubleshooting

Architecture

Next Steps