Development Setup

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 & Docker Compose

Docker Desktop or Docker Engine
Docker Compose v2+
At least 4GB of available RAM
10GB of free disk space

CLI Requirements

Node.js 20+
one package manager: npm, pnpm, or bun
Git

System Requirements

macOS, Linux, or Windows with WSL2
At least 8GB RAM (16GB recommended)
SSD storage for better performance

Install GAIA CLI

Verify installation:

gaia --help

First-Time Setup

Clone the repository

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

Run setup wizard

gaia init

In the wizard:

Choose Developer Mode (Local)
Choose your env setup method (Manual or Infisical)

Start development in Nx TUI

gaia dev

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

Run Modes

Command	Description
`gaia dev`	API + web in Nx TUI (developer mode)
`gaia dev full`	API + web + workers in Nx TUI (developer mode)
`gaia logs`	Stream logs for currently running services
`gaia status`	Health check for GAIA services
`gaia stop`	Stop services safely (GAIA-managed processes)
`gaia setup`	Re-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

gaia command not found

Reinstall globally, then open a new terminal session:

npm install -g @heygaia/cli
gaia --help

pnpm add -g @heygaia/cli
gaia --help

bun add -g @heygaia/cli
gaia --help

Docker services not starting

Check Docker is running:

docker ps

Then check GAIA service health:

gaia status

Need to reconfigure environment

From your repo root, run:

gaia setup

Next Steps

Commands Reference - Full command list
CLI Commands - GAIA CLI reference
Environment Variables - Configure your setup
Contributing - How to contribute

Getting Started

Self-Hosting

CLI

Contributing

Bot Development

Conventions

Who This Guide Is For

Open Source Contributors

Customizers

Prerequisites

Install GAIA CLI

First-Time Setup

Run Modes

Project Structure

Troubleshooting

Next Steps

​Who This Guide Is For

Open Source Contributors

Customizers

​Prerequisites

​Install GAIA CLI

​First-Time Setup

​Run Modes

​Project Structure

​Troubleshooting

​Next Steps

Who This Guide Is For

Prerequisites

Install GAIA CLI

First-Time Setup

Run Modes

Project Structure

Troubleshooting

Next Steps