Download and install
Get the installer
Go to heygaia.io/download and pick the installer for your OS:
- macOS:
.dmg(Intel or Apple Silicon) - Windows:
.exeinstaller or portable.exe - Linux:
.AppImage,.deb, or.rpm
Run the installer
Open the downloaded file and follow the prompts. On macOS, drag GAIA into Applications. On Windows, you can pick a custom install location.
What you get
- A dedicated window with a clean title bar (hidden inset style on macOS). External links open in your default browser, so the GAIA window stays focused on your work.
- Automatic updates. Every launch checks for updates in the background. When one is ready, you get a prompt, restart right away or wait until you next quit.
- A splash screen on startup while the app’s internal server gets ready, usually a few seconds.
Updates come through GitHub Releases. If your company network blocks GitHub,
add
github.com to your allowlist so updates can get through.Desktop vs. web
The desktop app renders the same UI as heygaia.io, every feature is available in both.| Feature | Web | Desktop |
|---|---|---|
| Chat, workflows, calendar, integrations | Yes | Yes |
| Runs in a browser tab | Yes | No |
| Native OS authentication (deep link) | No | Yes |
| Automatic updates | N/A (always latest) | Yes |
| Works offline (cached content) | Partial | Partial |
| Dedicated window with minimal chrome | No | Yes |
Available on Linux as .deb / .rpm / .AppImage | N/A | Yes |
Power-user tips
You can skip this section unless you want to fine-tune your setup or fix something.Keep it running
On macOS, closing all windows keeps the app alive in the Dock. Click the
icon to bring it back instantly.
Use keyboard shortcuts
Every shortcut from the web app works here too. Press
/ in
chat to open the command palette.Check your version
Reporting a bug? Find your app version in Settings and share it with
support so they can reproduce the issue on your exact build.
Reset if stuck
If the app won’t load after an update, delete the app data folder and
relaunch. On macOS:
~/Library/Application Support/GAIA. On Windows:
%APPDATA%/GAIA. On Linux: ~/.config/GAIA.Troubleshooting
Blank screen after launch: The internal server may still be starting. Wait up to 15 seconds, then quit and relaunch. Check that nothing else is using ports 5174–5180. “Update available” prompt never appears: Make sure your network allows outbound HTTPS togithub.com. Corporate proxies or firewalls can block the update check.
OAuth sign-in doesn’t redirect back to the app: The gaia:// protocol needs to be registered with your OS. On Linux, the .deb and .rpm installers handle this automatically; if you’re using the AppImage, launch the app once so it can register the protocol handler.