Skip to main content
Install the gaia CLI, run gaia up, and finish setup in your browser.

Install and start

1

Install the CLI

The GAIA installer under the GAIA logo: Node.js, the GAIA CLI and Docker installed, setup files fetched, then Downloading GAIA at 52%, 1.5 of 2.7 GB with about 2 minutes left, and a row per image: web app done, the rest unpacking or downloading

The installer carries straight on into gaia up and downloads GAIA

2

Start GAIA

It checks Docker (and offers to install it), downloads GAIA into ~/gaia, writes the settings and starts everything. Git is not needed.
3

Finish in the browser

Open http://localhost:3000/setup, create the admin account and pick an AI provider.
New to this? The walkthrough shows every step with screenshots.

Everyday commands

Every flag and command is in the CLI reference.
Terminal output of gaia status: GAIA is running at its .local address; the web app, server, background jobs and proxy, and MongoDB, PostgreSQL, Redis, RabbitMQ and ChromaDB all checked; no bots yet; setup not finished, with the link to finish it

gaia status: every dependency and container

Update

Each CLI version ships one tested GAIA release. To get a newer GAIA, update the CLI first with the install command above, then run gaia update. If the download fails, nothing changes.

Something broke?

It checks Docker, containers, ports, every database, the web app, disk and memory, and prints a fix for each problem.
Terminal output of gaia doctor: Docker, ports, the 9 running containers, the API, each database, the web app, disk space, memory and the GAIA version all checked, and one warning that setup is not finished yet, with the link to finish it

gaia doctor on a fresh install, before the admin account exists

Good to know

GAIA opens one port. If it is busy, gaia up shows what uses it and suggests another. The choice is saved in packages/cli/selfhost/.env inside ~/gaia. To change it later, edit that file, then run gaia stop && gaia start.
Betas are early versions, numbered like 0.7.0-beta.1. Add GAIA_CHANNEL=beta to the install command, then run gaia up:
Expect rough edges, and run gaia backup first if you rely on the install.
  • packages/cli/selfhost/: the Compose files and proxy settings
  • Your files: apps/api/.env, apps/bots/.env, packages/cli/selfhost/.env and backups/
  • gaia-selfhost.json: the list of files that came with the release
Run the commands from inside this folder.
These were git checkouts. The next gaia update converts them: the tracked files and .git are removed, and your settings and backups stay. A checkout on a branch, or with local edits, is refused and pointed at gaia update --git.