​
Overview

Infisical is a secure secret management platform that GAIA uses to centrally manage environment variables and API keys. Instead of storing sensitive information in .env files, Infisical allows you to:

  • Centrally manage secrets across multiple environments
  • Secure access controls with role-based permissions
  • Audit logging for secret access and changes
  • Automatic secret rotation capabilities
  • Team collaboration with shared secret access

When Infisical is configured, it will override any local environment variables with the same names from your Infisical project.

​
How Infisical Works with GAIA

GAIA’s backend automatically loads secrets from Infisical during startup using the inject_infisical_secrets() function. Here’s the process:

  1. Authentication: Uses machine identity credentials to authenticate with Infisical
  2. Secret Retrieval: Fetches all secrets from your Infisical project
  3. Environment Injection: Overwrites local environment variables with Infisical secrets
  4. Application Startup: GAIA starts with the combined environment configuration

​
Setting Up Infisical

​
Step 1: Create an Infisical Account

  1. Visit app.infisical.com
  2. Sign up for a free account
  3. Create a new project for GAIA

​
Step 2: Create a Machine Identity

Machine identities allow GAIA to authenticate with Infisical automatically:

  1. Go to Project Settings → Access Control → Machine Identities
  2. Click Create Identity
  3. Configure the identity:
    • Name: gaia-backend
    • Role: Admin or Developer (with read access to secrets)
  4. Note down the Client ID and Client Secret

​
Step 3: Add Secrets to Infisical

Navigate to your project’s Secrets section and add all your environment variables:

Core Application

ENV=production
DEBUG=false
HOST=https://api.heygaia.io
FRONTEND_URL=https://heygaia.io

Database URLs

POSTGRES_URL=postgresql://user:pass@host:5432/db
MONGO_DB=mongodb://user:pass@host:27017/gaia
REDIS_URL=redis://user:pass@host:6379

AI API Keys

OPENAI_API_KEY=sk-your-openai-key
GEMINI_API_KEY=your-gemini-key
HUGGINGFACE_API_KEY=hf_your-hf-token

Integration APIs

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-secret
BING_API_KEY=your-bing-key

​
Step 4: Configure GAIA Backend

Add the Infisical configuration to your backend .env file:

# Infisical Configuration
INFISICAL_PROJECT_ID=your-project-id-from-infisical
INFISICAL_MACHINE_INDENTITY_CLIENT_ID=your-client-id
INFISICAL_MACHINE_INDENTITY_CLIENT_SECRET=your-client-secret

# Optional: Set environment (defaults to 'production')
ENV=development

The INFISICAL_PROJECT_ID, INFISICAL_MACHINE_INDENTITY_CLIENT_ID, and INFISICAL_MACHINE_INDENTITY_CLIENT_SECRET must be set in your local .env file - they cannot be stored in Infisical itself since they’re needed to authenticate with Infisical.

​
Environment Priority

GAIA loads environment variables in this order (later sources override earlier ones):

  1. System environment variables
  2. Local .env file variables
  3. Infisical secrets (highest priority)

This means:

  • ✅ Infisical secrets will override local .env variables
  • ✅ You can use local .env for development and Infisical for production
  • ✅ Critical secrets are managed centrally through Infisical

​
Development vs Production

​
Development Setup

For local development, you can choose between:

Option A: Use Infisical (Recommended for teams)

# backend/.env
ENV=development
INFISICAL_PROJECT_ID=your-dev-project-id
INFISICAL_MACHINE_INDENTITY_CLIENT_ID=your-client-id
INFISICAL_MACHINE_INDENTITY_CLIENT_SECRET=your-client-secret

Option B: Use Local Environment Variables

# backend/.env
ENV=development
# Add all your environment variables here
OPENAI_API_KEY=your-local-dev-key
# ... other variables

​
Production Setup

For production, always use Infisical:

# backend/.env (production)
ENV=production
INFISICAL_PROJECT_ID=your-prod-project-id
INFISICAL_MACHINE_INDENTITY_CLIENT_ID=your-prod-client-id
INFISICAL_MACHINE_INDENTITY_CLIENT_SECRET=your-prod-client-secret

​
Troubleshooting

​
Common Issues

​
Debug Mode

To debug Infisical integration, check the application logs during startup. The backend will log any Infisical connection issues.

​
Security Best Practices

Access Control

  • Use separate machine identities for different environments
  • Grant minimal required permissions
  • Regularly audit access logs

Secret Management

  • Use different secrets for dev/staging/production
  • Rotate secrets regularly
  • Never commit Infisical credentials to version control

Environment Separation

  • Use separate Infisical projects for each environment
  • Implement proper CI/CD secret injection
  • Monitor secret access patterns

Backup Strategy

  • Export secrets regularly for backup
  • Document secret recovery procedures
  • Have fallback authentication methods

​
Next Steps

Environment Variables

Configure your environment variables and learn about Infisical integration

Docker Setup

Deploy GAIA with Docker Compose and Infisical secrets

For more detailed Infisical documentation, visit the official Infisical docs.