> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heygaia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Infisical Setup

> Configure secure secret management with Infisical for GAIA

## 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

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

## 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](https://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:

```bash theme={null}
# Infisical Configuration
INFISICAL_PROJECT_ID=your-project-id-from-infisical
INFISICAL_MACHINE_IDENTITY_CLIENT_ID=your-client-id
INFISICAL_MACHINE_IDENTITY_CLIENT_SECRET=your-client-secret

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

<Warning>
  The `INFISICAL_PROJECT_ID`, `INFISICAL_MACHINE_IDENTITY_CLIENT_ID`, and
  `INFISICAL_MACHINE_IDENTITY_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.
</Warning>

## 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)

```bash theme={null}
# apps/api/.env
ENV=development
INFISICAL_PROJECT_ID=your-dev-project-id
INFISICAL_MACHINE_IDENTITY_CLIENT_ID=your-client-id
INFISICAL_MACHINE_IDENTITY_CLIENT_SECRET=your-client-secret
```

**Option B: Use Local Environment Variables**

```bash theme={null}
# apps/api/.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**:

```bash theme={null}
# apps/api/.env (production)
ENV=production
INFISICAL_PROJECT_ID=your-prod-project-id
INFISICAL_MACHINE_IDENTITY_CLIENT_ID=your-prod-client-id
INFISICAL_MACHINE_IDENTITY_CLIENT_SECRET=your-prod-client-secret
```

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="InfisicalConfigError: INFISICAL_PROJECT_ID is missing">
    **Solution**: Add the `INFISICAL_PROJECT_ID` to your `.env` file. You can find this in your Infisical project settings.
  </Accordion>

  {" "}

  <Accordion title="Authentication failed">
    **Solution**: - Verify your `INFISICAL_MACHINE_IDENTITY_CLIENT_ID` and
    `INFISICAL_MACHINE_IDENTITY_CLIENT_SECRET` - Ensure the machine identity has
    proper permissions - Check that the identity is enabled
  </Accordion>

  {" "}

  <Accordion title="Secrets not loading">
    **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
  </Accordion>

  <Accordion title="Local variables not being overridden">
    **Solution**: This is expected behavior. Infisical secrets have the highest priority and will override local variables with the same name.
  </Accordion>
</AccordionGroup>

### Debug Mode

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

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Access Control">
    Use separate machine identities for different environments, grant minimal
    required permissions, and regularly audit access logs.
  </Card>

  <Card title="Secret Management">
    Use different secrets for dev/staging/production, rotate secrets regularly,
    and never commit Infisical credentials to version control.
  </Card>

  <Card title="Environment Separation">
    Use separate Infisical projects for each environment, implement proper CI/CD
    secret injection, and monitor secret access patterns.
  </Card>

  <Card title="Backup Strategy">
    Export secrets regularly for backup, document secret recovery procedures,
    and have fallback authentication methods.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Environment Variables" href="/configuration/environment-variables">
    Configure your environment variables and learn about Infisical integration
  </Card>

  <Card title="Docker Setup" href="/self-hosting/docker-setup">
    Deploy GAIA with Docker Compose and Infisical secrets
  </Card>
</CardGroup>

<Note>
  For more detailed Infisical documentation, visit the [official Infisical
  docs](https://infisical.com/docs).
</Note>