Skip to main content

​
Overview

JARVIS requires environment variables for both frontend and backend components. All sensitive credentials should be stored securely and never committed to version control.
Never commit .env files to version control. Add them to .gitignore.

​
Environment File Structure

Create separate environment files: 
backend/.env          # Backend configuration
frontend/.env.local   # Frontend configuration (local dev)
Copy from the example file: 
cp backend/.env.example backend/.env

​
Frontend Environment Variables

​
Convex Configuration

​
NEXT_PUBLIC_CONVEX_URL
string
required
Convex deployment URL for real-time database connections.Get this from your Convex dashboard after deploying your schema.Example: https://happy-animal-123.convex.cloud
Must be prefixed with NEXT_PUBLIC_ to be exposed to the browser.

​
Example Frontend .env.local

# Frontend
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

​
Backend Environment Variables

​
Core Application Settings

​
SPECTER_ENV
string
default:"development"
Application environment mode.Options: development, staging, productionExample: SPECTER_ENV=production
​
SPECTER_FRONTEND_ORIGIN
string
default:"http://localhost:3000"
Frontend URL for CORS configuration.Set this to your Vercel deployment URL in production.Example: SPECTER_FRONTEND_ORIGIN=https://jarvis.vercel.app
​
SPECTER_API_PORT
integer
default:"8000"
Port for the FastAPI server to listen on.Example: SPECTER_API_PORT=8000
​
SPECTER_LOG_LEVEL
string
default:"INFO"
Logging verbosity level.Options: DEBUG, INFO, WARNING, ERROR, CRITICALExample: SPECTER_LOG_LEVEL=INFO

​
Database Configuration

​
CONVEX_URL
string
required
Convex deployment URL for backend database operations.Same as frontend URL but used by backend for mutations/queries.Example: CONVEX_URL=https://happy-animal-123.convex.cloud
​
MONGODB_URI
string
required
MongoDB Atlas connection string for persistent storage.Used for storing raw images and archival data.Example: MONGODB_URI=mongodb+srv://user:[email protected]/jarvis

​
AI Model API Keys

​
OPENAI_API_KEY
string
OpenAI API key for GPT-4 vision model.Used for image analysis and identification.Get it: platform.openai.com/api-keysExample: OPENAI_API_KEY=sk-...
​
GEMINI_API_KEY
string
Google Gemini API key for vision and synthesis.Used for screenshot parsing and report synthesis (cheaper than OpenAI).Get it: makersuite.google.com/app/apikeyExample: GEMINI_API_KEY=AIza...
​
ANTHROPIC_API_KEY
string
Anthropic Claude API key (alternative LLM).Get it: console.anthropic.comExample: ANTHROPIC_API_KEY=sk-ant-...

​
Research & Data APIs

​
EXA_API_KEY
string
required
Exa API key for fast person search and web research.Critical for Tier 1 enrichment (~200ms response time).Get it: exa.aiExample: EXA_API_KEY=exa_...
​
BROWSER_USE_API_KEY
string
required
Browser Use cloud API key for agent automation.Required for all Browser Use agents (LinkedIn, Twitter, Instagram, PimEyes).Get it: cloud.browser-use.com/new-api-keyExample: BROWSER_USE_API_KEY=bu_...
When set, agents use cloud browser sessions with persistent authentication.
​
BROWSER_USE_PROFILE_ID
string
Browser Use profile ID for persistent browser sessions.Set up authenticated sessions for LinkedIn, Twitter, Instagram:
  1. Set BROWSER_USE_API_KEY
  2. Run browseruse CLI interactively
  3. Log into platforms manually
  4. Sessions persist in your Browser Use cloud profile
Example: BROWSER_USE_PROFILE_ID=profile_...

​
Identity & Search Services

​
PIMEYES_ACCOUNT_POOL
string
default:"[]"
JSON array of PimEyes accounts for facial recognition.Format: [{"email":"[email protected]","password":"pass123"}]Multiple accounts enable round-robin rotation to avoid rate limits.Example: PIMEYES_ACCOUNT_POOL=[{"email":"[email protected]","password":"xxx"}]
​
PIMEYES_EMAIL
string
Single PimEyes account email (alternative to account pool).Example: [email protected]
​
PIMEYES_PASSWORD
string
Single PimEyes account password.Example: PIMEYES_PASSWORD=your_password
​
SIXTYFOUR_API_KEY
string
64.io API key for additional face search capabilities.Example: SIXTYFOUR_API_KEY=64_...

​
Observability & Monitoring

​
LAMINAR_API_KEY
string
required
Laminar API key for agent tracing and observability.Provides visibility into all LLM calls and agent runs.Get it: lmnr.aiExample: LAMINAR_API_KEY=lm_...
Config reads LAMINAR_API_KEY; the SDK receives it via Laminar.initialize()
​
HUD_API_KEY
string
HUD API key for multi-agent orchestration debugging.Example: HUD_API_KEY=hud_...

​
Memory & Persistence

​
SUPERMEMORY_API_KEY
string
SuperMemory API key for long-term memory and dossier caching.Enables cross-session memory for the research pipeline.Get it: supermemory.aiExample: SUPERMEMORY_API_KEY=sm_...

​
Communication Services

​
TELEGRAM_BOT_TOKEN
string
Telegram bot token for receiving photos from Meta glasses.Create a bot via @BotFather on Telegram.Example: TELEGRAM_BOT_TOKEN=123456789:ABC...
​
AGENTMAIL_API_KEY
string
AgentMail API key for email communications.Example: AGENTMAIL_API_KEY=am_...

​
Breach & Security Data

​
HIBP_API_KEY
string
Have I Been Pwned API key for breach data checks.Check if a person appears in known data breaches.Get it: haveibeenpwned.com/API/KeyExample: HIBP_API_KEY=hibp_...

​
Infrastructure

​
DAYTONA_API_KEY
string
Daytona API key for sandbox management.Example: DAYTONA_API_KEY=dt_...
​
DAYTONA_API_URL
string
Daytona API URL for custom deployments.Default: Daytona cloud APIExample: DAYTONA_API_URL=https://api.daytona.io
​
OP_VAULT_ID
string
1Password vault ID for credential management.Example: OP_VAULT_ID=vault_...

​
Complete .env.example

Here’s the complete example from the source repository: 
# Frontend
NEXT_PUBLIC_CONVEX_URL=

# Backend
SPECTER_ENV=development
SPECTER_FRONTEND_ORIGIN=http://localhost:3000
SPECTER_API_PORT=8000
SPECTER_LOG_LEVEL=INFO

# Service integrations
CONVEX_URL=
MONGODB_URI=
EXA_API_KEY=
OPENAI_API_KEY=
GEMINI_API_KEY=
TELEGRAM_BOT_TOKEN=
PIMEYES_ACCOUNT_POOL=[]

# Laminar observability — get your key at https://www.lmnr.ai
# Config reads LAMINAR_API_KEY; the SDK receives it via Laminar.initialize()
LAMINAR_API_KEY=

# Browser Use v2 cloud — get your key at https://cloud.browser-use.com/new-api-key
# When set, agents use cloud browser sessions with persistent auth.
# To set up authenticated sessions:
#   1. Set this key
#   2. Run `browseruse` CLI interactively
#   3. Log into LinkedIn, Twitter, Instagram manually
#   4. Sessions persist in your Browser Use cloud profile
BROWSER_USE_API_KEY=

# SuperMemory — long-term memory / dossier cache for the pipeline
# Get your key at https://supermemory.ai
SUPERMEMORY_API_KEY=

​
Service Flags

The backend automatically detects which services are configured based on environment variables. Access this information at the /api/status endpoint: 
{
  "services": {
    "convex": true,
    "mongodb": true,
    "exa": true,
    "browser_use": true,
    "openai": false,
    "gemini": true,
    "anthropic": false,
    "laminar": true,
    "telegram": false,
    "hibp": false,
    "pimeyes_pool": true,
    "supermemory": false,
    "daytona": false,
    "hud": false,
    "agentmail": false,
    "pimeyes": false,
    "sixtyfour": false,
    "browser_use_profile": false
  }
}
A service is true if its required environment variables are set and non-empty.

​
Required vs Optional

​
Minimum Required for Basic Functionality

# Absolutely required
NEXT_PUBLIC_CONVEX_URL=
CONVEX_URL=
MONGODB_URI=
EXA_API_KEY=
BROWSER_USE_API_KEY=
LAMINAR_API_KEY=

# At least one LLM
GEMINI_API_KEY=  # OR OPENAI_API_KEY

# At least one face search method
PIMEYES_ACCOUNT_POOL=[]  # OR PIMEYES_EMAIL + PIMEYES_PASSWORD

# Better results with both LLMs
GEMINI_API_KEY=
OPENAI_API_KEY=

# Enhanced agent capabilities
BROWSER_USE_PROFILE_ID=
SUPERMEMORY_API_KEY=

# Additional data sources
HIBP_API_KEY=
SIXTYFOUR_API_KEY=

# Communication
TELEGRAM_BOT_TOKEN=

​
Security Best Practices

Follow these security practices to protect your API keys and credentials.

​
Local Development

  1. Use .env files: Keep credentials in .env files, never in code
  2. Add to .gitignore: Ensure .env is in .gitignore
  3. Use .env.example: Provide a template without actual values
  4. Rotate keys regularly: Change API keys periodically

​
Production Deployment

  1. Use platform secrets: Vercel Environment Variables, Daytona Secrets
  2. Separate environments: Different keys for dev/staging/production
  3. Principle of least privilege: Only grant necessary permissions
  4. Monitor usage: Watch for unexpected API usage spikes
  5. Enable API key restrictions: Restrict keys to specific domains/IPs where possible

​
Credential Management

Set environment variables in Vercel dashboard:
  1. Project Settings > Environment Variables
  2. Add each variable
  3. Choose environments (Production, Preview, Development)
  4. Click “Save”
Or use Vercel CLI:
vercel env add VARIABLE_NAME

​
Troubleshooting

​
Variables Not Loading

Problem: Environment variables are undefined at runtime. Solutions:
  • Verify file name: .env (backend) or .env.local (frontend)
  • Check file location: Must be in project root
  • Restart dev server after changing .env files
  • For frontend, ensure NEXT_PUBLIC_ prefix for client-side variables

​
Service Flag Shows False

Problem: /api/status shows a service as false when it should be configured. Solutions:
  • Check variable name matches exactly (case-sensitive)
  • Ensure value is non-empty
  • For JSON values like PIMEYES_ACCOUNT_POOL, verify valid JSON syntax
  • Restart backend after changing environment variables

​
CORS Errors

Problem: Frontend can’t connect to backend. Solution:
  • Set SPECTER_FRONTEND_ORIGIN to match your frontend URL exactly
  • Include protocol: https:// not just domain.com
  • No trailing slash: https://domain.com not https://domain.com/

​
Next Steps

Backend Deployment

Deploy the FastAPI backend with environment variables configured

Frontend Deployment

Deploy the Next.js frontend with Convex URL configured

Build docs developers (and LLMs) love

Get started for freeTalk to us