Skip to main content

​
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

Recommended

Voyage AIEnables high-quality semantic search

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
1

Get your API key

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

Add to .env file

Open your .env file and add:
OPENAI_API_KEY=sk-your-actual-key-here
3

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/

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

Get your API key

  1. Go to Voyage AI Dashboard
  2. Sign up for an account
  3. Navigate to API Keys section
  4. Create a new API key
2

Add to .env file

VOYAGE_API_KEY=pa-your-actual-key-here
3

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
1

Create OAuth credentials

  1. Go to Google Cloud Console
  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)
2

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

​
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:
1

Check prerequisites

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

Install dependencies

Automatically install Python packages from requirements.txt:
  • PyYAML >= 6.0
3

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
4

Validate keys

Test API connectivity for OpenAI and Voyage AI
5

Generate .env

Create or update your .env file with the provided keys
6

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

Copy the template

cp .env.example .env
Or create a new .env file from scratch.
2

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
3

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

​
Security Best Practices

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

​
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:
1

Revoke the old key

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

Generate a new key

Create a new API key with the same permissions
3

Update .env

Replace the old key in your .env file
4

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

Build docs developers (and LLMs) love

Get started for freeTalk to us