Install GAIA

This is the page to start from if you want to use GAIA. GAIA runs AI agents locally on your machine, and you can use them two ways: the desktop app (a window with chat, your documents and files) or the terminal (gaia-tui). Building agents or working on GAIA itself? Skip to For developers.

What you’ll need

A computer running Windows 10/11, macOS 14+ (Apple Silicon), or Linux (Debian/Ubuntu/Fedora/Arch)
5 GB of free disk space (for the app + Python environment + minimal model)
16 GB of RAM or more. On a 16 GB PC, close other large apps first: the model needs about 8 GB free (see Not enough free memory)
An internet connection for the first launch (the app downloads its Python backend automatically)
About 10–15 minutes total: ~30 seconds to download, ~10 seconds to install, ~10 minutes or more for the first-launch backend setup

Download

Windows
macOS
Linux (Debian/Ubuntu)
Linux (other distros)

One installer, for Windows 10/11 on x64. While it runs you choose how you’ll use GAIA — the desktop app, the terminal, or both. At least one is required.

Choice	What you get	Shortcut it adds
Desktop app	A window with chat, your documents and files, and every tool call shown as it runs. Starts when you sign in to Windows — turn that off from the app’s tray menu or Task Manager → Startup.	GAIA, on the desktop and Start menu
Terminal	`gaia-tui` on your PATH, with a GAIA profile and font for Windows Terminal. See Terminal UI.	GAIA Terminal Hub, on the desktop and Start menu

On amd-gaia.ai, click Install GAIA for Windows. The file is gaia-<version>-win-x64-setup.exe.
Run it. It needs no administrator rights — everything installs for your account only.
On Choose Components, tick the desktop app, the terminal, or both.
Click Finish, then open GAIA from its desktop shortcut.

Either choice also installs Lemonade Server, the local model runtime, from inside the installer, so the install itself works offline.Updating or adding the other one: run a newer (or the same) installer. It starts with what you already have ticked. Unticking something does not remove it — uninstall it instead (see Uninstalling).Before GAIA 0.25, Windows had two separate installers: gaia-agent-ui-<version>-x64-setup.exe for the desktop app and the terminal-only gaia-<version>-win-x64-setup.exe. The new installer updates either one in place.

The first time you run an unsigned installer, Windows SmartScreen may show a “Windows protected your PC” warning. Click More info → Run anyway. (We’re working on Windows code signing — see troubleshooting.)

Windows on Arm has no installer: the desktop app has no Arm build, and neither does the agent the terminal runs. The standalone gaia-tui binary is in the full download list on amd-gaia.ai.

Go to GitHub Releases
Download gaia-agent-ui-X.Y.Z-arm64.dmg (Apple Silicon only)
Double-click the DMG to open it
Drag GAIA to the Applications folder
Eject the DMG and launch GAIA from Applications

On first launch, macOS Gatekeeper may show “GAIA cannot be opened because the developer cannot be verified.” Right-click the app and choose Open, then click Open in the dialog. (We’re working on Apple notarization — see troubleshooting.)

Intel Macs are not currently supported by the desktop app.Want the terminal instead, or as well? Its .pkg (Apple Silicon and Intel) is on amd-gaia.ai — see Terminal UI.

Go to GitHub Releases
Download gaia-agent-ui-X.Y.Z-amd64.deb

Install with apt:

sudo apt install ./gaia-agent-ui-X.Y.Z-amd64.deb

Launch GAIA from your application menu, or run gaia-desktop from a terminal

Or install via the GUI: double-click the .deb file and your software center will install it.Want the terminal instead, or as well? Its .deb and .rpm are on amd-gaia.ai — see Terminal UI.

Go to GitHub Releases
Download gaia-agent-ui-X.Y.Z-x86_64.AppImage

Make it executable:

chmod +x gaia-agent-ui-X.Y.Z-x86_64.AppImage

Double-click the AppImage to run, or run from terminal:
./gaia-agent-ui-X.Y.Z-x86_64.AppImage

AppImages are self-contained and require no installation. Move it anywhere convenient (e.g., ~/Applications/).

On macOS and Linux the desktop app and the terminal still download separately; a single installer with the same choice is planned for them too.

Silent install on Windows (IT and scripted deployment)

The Windows installer is an NSIS package, so it takes the usual /S, plus /COMPONENTS= to choose what to install:

gaia-<version>-win-x64-setup.exe /S /COMPONENTS=ui,tui

Option	Meaning
`/S`	No windows, no prompts.
`/COMPONENTS=ui,tui`	`ui` is the desktop app, `tui` the terminal; name one or both, no spaces. Without it, `/S` updates whatever is already installed, and installs both on a machine that has neither.
`/D=<folder>`	The terminal’s install folder. Must come last. The desktop app always uses its own folder.

Exit code	Meaning
`0`	Installed what was asked.
`2`	A GAIA program it would replace is running. Nothing was changed.
`3`	`/COMPONENTS=` named something unknown, or nothing. Nothing was changed.
`4`	A conflicting install: a GAIA developer build, or the desktop app installed for all users. Nothing was changed.
`5`	A chosen component failed. Any other component you chose was installed.

/S installs for the account that runs it. Deployment tools that run as SYSTEM (the SCCM and Intune default) install into SYSTEM’s profile, not a user’s — run it in the user’s context. To uninstall silently, run each component’s QuietUninstallString from HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall. Both keep ~/.gaia when silent.

First-launch setup (desktop app)

The first time you launch the desktop app, it automatically sets up its Python backend. You’ll see a progress dialog with these stages:

Pre-flight checks (~5 seconds) — verifies free disk space and network connectivity
Download uv (~30 seconds) — installs the uv Python package manager
Create Python environment (~30 seconds) — downloads Python 3.12 and creates a virtualenv at ~/.gaia/venv/
Install GAIA backend (~3-5 minutes) — installs the amd-gaia[ui] Python package and its dependencies
Download the models (several minutes; the largest download) — runs gaia init --profile gaia, the same setup the app checks for, so the first launch does not run setup again. It fetches the default chat model via Lemonade Server, Gemma-4-E4B-it-GGUF (~6 GB) on most PCs or Qwen3.6-35B-A3B-GGUF (~23 GB) on PCs whose GPU can hold it, such as Ryzen AI Max systems, plus the small document-search model. If you set default_model yourself, that model is downloaded instead of Gemma. If this step is interrupted, the next launch finishes it rather than reporting GAIA as installed
Verify (~5 seconds) — runs a quick test to confirm everything works

Total: about 10 minutes the first time, longer on a slow connection — most of it is the backend packages and the model download (~6 GB, or ~23 GB for Qwen3.6 on Ryzen AI Max). Subsequent launches are instant — the app reuses the installed environment.

What if it fails?

If the install fails, you’ll see an error dialog with:

A short explanation of what went wrong
A Retry button
A Manual install instructions link to the troubleshooting guide
A Quit button

The full install log is at ~/.gaia/electron-install.log — attach it when reporting issues. See the installation troubleshooting guide for common failure modes.

Use a Lemonade you already run

GAIA normally runs its own private Lemonade Server. If you already run Lemonade, point GAIA at yours instead: the PC then runs one server and keeps one copy of each model, and your own launch flags and backend stay in charge. On a 16 GB machine, two servers side by side can run it out of memory. GAIA asks the first time it finds one, and remembers the answer:

Desktop app and npx @amd-gaia/agent-ui: the first install asks before it downloads anything. The Agent UI’s setup screen asks too.
Terminal UI: the first-run checks offer it.
Command line: gaia init asks; gaia init --yes never switches on its own and prints the command to run instead.

To switch at any time:

gaia lemonade connect http://localhost:13305

gaia config set lemonade_mode gaia

gaia lemonade status

In the Agent UI, use Settings → Advanced → Model server. gaia lemonade connect with no address uses the one gaia lemonade detect finds on this PC.

Version: your Lemonade must be v10.9.0 or newer. An older one is refused, and the message names both versions.
API key: if your server was started with LEMONADE_API_KEY, GAIA asks for it (--api-key-stdin reads it from a pipe). It’s kept in the OS credential store, never in GAIA’s config file.
Down: if your server isn’t answering, GAIA says so and how to start it. It never starts its own instead.
What GAIA does on your server: registers its embedding model (user.embeddinggemma-300m-GGUF), downloads the models it needs and loads them. Its chat model loads with GAIA’s context size for that load.
What GAIA never does there: change your server’s setup. It doesn’t register cloud providers or hand your server keys, install backends, save load options into its config, or unload or delete your models.
Cloud providers: to chat through Fireworks AI or the AMD LLM Gateway, set the provider up on your server yourself, with its key in your server’s environment. GAIA then uses it as it is. If it isn’t set up, connecting says so instead of changing your server.
Long documents: if answers about long documents time out, raise your server’s request timeout (global_timeout in its config).

LEMONADE_BASE_URL (and LEMONADE_API_KEY) still work and win over this setting. The choice is stored as lemonade_mode and lemonade_base_url in ~/.gaia/config.json. Switching tells a running GAIA daemon right away. It stops GAIA’s own server when you switch to yours, and starts it again when you switch back. Switching back needs GAIA’s own server installed, and waits until it answers: if it isn’t installed or won’t start, the switch is refused or undone and nothing changes. Run gaia init --gaia-lemonade to install it and switch in one step.

Updating GAIA

GAIA checks for updates automatically:

10 seconds after launch
Every 4 hours while running

When an update is available, you’ll see a small “update available” indicator in the status bar. The update downloads silently in the background. When ready, GAIA prompts you to Restart now or Later. Your chat history is preserved across updates. To disable auto-updates, set the environment variable GAIA_DISABLE_UPDATE=1 before launching.

Uninstalling

GAIA follows the platform convention: removing the app leaves your user data (chats, documents, downloaded models) behind by default. To remove the data too, run the gaia uninstall CLI from a terminal — it has tiered flags so you can decide exactly what to keep.

Windows

The Windows uninstallers keep data by default. Choosing Yes to the additional cleanup prompt deletes every file in ~/.gaia, including custom agents, connector sign-ins and permissions, memory, and shared runtimes. Other GAIA installations using that folder will stop working. Silent uninstalls keep it. Each part you installed has its own entry in Settings → Apps → Installed apps, so you can remove one and keep the other. To remove GAIA completely, uninstall both:

GAIA — the desktop app. Removes the app, its Start Menu / Desktop shortcuts, and the autostart registry entry.
GAIA Terminal Hub — the terminal. Removes gaia-tui, gaia-agent, the PATH entry, the Windows Terminal profile, the font if the installer added it, and its shortcuts.

Each uninstaller shows the cleanup prompt above; decline it and ~/.gaia/ is left alone. For tiered cleanup instead of deleting the whole shared folder, open a terminal (PowerShell or cmd) and run:

~\.gaia\venv\Scripts\gaia uninstall --purge

macOS

Drag the GAIA app from Applications to the Trash. Empty the Trash. To also remove your data, run from a terminal:

~/.gaia/venv/bin/gaia uninstall --purge

Linux (Debian/Ubuntu)

sudo apt remove gaia-desktop

Both apt remove and apt purge preserve your personal data in ~/.gaia. To also remove your data, run as your own user:

~/.gaia/venv/bin/gaia uninstall --purge

Linux (AppImage)

Delete the .AppImage file. To also remove your data:

~/.gaia/venv/bin/gaia uninstall --purge

Tiered cleanup with `gaia uninstall`

The CLI lets you escalate cleanup as far as you want — useful for reclaiming disk or fully resetting:

gaia uninstall --purge --dry-run            # Preview the purge tier without deleting
gaia uninstall --venv                       # Just the Python env
gaia uninstall --purge                      # Venv + chats + documents + config + installer binaries, daemon state and PATH edits
gaia uninstall --purge --purge-lemonade     # Also remove Lemonade Server install
gaia uninstall --purge --purge-models       # Also remove downloaded Lemonade models
gaia uninstall --purge --purge-hf-cache     # Also remove ~/.cache/huggingface/

Where things live

What	Location
Electron app	Platform-specific (Program Files / /Applications / /opt/GAIA)
Python environment	`~/.gaia/venv/`
Chat database	`~/.gaia/chat/gaia_chat.db`
Document Library uploads	`~/.gaia/documents/`
Chat file attachments	`~/.gaia/chat/uploads/`
Configuration	`~/.gaia/electron-config.json`
Logs	`~/.gaia/gaia.log` (capped at 10 MB; older logs rotate to `gaia.log.1`–`gaia.log.3`), `~/.gaia/electron-install.log`
Terminal hub and agent binaries (one-line installer)	`~/.gaia/bin/`
Agent run traces	`~/.gaia/traces/`
Daemon state (token, custody database, logs)	`~/.gaia/host/` (`$GAIA_HOME/host/` when `GAIA_HOME` is set)
Models (managed by Lemonade)	`~/.cache/lemonade/models/`

Setting GAIA_HOME moves Document Library uploads and chat file attachments to $GAIA_HOME/documents/ and $GAIA_HOME/chat/uploads/, the MCP server list to $GAIA_HOME/mcp_servers.json, and installed agents to $GAIA_HOME/agents/. It must not be your home directory or one of its parents.

Privacy

GAIA runs entirely on your machine. No data is sent externally beyond the package downloads during install. There is no telemetry, no crash reporting, no usage analytics. See the FAQ for more.

For developers

The installer above is for using GAIA. To build agents, work on GAIA itself, or put one front end on a machine from a script, use one of these instead. Each installs one thing directly; the script, pip/uv and npm routes add no desktop shortcuts or Installed-apps entries:

You want	Use
The Python CLI and SDK, plus the terminal UI, in one command	Windows: `irm https://amd-gaia.ai/install.ps1 \| iex` · Linux/macOS: `curl -fsSL https://amd-gaia.ai/install.sh \| sh`
The Python package only	`uv pip install amd-gaia` — see Setup and the Quickstart
The desktop app from npm	`npm install -g @amd-gaia/agent-ui`, then `gaia-ui` — see Agent UI
The desktop app’s own installer	`gaia-agent-ui-<version>-<arch>` files on GitHub Releases
Either front end from source	Development guide; the terminal builds with `cd tui && make build`, the desktop installers as in Packaging & Distribution
A Windows build of your own branch to hand to someone	Shareable build. Uninstall it before running the GAIA installer, which refuses to install beside it.

Next steps

Quickstart — your first conversation with a GAIA agent
Chat with your documents — RAG-powered Q&A
Troubleshooting — install failure modes and fixes
FAQ — common questions

Getting Started

C++ Framework

Python Framework

What you’ll need

Download

Silent install on Windows (IT and scripted deployment)

First-launch setup (desktop app)

What if it fails?

Use a Lemonade you already run

Updating GAIA

Uninstalling

Windows

macOS

Linux (Debian/Ubuntu)

Linux (AppImage)

Tiered cleanup with `gaia uninstall`

Where things live

Privacy

For developers

Next steps

​What you’ll need

​Download

​Silent install on Windows (IT and scripted deployment)

​First-launch setup (desktop app)

​What if it fails?

​Use a Lemonade you already run

​Updating GAIA

​Uninstalling

​Windows

​macOS

​Linux (Debian/Ubuntu)

​Linux (AppImage)

​Tiered cleanup with gaia uninstall

​Where things live

​Privacy

​For developers

​Next steps

What you’ll need

Download

Silent install on Windows (IT and scripted deployment)

First-launch setup (desktop app)

What if it fails?

Use a Lemonade you already run

Updating GAIA

Uninstalling

Windows

macOS

Linux (Debian/Ubuntu)

Linux (AppImage)

Tiered cleanup with `gaia uninstall`

Where things live

Privacy

For developers

Next steps