> ## 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.

# The desktop app

> The tray icon, closing and quitting, updates, going back a version, and uninstalling

The desktop app keeps GAIA running in the tray, updates when you say so, and can go back to an earlier version.

## The tray icon

The desktop app keeps an icon in the system tray (the menu bar on macOS). Its
badge shows what GAIA is doing, by shape as well as colour:

| Badge | Meaning |
| - | - |
| None | Idle |
| Open ring | Writing an answer |
| Hourglass | Waiting for the model: loading it, downloading it, or retrying it |
| Solid dot | A chat needs you: an approval or an answer to a question |
| Triangle | Something is wrong: GAIA's service or the model server isn't running |

Hover for a tooltip such as *GAIA — answering in 'Trip plan'*. On Linux, where
most trays show no tooltip, the first line of the menu says the same thing.
On Windows, the taskbar button also shows a dot when a chat needs you or a
notification is unread.

The menu:

* **Status line**, for example `Gemma-4-E4B-it on GPU · idle`.
* **Needs you**: each chat waiting on you. Click one to open it.
* **New chat** and up to five **Recent** chats.
* **Show GAIA**.
* **Free memory…** unloads the chat model to give its memory back, after
  asking. Your next message loads it again. It is greyed out, with the reason,
  while an answer is running in this window, when no model is loaded, or when
  the model runs in the cloud. If an answer elsewhere or a document index still
  needs the model, it says so instead of asking.
* **Settings…** and **Quit GAIA**.

The first time you close the window, GAIA says once that it is still running
in the tray. If you quit, or restart from the update chip, while an
answer is being written or a document is indexing, GAIA asks first and says
that the answer will be lost; when idle it doesn't ask. Keeping GAIA running
puts an update off until you next quit.

**Settings → General → Desktop app** has three switches, each applied as soon
as you flip it:

* **Keep running when the window closes**: close hides the window instead of
  quitting.
* **Start GAIA when you sign in.** Off until you turn it on; an entry an earlier
  version added stays on, and an update keeps your choice. On Windows it also
  follows Task Manager → Startup apps. On Linux
  this writes `gaia-agent-ui.desktop` to `$XDG_CONFIG_HOME/autostart` (usually
  `~/.config/autostart`). If the system refuses, or macOS waits for your
  approval in System Settings → Login Items, the switch stays off and says why.
* **Start in the tray**: every launch opens without the window. Takes effect
  from the next launch. On Windows a launch at sign-in always starts in the
  tray.

On a Linux desktop that shows no tray icons, such as stock GNOME, closing the
window minimizes GAIA instead, with your model still loaded. Click GAIA in the
dock to bring it back, or in the Activities overview where no dock is on screen
(Fedora). To quit, right-click it there and choose Quit. **Start in
the tray** stays off there, because there's no tray to open the window from.
No extension is needed. GAIA doesn't appear under GNOME's **Background Apps**:
that list shows Flatpak apps only.

## Close, quit and restart

Chats, documents and schedules are saved on disk as you go. What happens to work in progress depends on what stopped:

| What happened | A reply being written | A document being indexed |
| - | - | - |
| You switch chats, open Memory or Scheduled tasks, or close the browser tab | Keeps going; reopen the chat to watch it finish | Keeps going |
| You close the desktop window | Keeps going: the window hides to the tray (or, on a desktop with no tray, minimizes to the dock) and GAIA keeps running. With that turned off, closing quits (next row) | Keeps going |
| The desktop window stops working (its page crashed, or the PC ran out of memory) | Keeps going: GAIA says its window stopped working and offers **Reload window**, which brings the window back on the running GAIA, or **Quit GAIA** | Keeps going |
| You quit GAIA, it crashes, or the PC shuts down | Stops. On the next start the reply shows what it had written so far, which tools it had started, then "This answer was interrupted when GAIA closed. Send again to retry." A scheduled run cut short shows the same in its chat. | Stops. On the next start it shows as **Failed** with **Retry**, and "Indexing was interrupted when GAIA closed" under the document |

GAIA never re-runs an interrupted reply by itself: it may already have run tools, and running them twice is not safe. Send the message again to retry, or press **Try again** under the reply. While GAIA is still starting, Try again leaves the question and the reply as they are and says to try again in a moment.

## Keeping the PC awake

GAIA keeps the PC from idle-sleeping while a chat is working; see [Notifications](https://amd-gaia.ai/docs/guides/agent-ui/control.md#notifications) for the battery level it stops at. If the PC does sleep mid-reply, see [Long responses](https://amd-gaia.ai/docs/guides/agent-ui/chat.md#long-responses).

## Updates and installing a specific version

GAIA offers each new release and waits for you: auto-update is **off by default**.
Everything lives in **Settings → General → Updates** (desktop installer only):

* **Install updates automatically** — off by default. The Terminal UI follows the
  same setting.
* **Include release candidates** — off by default. On, GAIA also offers `vX.Y.Z-rcN`
  test builds; they still wait for you unless auto-update is on. A release
  candidate build is offered newer candidates either way.
* **Check for updates**, then **Update to vX** when one is waiting. The corner chip
  offers the same **Update now**.
* **Install a specific version…** — pick a recent release, newer or older
  (useful to step back from a regression). The app downloads it and restarts into
  it, asking first if an answer or indexing job is still running.

An update downloads in the background, usually only the parts that changed, and
installs with no setup wizard. Once it is ready, the corner chip offers the restart,
whenever suits you; quitting GAIA also installs it. The update carries the new
version's backend, so the first launch afterwards downloads nothing for it. A restart
that would leave no working app, such as one with no disk space, is refused with the
reason.

**On a Mac** the app can't install updates itself yet, because its builds aren't
signed with an Apple Developer ID ([#7061](https://github.com/amd/gaia/issues/7061)).
A new release still shows, with a **Download** link to its release page instead of
**Update now**; install the `.dmg` from there.

**Pinning:** after installing a specific version, GAIA stays on it and offers no
updates. The Updates section shows "Pinned to vX.Y.Z"; click **Unpin** to resume.

**Going back:** after an update, **Go back to GAIA vX** in the Updates section installs
the version you had before and pins it, so the update that went wrong isn't offered
again until you click **Unpin**. If the update fails to finish setting up or start
in the first three launches after it, GAIA offers the same button in that error box
or on the corner chip. It downloads the older version, so it needs an internet
connection, and keeps your chats, memory and goals.

Checks read the [GitHub releases](https://github.com/amd/gaia/releases) and take the
newest one on your channel that publishes this platform's update. When none does,
the Updates section says so rather than "up to date", and you install from the
releases page instead.

### Platform support

| Platform | Specific-version install and Go back |
| - | - |
| Windows (NSIS installer) | Full — download + reinstall works end-to-end |
| macOS | Not yet — releases don't publish the `.zip` the macOS updater installs from ([#5682](https://github.com/amd/gaia/issues/5682)); install the `.dmg` from [Releases](https://github.com/amd/gaia/releases) |
| 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](https://github.com/amd/gaia/releases) |

> [!NOTE]
>
> The version list only shows releases that have an installer for your current platform. Releases without a matching artifact are filtered out automatically.

## Uninstall

On Windows, uninstall via Windows Settings → Apps → Installed apps → GAIA. On Ubuntu, `sudo apt remove gaia-desktop`. [Uninstalling](https://amd-gaia.ai/docs/guides/install.md#uninstalling) covers every platform and what is kept.

> [tab] npm
>
> ```bash theme={null}
> npm uninstall -g @amd-gaia/agent-ui
> ```
>
> To also remove all GAIA data (sessions, config, downloaded models):
>
> ```bash theme={null}
> # macOS / Linux
> rm -rf ~/.gaia
>
> # Windows (PowerShell)
> Remove-Item -Recurse -Force "$env:USERPROFILE\.gaia"
> ```

> [tab] Python CLI
>
> ```bash theme={null}
> uv pip uninstall amd-gaia
> ```
>
> To also remove all GAIA data:
>
> ```bash theme={null}
> # macOS / Linux
> rm -rf ~/.gaia
>
> # Windows (PowerShell)
> Remove-Item -Recurse -Force "$env:USERPROFILE\.gaia"
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.