Configuration - Mega Brain

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.

Never commit your .env file to git! It contains sensitive API keys. The file is automatically added to .gitignore during installation.

API Keys Overview

Mega Brain integrates with multiple services for different capabilities:

Required

OpenAIEssential for video/audio transcription

Optional

Everything elseAdvanced features and integrations

Required API Keys

OpenAI API Key

Required for: Video/audio transcription via Whisper APIUsed by: /ingest command when processing YouTube videos, podcasts, or audio files

Get your API key

Go to OpenAI Platform
Sign in or create an account
Click “Create new secret key”
Copy the key (starts with sk-)

Add to .env file

Open your .env file and add:

OPENAI_API_KEY=sk-your-actual-key-here

Verify the key

Test your configuration:

npx mega-brain-ai status

You should see:

API Keys
  OPENAI_API_KEY ..... OK  sk-...

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

Required for: High-quality semantic embeddings for RAG (Retrieval Augmented Generation)Used by: Knowledge search, similarity matching, and agent context retrieval

Get your API key

Go to Voyage AI Dashboard
Sign up for an account
Navigate to API Keys section
Create a new API key

Add to .env file

VOYAGE_API_KEY=pa-your-actual-key-here

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.

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)

Required for: Importing transcriptions directly from Google Drive or Google DocsUsed by: /ingest command when processing Google Drive URLs

Create OAuth credentials

Go to Google Cloud Console
Create a new project or select existing
Enable Google Drive API and Google Docs API
Create OAuth 2.0 credentials
Add authorized redirect URIs (typically http://localhost:8080)

Add to .env file

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

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

Required for: Direct Claude API access (separate from Claude Code)Used by: Standalone scripts and batch processing operations

ANTHROPIC_API_KEY=sk-ant-your-actual-key-here

Get your key from Anthropic Console.

Voice & Audio Features

These keys enable advanced voice interaction features:

ElevenLabs

Text-to-Speech

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

Deepgram

Speech-to-Text

DEEPGRAM_API_KEY=your-key

Get API key

VAPI

Voice AI Platform

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

Database & Storage

Supabase (Email Validation)

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 → Settings → API.

Integration Services (MCP)

These services enable integrations with productivity tools:

# 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

N8N

Workflow automation and webhook handling

ClickUp

Task and project management integration

Miro

Collaborative whiteboarding

Notion

Documentation and knowledge management

Figma

Design file access and integration

Premium Distribution

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

# Required
OPENAI_API_KEY=sk-your-key-here

# Recommended
VOYAGE_API_KEY=pa-your-key-here

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

Setup Wizard

Interactive Configuration

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

npx mega-brain-ai setup

The wizard will:

Check prerequisites

Verify Node.js 18+ and Python 3.10+ are installed

Install dependencies

Automatically install Python packages from requirements.txt:

PyYAML >= 6.0

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

Validate keys

Test API connectivity for OpenAI and Voyage AI

Generate .env

Create or update your .env file with the provided keys

Show summary

Display a complete setup summary with next steps

Example Setup Session

$ 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:

Copy the template

cp .env.example .env

Or create a new .env file from scratch.

Edit the file

Open .env in your text editor and fill in your API keys:

OPENAI_API_KEY=sk-your-actual-key
VOYAGE_API_KEY=pa-your-actual-key

Verify configuration

npx mega-brain-ai status

Validation Commands

Check System Status

View your complete configuration status:

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

# Try ingesting a short YouTube video
/ingest https://www.youtube.com/watch?v=SHORT_VIDEO

# Process material and verify embeddings work
/process-jarvis

Security Best Practices

Critical Security Rules:

Never commit .env to version control
Never share your API keys publicly
Rotate keys immediately if compromised
Use separate keys for development and production
Restrict key permissions to minimum required scope

Verify .gitignore

Ensure your .env file is ignored:

cat .gitignore | grep .env

Should output:

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

Key Rotation

If you need to rotate a compromised key:

Revoke the old key

Log into the provider’s dashboard and revoke/delete the old key

Generate a new key

Create a new API key with the same permissions

Update .env

Replace the old key in your .env file

Test the new key

npx mega-brain-ai setup

The wizard will validate the new key.

Troubleshooting

API Key Validation Failed

If the setup wizard reports a key is invalid:

Check for extra spaces - Copy the key again, ensuring no leading/trailing spaces
Verify key format - OpenAI keys start with sk-, Voyage keys start with pa-
Check key status - Log into the provider’s dashboard and verify the key is active
Test network - Ensure you can reach the API endpoint:
curl -I https://api.openai.com/v1/models

Environment Variables Not Loading

If your keys aren’t being recognized:

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

Setup Wizard Won’t Start

If npx mega-brain-ai setup fails:

# Clear npm cache
npm cache clean --force

# Try again
npx mega-brain-ai setup

Next Steps

Quick Start Guide

Now that you’re configured, ingest your first material

Available Commands

Explore all CLI commands and slash commands

API Keys Guide

Detailed guide for each API provider

Layer System

Understand Community vs Pro features

​Environment Configuration

​API Keys Overview

Required

Recommended

Optional

​Required API Keys

​OpenAI API Key

​Recommended API Keys

​Voyage AI API Key

​Optional API Keys

​Google OAuth (Drive Integration)

​Anthropic API Key

​Voice & Audio Features

ElevenLabs

Deepgram

VAPI

​Database & Storage

​Supabase (Email Validation)

​Integration Services (MCP)

N8N

ClickUp

Miro

Notion

Figma

​Premium Distribution

​Configuration File Structure

​Setup Wizard

​Interactive Configuration

​Example Setup Session

​Manual Configuration

​Validation Commands

​Check System Status

​Validate API Keys

​Test Specific Features

​Security Best Practices

​Verify .gitignore

​Key Rotation

​Troubleshooting

​API Key Validation Failed

​Environment Variables Not Loading

​Setup Wizard Won’t Start

​Next Steps

Quick Start Guide

Available Commands

API Keys Guide

Layer System

Environment Configuration

API Keys Overview

Required API Keys

OpenAI API Key

Recommended API Keys

Voyage AI API Key

Optional API Keys

Google OAuth (Drive Integration)

Anthropic API Key

Voice & Audio Features

Database & Storage

Supabase (Email Validation)

Integration Services (MCP)

Premium Distribution

Configuration File Structure

Setup Wizard

Interactive Configuration

Example Setup Session

Manual Configuration

Validation Commands

Check System Status

Validate API Keys

Test Specific Features

Security Best Practices

Verify .gitignore

Key Rotation

Troubleshooting

API Key Validation Failed

Environment Variables Not Loading

Setup Wizard Won’t Start

Next Steps