Skip to main content

​
Who This Guide Is For

Open Source Contributors

Developers who want to contribute by fixing bugs, adding features, or improving documentation.

Customizers

Developers who want to modify GAIA for their specific use cases or integrate with custom systems.

​
Prerequisites

  • Docker Desktop or Docker Engine
  • Docker Compose v2+
  • At least 4GB of available RAM
  • 10GB of free disk space
  • Node.js 20+
  • one package manager: npm, pnpm, or bun
  • Git
  • macOS, Linux, or Windows with WSL2
  • At least 8GB RAM (16GB recommended)
  • SSD storage for better performance

​
Install GAIA CLI

npm install -g @heygaia/cli
Verify installation: 
gaia --help

​
First-Time Setup

1

Clone the repository

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

Run setup wizard

gaia init
In the wizard:
  • Choose Developer Mode (Local)
  • Choose your env setup method (Manual or Infisical)
3

Start development in Nx TUI

gaia dev
This runs mise dev for you and opens the Nx TUI in your current terminal.

​
Run Modes

CommandDescription
gaia devAPI + web in Nx TUI (developer mode)
gaia dev fullAPI + web + workers in Nx TUI (developer mode)
gaia logsStream logs for currently running services
gaia statusHealth check for GAIA services
gaia stopStop services safely (GAIA-managed processes)
gaia setupRe-run setup for an existing clone

​
Project Structure

gaia/
├── apps/
│   ├── api/           # FastAPI backend (Python)
│   ├── web/           # Next.js frontend (TypeScript)
│   ├── desktop/       # Electron desktop app
│   ├── mobile/        # React Native mobile app
├── docs/              # Documentation
├── libs/              # Shared libraries
├── infra/
│   └── docker/        # Docker Compose files
├── config/            # Build configuration
├── mise.toml          # Root task configuration
└── nx.json            # Nx build configuration

​
Troubleshooting

Reinstall globally, then open a new terminal session:
npm install -g @heygaia/cli
gaia --help
Check Docker is running:
docker ps
Then check GAIA service health:
gaia status
From your repo root, run:
gaia setup

​
Next Steps