Set up GAIA for development

Go from a fresh machine to a running GAIA in a few steps. Each step ends with what you should see.

Only want to run GAIA? Use Self-Hosting instead.

What you need

Tool	Why	Get it
Git	Clone the code	git-scm.com
mise	Installs the pinned Node, Python, pnpm, uv and Nx, and runs every task	mise.jdx.dev, then activate it in your shell
Docker	Runs the databases (MongoDB, PostgreSQL, Redis, ChromaDB, RabbitMQ). Your code runs outside Docker	On Linux `mise bootstrap` installs it. On macOS: Docker Desktop or OrbStack

Works on macOS, Linux and Windows (WSL2). Plan for 16 GB of RAM and 10 GB of disk. mise installs Node, Python and pnpm for you.

Clone the repository

git clone https://github.com/theexperiencecompany/gaia.git
cd gaia

Want to open a pull request? Fork first and clone your fork. See Open a pull request.You should see a gaia folder with apps/, libs/ and mise.toml.

Set up the machine

mise trust
mise bootstrap

mise bootstrap installs git and curl, installs Docker on Linux the way gaia up does (Docker’s own script; it asks for your sudo password), installs the pinned tools into mise’s own folder, then creates your .env files, installs JavaScript and Python packages, downloads the voice models and starts the databases. Your system Node and Python are untouched. On macOS, install and open OrbStack or Docker Desktop first. The first run takes several minutes; mise bootstrap --dry-run shows what it would do.You should see Setup complete! at the end, and docker ps lists the database containers. Run mise run bootstrap later to redo only the project part.

Add your configuration

Pick the option that matches you.

Outside contributor
GAIA team member

Open apps/api/.env and set two values:

AUTH_MODE=local
OPENROUTER_API_KEY=sk-or-...

AUTH_MODE=local uses built-in sign-in. The default needs WorkOS keys (a login service) that you don’t have, so the API won’t start without this.
One AI key: OPENROUTER_API_KEY, GOOGLE_API_KEY or OPENAI_API_KEY. No key? Use mise dev --sim in the next step for scripted replies.

Everything else is optional. See Environment Variables.

Team secrets live in Infisical. You don’t edit .env.

brew install infisical/get-cli/infisical   # other platforms: infisical.com/docs/cli/overview
infisical login

From now on, put mise infisical -- in front of a task, like mise infisical -- dev --agent. See Infisical Setup.

Start GAIA

mise dev --agent

Team members run mise infisical -- dev --agent.This starts the API (port 8000) and the web app (port 3000) with hot reload. --agent skips login: every request is the dev user dev@gaia.local. It refuses to run in production.You should see two tasks, api and web. Then curl http://localhost:8000/health returns "status":"online".Other ways to start GAIA: Run GAIA locally.

Create your development user

The dev user must exist first. In a second terminal:

mise seed

Run it once. It adds sample todos and conversations.You should see seeded dev@gaia.local. Skip it and every request fails with a 401.

Open the app

Open http://localhost:3000/c and send a message.You should see a signed-in chat and a reply. With --sim the reply is scripted.

Make a change

Edit text under apps/web/src/ or save a file under apps/api/app/. Both reload on their own. Changed a .env file? Stop mise dev with Ctrl+C and start it again.

Check it before you push

Install the commit hooks once:

mise run pre-commit:install

Then run what matches your change:

mise run lint         # TypeScript and the Nx projects (Biome)
mise run lint:py      # all Python (Ruff), as CI runs it
mise run type-check   # TypeScript and Python types
mise test:one tests/unit/path/to/test_file.py   # API tests
nx test web           # TypeScript tests of the project you changed

mise test:one paths are relative to apps/api/. Run only the tests you touched; CI runs the rest. See Testing. Next, use a conventional commit message like fix(web): keep the draft when switching chats and open a pull request against master. See Open a pull request.

If something goes wrong

mise: command not found, or a task is missing

mise isn’t activated in this shell. Follow mise’s activation guide, open a new terminal and run mise trust && mise install. Answer yes if it asks to trust another mise.toml.

pnpm: command not found

Run corepack enable once.

The API exits with 'WORKOS_API_KEY is required when AUTH_MODE=workos'

Add AUTH_MODE=local to apps/api/.env, then start mise dev --agent again.

Every request returns 401 'No GAIA user exists'

Run mise seed while the API is running.

'ERROR: API port 8000 is already in use by PID ...'

Stop the process using it, or give this checkout its own ports with mise run wt:env. See Run GAIA locally.

The databases don't start

Check that Docker is running, then:

docker compose -f infra/docker/docker-compose.yml ps

Docker for development lists each service and its port.

Start over from a clean configuration

Delete apps/api/.env and run mise run setup:env to copy the template again.

Still stuck? Ask in Discord or open an issue.

Project tour

Where each part of GAIA lives.

Start here

Everyday work

Go deeper

Reference

What you need

Make a change

Check it before you push

If something goes wrong

Next

Project tour

​What you need

​Make a change

​Check it before you push

​If something goes wrong

​Next

Project tour

What you need

Make a change

Check it before you push

If something goes wrong

Next