Skip to main content

​
Configuration Overview

JARVIS uses environment variables for all configuration. The backend reads from .env files using Pydantic Settings, providing type safety and validation.

​
Environment File Setup

Create a .env file in the backend/ directory: 
cp .env.example .env

​
Core Configuration

​
Application Settings

# Application environment
SPECTER_ENV=development
SPECTER_LOG_LEVEL=INFO
SPECTER_API_PORT=8000

# Frontend origin for CORS
SPECTER_FRONTEND_ORIGIN=http://localhost:3000
​
SPECTER_ENV
string
default:"development"
Application environment: development, staging, or production
​
SPECTER_LOG_LEVEL
string
default:"INFO"
Logging level: DEBUG, INFO, WARNING, ERROR, or CRITICAL
​
SPECTER_API_PORT
integer
default:"8000"
Port for the FastAPI backend server
​
SPECTER_FRONTEND_ORIGIN
string
default:"http://localhost:3000"
Frontend URL for CORS configuration

​
Database Configuration

​
Convex (Real-time Database)

CONVEX_URL=https://your-project.convex.cloud
Convex provides real-time subscriptions for streaming intelligence data to the frontend.
Get your Convex URL from convex.dev after creating a project.

​
MongoDB (Persistent Storage)

MONGODB_URI=mongodb+srv://username:[email protected]/jarvis
MongoDB stores raw images, capture metadata, and persistent person records.

​
API Key Configuration

​
LLM Providers

# OpenAI (GPT-4 Vision for face identification)
OPENAI_API_KEY=sk-...

# Google Gemini (Report synthesis)
GEMINI_API_KEY=...

# Anthropic Claude (Alternative LLM)
ANTHROPIC_API_KEY=sk-ant-...
At least one LLM provider is required. OpenAI is recommended for vision capabilities.

​
Browser Automation

# Browser Use API key
BRORWSER_USE_API_KEY=...

# Optional: Browser Use persistent profile
BROWSER_USE_PROFILE_ID=...
Browser Use powers the agent swarm for researching people across LinkedIn, Twitter, and other platforms.

Get Browser Use API Key

Sign up for Browser Use to get $100 in hackathon credits

​
Research APIs

# Exa API for fast person lookup
EXA_API_KEY=...

# SuperMemory for long-term agent memory
SUPERMEMORY_API_KEY=...

​
Face Recognition

# PimEyes account pool (JSON array)
PIMEYES_ACCOUNT_POOL=[{"email":"[email protected]","password":"xxx"}]

# Or single account
PIMEYES_EMAIL=[email protected]
PIMEYES_PASSWORD=xxx
Use multiple PimEyes accounts to avoid rate limiting. The pool format allows round-robin rotation.

​
Observability

# Laminar tracing (get key at lmnr.ai)
LMNR_PROJECT_API_KEY=...

# HUD multi-agent orchestration
HUD_API_KEY=...

​
Notifications

# Telegram bot for Meta glasses integration
TELEGRAM_BOT_TOKEN=...

​
Configuration in Code

The backend uses Pydantic Settings for type-safe configuration: 
from config import Settings, get_settings

# Get settings instance (cached)
settings = get_settings()

# Access configuration
print(settings.app_name)  # "JARVIS API"
print(settings.environment)  # "development"
print(settings.api_port)  # 8000

# Check service availability
flags = settings.service_flags()
if flags["openai"]:
    print("OpenAI is configured")
if not flags["convex"]:
    print("Warning: Convex not configured")

​
Settings Class

The Settings class in backend/config.py:
backend/config.py
from pydantic_settings import BaseSettings
from pydantic import Field

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        extra="ignore",
    )

    app_name: str = "JARVIS API"
    environment: str = Field(default="development", alias="SPECTER_ENV")
    log_level: str = Field(default="INFO", alias="SPECTER_LOG_LEVEL")
    frontend_origin: str = Field(default="http://localhost:3000", alias="SPECTER_FRONTEND_ORIGIN")
    api_port: int = Field(default=8000", alias="SPECTER_API_PORT")

    # Database
    convex_url: str | None = Field(default=None, alias="CONVEX_URL")
    mongodb_uri: str | None = Field(default=None, alias="MONGODB_URI")

    # APIs
    exa_api_key: str | None = Field(default=None, alias="EXA_API_KEY")
    browser_use_api_key: str | None = Field(default=None, alias="BROWSER_USE_API_KEY")
    openai_api_key: str | None = Field(default=None, alias="OPENAI_API_KEY")
    gemini_api_key: str | None = Field(default=None, alias="GEMINI_API_KEY")
    laminar_api_key: str | None = Field(default=None, alias="LMNR_PROJECT_API_KEY")

    def service_flags(self) -> dict[str, bool]:
        """Return dict of configured services."""
        return {
            "convex": bool(self.convex_url),
            "mongodb": bool(self.mongodb_uri),
            "exa": bool(self.exa_api_key),
            "browser_use": bool(self.browser_use_api_key),
            "openai": bool(self.openai_api_key),
            "gemini": bool(self.gemini_api_key),
            "laminar": bool(self.laminar_api_key),
        }

​
Environment-Specific Configuration

​
Development

SPECTER_ENV=development
SPECTER_LOG_LEVEL=DEBUG
SPECTER_FRONTEND_ORIGIN=http://localhost:3000
  • Verbose logging
  • CORS allows localhost
  • Hot reload enabled

​
Production

SPECTER_ENV=production
SPECTER_LOG_LEVEL=WARNING
SPECTER_FRONTEND_ORIGIN=https://yourdomain.com
  • Minimal logging
  • CORS restricted to production domain
  • Optimized for performance

​
Configuration Validation

Check your configuration with the built-in validation script: 
cd backend
python env_check.py
Example output: 
✓ Core configuration loaded
✓ OpenAI API key configured
✓ Gemini API key configured
✓ Browser Use API key configured
✗ Convex URL not configured
✗ MongoDB URI not configured
✓ Laminar API key configured

​
Security Best Practices

Never commit .env files to version control. The .env.example file should only contain placeholders.

​
API Key Rotation

  1. Generate new API key from provider
  2. Update .env file
  3. Restart the backend service
  4. Revoke old API key

​
Secrets Management

For production deployments:
  • Use environment variables from your hosting provider
  • Consider using secrets managers (AWS Secrets Manager, HashiCorp Vault)
  • Encrypt sensitive values at rest

​
Troubleshooting

​
Service Flags Show False

If service_flags() returns false for a configured service:
  1. Check environment variable name matches exactly
  2. Verify .env file is in the correct directory
  3. Restart the backend server
  4. Check for typos in API keys

​
Import Errors

If you get import errors when accessing settings: 
# Ensure you're in the backend directory
cd backend

# Reinstall dependencies
uv pip install -e ".[dev]"

​
Configuration Not Loading

Pydantic Settings reads from:
  1. Environment variables (highest priority)
  2. .env file
  3. Default values (lowest priority)
Use environment variables to override .env values: 
SPECTER_LOG_LEVEL=DEBUG uvicorn main:app --reload

​
Next Steps

Testing

Write tests for your configured services

Observability

Set up Laminar tracing

API Reference

Explore API endpoints

Deployment

Deploy to production

Build docs developers (and LLMs) love

Get started for freeTalk to us