Skip to main content

​
CLI-Based Setup

The GAIA CLI provides the easiest way to set up a self-hosted GAIA instance. It handles repository cloning, tool installation, environment configuration, and service startup through an interactive wizard.
For installation instructions, see CLI Installation. For the full command reference, see CLI Commands.

​
Quick Start

# Install the CLI
curl -fsSL https://heygaia.io/install.sh | sh

# Run the setup wizard
gaia init

# Clone a specific branch
gaia init --branch develop

​
What the Wizard Does

The gaia init command walks you through:
1

Prerequisites Check

Verifies Git, Docker, and Mise are installed. Installs Mise automatically if missing. Checks for port conflicts and suggests alternatives.
2

Repository Setup

Clones the GAIA repository to your chosen directory with progress tracking.
3

Tool Installation

Installs all required development tools (Node.js, Python, uv, Nx) via Mise.
4

Environment Configuration

Choose between Self-Host (Docker) or Developer Mode (Local), then configure environment variables either:
  • Manually: Interactive prompts for each variable with descriptions and defaults
  • Via Infisical: Enter your Infisical credentials for secret management
5

Project Setup

Runs mise setup to install all dependencies, start Docker services, and seed the database.
6

Service Startup

If services aren’t already running, optionally starts all services immediately. If they’re already running, the wizard detects this and skips to completion.

​
Already Have the Repo?

If you’ve already cloned GAIA and just need to configure it, use gaia setup instead: 
cd /path/to/gaia
gaia setup
This skips cloning and tool installation, going straight to environment configuration and project setup.

​
Managing Services After Setup

Once setup is complete, manage your GAIA instance with: 
gaia start    # Start all services
gaia stop     # Stop all services
gaia status   # Check service health
gaia setup    # Reconfigure environment
See CLI Commands for full details on each command.

​
Environment Variable Auto-Discovery

The CLI automatically discovers environment variables from the codebase at runtime. When a developer adds a new variable to the API settings or web .env file, the CLI picks it up automatically — no CLI updates needed.
  • API variables: Extracted from Python settings files using AST parsing
  • Web variables: Parsed from apps/web/.env at runtime

​
Monitoring Logs (Developer Mode)

In developer mode, gaia start runs services in the background. Logs are written to dev-start.log in the repo root — monitor them with: 
tail -f dev-start.log

​
Port Conflict Handling

If required ports are already in use, the CLI detects the conflict, shows which process is using the port, and suggests an alternative port. Infrastructure URLs in your .env files are automatically updated to use the alternative ports. Port overrides are saved to infra/docker/.env inside your GAIA repo and persist across gaia start/gaia stop cycles — no need to re-run setup. gaia status automatically uses the same overridden ports. To change port assignments after setup, edit infra/docker/.env directly:
VariableServiceDefault
API_HOST_PORTAPI8000
WEB_HOST_PORTWeb3000
POSTGRES_HOST_PORTPostgreSQL5432
REDIS_HOST_PORTRedis6379
MONGO_HOST_PORTMongoDB27017
RABBITMQ_HOST_PORTRabbitMQ5672
CHROMA_HOST_PORTChromaDB8080
Restart services after editing: gaia stop && gaia start