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

Development Tools

Git (for version control)
mise (task runner and tool manager)
For mobile development: Xcode (iOS) and/or Android Studio (Android)

System Requirements

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

Install mise

mise is required for all GAIA development.

macOS (Homebrew)
macOS/Linux (curl)
Windows

brew install mise

curl https://mise.run | sh

Add to PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

winget install jdx.mise

Or via scoop/choco:

scoop install mise
# or
choco install mise

Activate mise

Add mise activation to your shell:

zsh
bash
fish

echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

echo 'eval "$(mise activate bash)"' >> ~/.bashrc
source ~/.bashrc

echo 'mise activate fish | source' >> ~/.config/fish/config.fish

Verify mise is working:

mise doctor

Setup

Automated (Recommended)
Manual Setup

Clone the repository

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

Create environment files

cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
cp apps/mobile/.env.example apps/mobile/.env

Edit apps/api/.env with your secrets. See Environment Variables.

Run setup

mise setup

This will:

Check .env files exist
Start Docker services
Install Python 3.12 via mise
Install API dependencies (uv sync)
Install Node 22 via mise
Install web dependencies (pnpm install)
Install mobile dependencies (pnpm install)
Install desktop dependencies (pnpm install)
Install voice agent dependencies
Seed AI models

Start development

mise dev

This starts:

Docker services (databases, Redis, etc.)
API server on http://localhost:8000
Web app on http://localhost:3000

For more control over the setup process.

Clone and setup environment

git clone https://github.com/heygaia/gaia.git
cd gaia
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
cp apps/mobile/.env.example apps/mobile/.env

Start Docker services

docker compose -f infra/docker/docker-compose.yml up -d

Wait for all services to be healthy:

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

Install API dependencies

cd apps/api
uv sync
cd ../..

Install web dependencies

cd apps/web
pnpm install
cd ../..

Start development servers

In separate terminals:

# Terminal 1: API
cd apps/api
mise dev

# Terminal 2: Web
cd apps/web
mise dev

Development Commands

Command	Description
`mise dev`	Start API + web (recommended)
`mise dev:api`	API server only
`mise dev:web`	Web app only
`mise dev:full`	API + web + ARQ worker
`mise lint`	Lint all code
`mise format`	Format all code
`mise test`	Run all tests

See Commands Reference for the complete list.

Project Structure

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

Troubleshooting

mise command not found

Ensure mise is installed and activated in your shell:

mise doctor

If not activated, re-run the activation step for your shell.

Docker services not starting

Check Docker is running: bash docker ps Check for port conflicts:

lsof -i :5432 # PostgreSQL lsof -i :6379 # Redis lsof -i :8000 # API

Missing environment variables

Ensure .env files exist: bash ls apps/api/.env apps/web/.env If missing, copy from examples: bash cp apps/api/.env.example apps/api/.env cp apps/web/.env.example apps/web/.env

Python/Node version issues

mise manages tool versions. Let it install them:

mise install

Check versions:

mise current

Next Steps

Commands Reference - All available commands
Environment Variables - Configure your setup
Contributing - How to contribute
Code Style - Coding standards

Get Started

Self-Hosting

Developers

Configuration

Development Setup

Who This Guide Is For

Open Source Contributors

Customizers

Prerequisites

Install mise

Activate mise

Setup

Development Commands

Project Structure

Troubleshooting

Next Steps

Get Started

Self-Hosting

Developers

Configuration

​Who This Guide Is For

Open Source Contributors

Customizers

​Prerequisites

​Install mise

​Activate mise

​Setup

​Development Commands

​Project Structure

​Troubleshooting

​Next Steps

Who This Guide Is For

Prerequisites

Install mise

Activate mise

Setup

Development Commands

Project Structure

Troubleshooting

Next Steps