Skip to main content

​
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.

​
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

Solution: Add the INFISICAL_PROJECT_ID to your .env file. You can find this in your Infisical project settings.
Solution: - Verify your INFISICAL_MACHINE_INDENTITY_CLIENT_ID and INFISICAL_MACHINE_INDENTITY_CLIENT_SECRET - Ensure the machine identity has proper permissions - Check that the identity is enabled
Solution: - Verify the environment slug matches (development/production) - Check that secrets exist in the correct Infisical project - Ensure the machine identity has read access to secrets
Solution: This is expected behavior. Infisical secrets have the highest priority and will override local variables with the same name.

​
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, and regularly audit access logs.

Secret Management

Use different secrets for dev/staging/production, rotate secrets regularly, and never commit Infisical credentials to version control.

Environment Separation

Use separate Infisical projects for each environment, implement proper CI/CD secret injection, and monitor secret access patterns.

Backup Strategy

Export secrets regularly for backup, document secret recovery procedures, and 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.