Prerequisites¶

Before you start building with Gaia, make sure you have the following tools, accounts, and knowledge in place.

Platform Requirements¶

Cohesity Cluster with Gaia Enabled¶

You need access to a Cohesity cluster that has the Gaia feature enabled. This is available through:

• Cohesity DataProtect with the Gaia add-on
• Cohesity DataHawk with Gaia capabilities
• Cohesity Cloud Services (Helios-managed clusters)

A Gaia API Key¶

All Gaia API calls require an API key for authentication. To obtain one:

1. Log in to the Cohesity UI (either the cluster UI or Helios at helios.cohesity.com).
2. Navigate to Settings → Access Management → API Keys.
3. Click Generate API Key.
4. Give it a descriptive name (e.g., gaia-dev-myname).
5. Copy the key immediately — it won't be shown again.

Development Environment¶

Python 3.10+¶

The backend and SDK require Python 3.10 or later (for match statements, X | Y union types, and modern asyncio).

brew install python@3.12
python3.12 --version

sudo apt update && sudo apt install python3.12 python3.12-venv
python3.12 --version

# Download from https://www.python.org/downloads/
# Or use winget:
winget install Python.Python.3.12
python --version

Node.js 18+¶

The frontend build tooling requires Node.js 18 or later.

brew install node@20
node --version && npm --version

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs
node --version && npm --version

nvm install 20
nvm use 20
node --version

Code Editor¶

Any editor works, but we recommend Cursor IDE for AI-assisted development. Cursor understands your codebase and can help you write Gaia integration code faster with inline suggestions and chat.

Knowledge Prerequisites¶

You don't need to be an expert, but familiarity with the following will help:

Python Packages¶

The backend uses the following key packages:

Setting Up the Python Environment¶

# Create a project directory
mkdir gaia-app && cd gaia-app

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install backend dependencies
pip install httpx pydantic fastapi uvicorn python-dotenv

# Or install from a requirements.txt
cat > requirements.txt << 'EOF'
httpx>=0.27.0
pydantic>=2.0
fastapi>=0.110.0
uvicorn[standard]>=0.29.0
python-dotenv>=1.0.0
EOF

pip install -r requirements.txt

# Clone the repository (if you haven't already)
git clone https://github.com/cohesity/build-with-gaia.git
cd build-with-gaia

# Install the SDK from the project root
pip install -e sdk/python/

Node.js Packages¶

The frontend uses the following key packages:

Setting Up the Frontend¶

# Create a new Vite + React project
npm create vite@latest frontend -- --template react-ts
cd frontend

# Install dependencies
npm install

# Install additional packages
npm install zustand react-router-dom

# Verify the dev server starts
npm run dev

Environment Configuration¶

Create a .env file in your backend project root:

# .env
GAIA_API_KEY=your-api-key-here
GAIA_BASE_URL=https://helios.cohesity.com/v2/mcm/gaia
GAIA_VERIFY_SSL=true

# Optional: security context for multi-tenant setups
# GAIA_SECURITY_CTX=your-security-context

echo ".env" >> .gitignore

Verify Your Setup¶

Run this quick check to make sure everything is working:

#!/usr/bin/env python3
"""Verify your Gaia development environment."""

import sys
import importlib
from dotenv import load_dotenv

# Load variables from .env so this script works without manually exporting them
load_dotenv()

print(f"Python: {sys.version}")

required = ["httpx", "pydantic", "fastapi", "uvicorn", "dotenv"]
for pkg in required:
    try:
        mod = importlib.import_module(pkg)
        version = getattr(mod, "__version__", "installed")
        print(f"  ✓ {pkg} ({version})")
    except ImportError:
        print(f"  ✗ {pkg} — not installed (pip install {pkg})")

# Check for the Gaia SDK
try:
    from gaia_sdk import GaiaClient
    print("  ✓ gaia_sdk (available)")
except ImportError:
    print("  ⓘ gaia_sdk — not installed (optional: pip install -e sdk/python/)")

print("\nEnvironment variables:")
import os
for var in ["GAIA_API_KEY", "GAIA_BASE_URL"]:
    val = os.environ.get(var)
    if val:
        display = val[:8] + "..." if var == "GAIA_API_KEY" else val
        print(f"  ✓ {var} = {display}")
    else:
        print(f"  ✗ {var} — not set")

Save this as check_env.py. Make sure your virtual environment is active, then run it:

# Activate your virtual environment first
source .venv/bin/activate   # On Windows: .venv\Scripts\activate

python check_env.py

Expected output:

Python: 3.12.x
  ✓ httpx (0.27.x)
  ✓ pydantic (2.x.x)
  ✓ fastapi (0.110.x)
  ✓ uvicorn (0.29.x)
  ✓ dotenv (1.0.x)
  ✓ gaia_sdk (available)

Environment variables:
  ✓ GAIA_API_KEY = abcd1234...
  ✓ GAIA_BASE_URL = https://helios.cohesity.com/v2/mcm/gaia

Next Steps¶

You're all set! Continue to:

• Authentication — Learn how API key auth works.
• Your First API Call — Talk to Gaia.