Skip to main content
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: 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: 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 for the battery level it stops at. If the PC does sleep mid-reply, see 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). 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 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

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 covers every platform and what is kept.
To also remove all GAIA data (sessions, config, downloaded models):