> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/thiagofinch/mega-brain/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure API keys and customize Mega Brain for your workflow

## Environment Configuration

Mega Brain uses a `.env` file to store API keys and configuration. This file is automatically generated during setup and should never be committed to version control.

<Warning>
  **Never commit your `.env` file to git!** It contains sensitive API keys. The file is automatically added to `.gitignore` during installation.
</Warning>

## API Keys Overview

Mega Brain integrates with multiple services for different capabilities:

<CardGroup cols={3}>
  <Card title="Required" icon="circle-exclamation" color="#ef4444">
    **OpenAI**

    Essential for video/audio transcription
  </Card>

  <Card title="Recommended" icon="circle-check" color="#f59e0b">
    **Voyage AI**

    Enables high-quality semantic search
  </Card>

  <Card title="Optional" icon="circle" color="#6b7280">
    **Everything else**

    Advanced features and integrations
  </Card>
</CardGroup>

## Required API Keys

### OpenAI API Key

<Note>
  **Required for:** Video/audio transcription via Whisper API

  **Used by:** `/ingest` command when processing YouTube videos, podcasts, or audio files
</Note>

<Steps>
  <Step title="Get your API key">
    1. Go to [OpenAI Platform](https://platform.openai.com/api-keys)
    2. Sign in or create an account
    3. Click "Create new secret key"
    4. Copy the key (starts with `sk-`)
  </Step>

  <Step title="Add to .env file">
    Open your `.env` file and add:

    ```bash theme={null}
    OPENAI_API_KEY=sk-your-actual-key-here
    ```
  </Step>

  <Step title="Verify the key">
    Test your configuration:

    ```bash theme={null}
    npx mega-brain-ai status
    ```

    You should see:

    ```
    API Keys
      OPENAI_API_KEY ..... OK  sk-...
    ```
  </Step>
</Steps>

**Pricing:** Pay-as-you-go. Whisper transcription costs approximately:

* \$0.006 per minute of audio
* A 1-hour video costs \~\$0.36 to transcribe

**What happens without it:**

* Video/audio ingestion will fail
* PDF and text ingestion still works
* You can manually place transcripts in `inbox/`

## Recommended API Keys

### Voyage AI API Key

<Note>
  **Required for:** High-quality semantic embeddings for RAG (Retrieval Augmented Generation)

  **Used by:** Knowledge search, similarity matching, and agent context retrieval
</Note>

<Steps>
  <Step title="Get your API key">
    1. Go to [Voyage AI Dashboard](https://dash.voyageai.com)
    2. Sign up for an account
    3. Navigate to API Keys section
    4. Create a new API key
  </Step>

  <Step title="Add to .env file">
    ```bash theme={null}
    VOYAGE_API_KEY=pa-your-actual-key-here
    ```
  </Step>

  <Step title="Configure embedding model (optional)">
    Voyage AI offers different embedding models. The default is `voyage-3-lite`.

    To use a different model, you can configure it in your processing scripts.
  </Step>
</Steps>

**Pricing:** Free tier available, then pay-as-you-go

* 100M tokens/month free
* \~\$0.02 per 1M tokens after that

**What happens without it:**

* System falls back to mock vectors (significantly degraded quality)
* Semantic search accuracy drops
* Agent context retrieval is less precise
* Processing still works, but outputs are less intelligent

## Optional API Keys

### Google OAuth (Drive Integration)

<Note>
  **Required for:** Importing transcriptions directly from Google Drive or Google Docs

  **Used by:** `/ingest` command when processing Google Drive URLs
</Note>

<Steps>
  <Step title="Create OAuth credentials">
    1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
    2. Create a new project or select existing
    3. Enable Google Drive API and Google Docs API
    4. Create OAuth 2.0 credentials
    5. Add authorized redirect URIs (typically `http://localhost:8080`)
  </Step>

  <Step title="Add to .env file">
    ```bash theme={null}
    GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
    GOOGLE_CLIENT_SECRET=your-client-secret
    ```
  </Step>
</Steps>

**What happens without it:**

* Google Drive ingestion won't work
* You'll need to manually download files from Drive
* Direct ingestion from Google Docs is unavailable

### Anthropic API Key

<Note>
  **Required for:** Direct Claude API access (separate from Claude Code)

  **Used by:** Standalone scripts and batch processing operations
</Note>

```bash theme={null}
ANTHROPIC_API_KEY=sk-ant-your-actual-key-here
```

Get your key from [Anthropic Console](https://console.anthropic.com).

### Voice & Audio Features

These keys enable advanced voice interaction features:

<CardGroup cols={2}>
  <Card title="ElevenLabs" icon="microphone">
    **Text-to-Speech**

    ```bash theme={null}
    ELEVENLABS_API_KEY=your-key
    ELEVENLABS_VOICE_ID=your-voice-id
    ELEVENLABS_NARRATOR_VOICE_ID=narrator-id
    ELEVENLABS_TERMINAL_VOICE_ID=terminal-id
    ```

    [Get API key](https://elevenlabs.io)
  </Card>

  <Card title="Deepgram" icon="waveform">
    **Speech-to-Text**

    ```bash theme={null}
    DEEPGRAM_API_KEY=your-key
    ```

    [Get API key](https://deepgram.com)
  </Card>

  <Card title="VAPI" icon="phone">
    **Voice AI Platform**

    ```bash theme={null}
    VAPI_API_KEY=your-key
    VAPI_ASSISTANT_ID=assistant-id
    VAPI_VOICE_ID_V5_BR=voice-id
    VAPI_WEBHOOK_SECRET=webhook-secret
    ```

    [Get API key](https://vapi.ai)
  </Card>
</CardGroup>

### Database & Storage

#### Supabase (Email Validation)

```bash theme={null}
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_PUBLISHABLE_KEY=your-publishable-key
SUPABASE_SERVICE_KEY=your-service-key
```

Used for MoneyClub email validation in Pro version. Get keys from [Supabase Dashboard](https://supabase.com) → Settings → API.

### Integration Services (MCP)

These services enable integrations with productivity tools:

```bash theme={null}
# N8N Automation
N8N_API_URL=https://your-instance.app.n8n.cloud
N8N_API_KEY=your-n8n-api-key

# Project Management
CLICKUP_PERSONAL_TOKEN=your-clickup-token
MIRO_TOKEN=your-miro-token
NOTION_TOKEN=your-notion-token

# Design Tools
FIGMA_API_KEY=your-figma-api-key
```

<CardGroup cols={2}>
  <Card title="N8N" icon="workflow" href="https://n8n.io">
    Workflow automation and webhook handling
  </Card>

  <Card title="ClickUp" icon="check-square" href="https://clickup.com">
    Task and project management integration
  </Card>

  <Card title="Miro" icon="diagram-project" href="https://miro.com">
    Collaborative whiteboarding
  </Card>

  <Card title="Notion" icon="book" href="https://notion.so">
    Documentation and knowledge management
  </Card>

  <Card title="Figma" icon="pen-nib" href="https://figma.com">
    Design file access and integration
  </Card>
</CardGroup>

### Premium Distribution

```bash theme={null}
# GitHub PAT for accessing premium repository (Pro users only)
PREMIUM_REPO_TOKEN=ghp_your-github-personal-access-token
```

Required for upgrading to Pro version. Needs `contents:read` permission on the `mega-brain-premium` repository.

## Configuration File Structure

Your complete `.env` file should look like this:

<CodeGroup>
  ```bash Minimal Configuration theme={null}
  # Required
  OPENAI_API_KEY=sk-your-key-here

  # Recommended
  VOYAGE_API_KEY=pa-your-key-here
  ```

  ```bash Full Configuration theme={null}
  #==================================
  # Mega Brain - Environment Variables
  #==================================

  # Core Services (Required)
  OPENAI_API_KEY=sk-your-key-here

  # RAG & Embeddings (Recommended)
  VOYAGE_API_KEY=pa-your-key-here

  # Google Drive Integration (Optional)
  GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
  GOOGLE_CLIENT_SECRET=your-client-secret

  # Claude API (Optional)
  ANTHROPIC_API_KEY=sk-ant-your-key-here

  # Voice Features (Optional)
  ELEVENLABS_API_KEY=your-key
  ELEVENLABS_VOICE_ID=your-voice-id
  DEEPGRAM_API_KEY=your-key
  VAPI_API_KEY=your-key
  VAPI_ASSISTANT_ID=your-assistant-id

  # Database (Optional)
  SUPABASE_URL=https://your-project.supabase.co
  SUPABASE_ANON_KEY=your-key
  SUPABASE_SERVICE_KEY=your-key

  # MCP Services (Optional)
  N8N_API_URL=https://your-instance.app.n8n.cloud
  N8N_API_KEY=your-key
  CLICKUP_PERSONAL_TOKEN=your-token
  MIRO_TOKEN=your-token
  FIGMA_API_KEY=your-key
  NOTION_TOKEN=your-token

  # Premium (Pro Users Only)
  PREMIUM_REPO_TOKEN=ghp_your-token
  ```
</CodeGroup>

## Setup Wizard

### Interactive Configuration

The easiest way to configure Mega Brain is using the interactive setup wizard:

```bash theme={null}
npx mega-brain-ai setup
```

The wizard will:

<Steps>
  <Step title="Check prerequisites">
    Verify Node.js 18+ and Python 3.10+ are installed
  </Step>

  <Step title="Install dependencies">
    Automatically install Python packages from `requirements.txt`:

    * PyYAML >= 6.0
  </Step>

  <Step title="Configure API keys">
    Prompt you for each API key with helpful context:

    * Which keys are required vs optional
    * What each key is used for
    * Where to get each key
  </Step>

  <Step title="Validate keys">
    Test API connectivity for OpenAI and Voyage AI
  </Step>

  <Step title="Generate .env">
    Create or update your `.env` file with the provided keys
  </Step>

  <Step title="Show summary">
    Display a complete setup summary with next steps
  </Step>
</Steps>

### Example Setup Session

```bash theme={null}
$ npx mega-brain-ai setup

╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║   ███   ███ ███████ ██████   █████                          ║
║   ████ ████ ██      ██      ██   ██                         ║
║   ██ ███ ██ █████   ██  ███ ███████                         ║
║   ██     ██ ██      ██   ██ ██   ██                         ║
║   ██     ██ ███████ ██████  ██   ██                         ║
║                                                              ║
║         B R A I N    S E T U P    W I Z A R D                ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

  This wizard will configure Mega Brain for first-time use.
  It takes about 2 minutes.

────────────────────────────────────────────────────────────────
  [1/6] Checking Python 3
────────────────────────────────────────────────────────────────
✔ Python 3.10.12 detected (python3)

────────────────────────────────────────────────────────────────
  [2/6] Checking Node.js
────────────────────────────────────────────────────────────────
✔ Node.js 18.17.0 detected

────────────────────────────────────────────────────────────────
  [3/6] Python Dependencies
────────────────────────────────────────────────────────────────
✔ Python dependencies installed

────────────────────────────────────────────────────────────────
  [4/6] API Key Configuration
────────────────────────────────────────────────────────────────

  Enter your API keys below. Press Enter to skip optional ones.
  Keys are stored locally in .env (never committed to git).

  REQUIRED OPENAI_API_KEY - Whisper transcription for video/audio
  Get yours at: https://platform.openai.com/api-keys
  
? OpenAI API Key: sk-proj-...

  RECOMMENDED VOYAGE_API_KEY - Semantic embeddings for RAG search
  Without this, semantic search uses mock vectors (degraded quality)
  Get yours at: https://dash.voyageai.com/api-keys
  
? Voyage API Key (Enter to skip): pa-...

  OPTIONAL Google OAuth - Import transcriptions from Google Drive
  Without these, download files manually to inbox/
  Setup at: https://console.cloud.google.com/apis/credentials
  
? Google Client ID (Enter to skip): 

────────────────────────────────────────────────────────────────
  [5/6] Validating Configuration
────────────────────────────────────────────────────────────────
✔ OpenAI API key is valid
✔ Voyage AI key is valid
  Google OAuth: not configured

────────────────────────────────────────────────────────────────
  [6/6] Summary & .env Generation
────────────────────────────────────────────────────────────────
✔ .env file generated

  ╭─────────────────────────────────────────────────────────╮
  │                                                         │
  │  SETUP SUMMARY                                          │
  │                                                         │
  │  Tools                                                  │
  │    Python 3 ........... OK  3.10.12                     │
  │    Node.js ............ OK  18.17.0                     │
  │    pip install ........ OK  installed                   │
  │                                                         │
  │  API Keys                                               │
  │    OPENAI_API_KEY ..... OK  sk-...                      │
  │    VOYAGE_API_KEY ..... OK  pa-...                      │
  │    Google OAuth ....... SKIP not set                    │
  │                                                         │
  │  .env file ............ WRITTEN                         │
  │                                                         │
  ╰─────────────────────────────────────────────────────────╯

  ╭─────────────────────────────────────────────────────────╮
  │  Setup complete!                                        │
  │                                                         │
  │  Next steps:                                            │
  │  1. Open this project in Claude Code                    │
  │  2. Drop a YouTube URL or PDF into inbox/               │
  │  3. Tell JARVIS: /ingest                                │
  │                                                         │
  │  JARVIS will handle the rest.                           │
  ╰─────────────────────────────────────────────────────────╯
```

## Manual Configuration

If you prefer to configure manually:

<Steps>
  <Step title="Copy the template">
    ```bash theme={null}
    cp .env.example .env
    ```

    Or create a new `.env` file from scratch.
  </Step>

  <Step title="Edit the file">
    Open `.env` in your text editor and fill in your API keys:

    ```bash theme={null}
    OPENAI_API_KEY=sk-your-actual-key
    VOYAGE_API_KEY=pa-your-actual-key
    ```
  </Step>

  <Step title="Verify configuration">
    ```bash theme={null}
    npx mega-brain-ai status
    ```
  </Step>
</Steps>

## Validation Commands

### Check System Status

View your complete configuration status:

```bash theme={null}
npx mega-brain-ai status
```

### Validate API Keys

The setup wizard automatically validates keys, but you can also use Claude Code:

```
/jarvis-briefing
```

This shows health score and active services.

### Test Specific Features

<CodeGroup>
  ```bash Test Transcription theme={null}
  # Try ingesting a short YouTube video
  /ingest https://www.youtube.com/watch?v=SHORT_VIDEO
  ```

  ```bash Test Semantic Search theme={null}
  # Process material and verify embeddings work
  /process-jarvis
  ```
</CodeGroup>

## Security Best Practices

<Warning>
  **Critical Security Rules:**

  1. Never commit `.env` to version control
  2. Never share your API keys publicly
  3. Rotate keys immediately if compromised
  4. Use separate keys for development and production
  5. Restrict key permissions to minimum required scope
</Warning>

### Verify .gitignore

Ensure your `.env` file is ignored:

```bash theme={null}
cat .gitignore | grep .env
```

Should output:

```
.env
.env.local
.env.*.local
```

### Key Rotation

If you need to rotate a compromised key:

<Steps>
  <Step title="Revoke the old key">
    Log into the provider's dashboard and revoke/delete the old key
  </Step>

  <Step title="Generate a new key">
    Create a new API key with the same permissions
  </Step>

  <Step title="Update .env">
    Replace the old key in your `.env` file
  </Step>

  <Step title="Test the new key">
    ```bash theme={null}
    npx mega-brain-ai setup
    ```

    The wizard will validate the new key.
  </Step>
</Steps>

## Troubleshooting

### API Key Validation Failed

If the setup wizard reports a key is invalid:

1. **Check for extra spaces** - Copy the key again, ensuring no leading/trailing spaces
2. **Verify key format** - OpenAI keys start with `sk-`, Voyage keys start with `pa-`
3. **Check key status** - Log into the provider's dashboard and verify the key is active
4. **Test network** - Ensure you can reach the API endpoint:
   ```bash theme={null}
   curl -I https://api.openai.com/v1/models
   ```

### Environment Variables Not Loading

If your keys aren't being recognized:

1. **Check file location** - `.env` must be in your project root
2. **Verify file name** - Must be exactly `.env` (not `.env.txt` or similar)
3. **Restart Claude Code** - Environment changes require a restart
4. **Check syntax** - Use `KEY=value` format with no spaces around `=`

### Setup Wizard Won't Start

If `npx mega-brain-ai setup` fails:

```bash theme={null}
# Clear npm cache
npm cache clean --force

# Try again
npx mega-brain-ai setup
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Now that you're configured, ingest your first material
  </Card>

  <Card title="Available Commands" icon="terminal" href="/commands/overview">
    Explore all CLI commands and slash commands
  </Card>

  <Card title="API Keys Guide" icon="key" href="/configuration">
    Detailed guide for each API provider
  </Card>

  <Card title="Layer System" icon="layer-group" href="/concepts/layer-system">
    Understand Community vs Pro features
  </Card>
</CardGroup>