Installation - JARVIS

Prerequisites

Before installing JARVIS, ensure you have the following installed on your system:

Python 3.11+

Required for the backend FastAPI server

Node.js 20+

Required for the Next.js frontend

Git

For cloning the repository

uv

Fast Python package manager (recommended)

If you don’t have uv installed, you can install it with:

curl -LsSf https://astral.sh/uv/install.sh | sh

System Requirements

OS: Linux, macOS, or Windows (WSL recommended)
RAM: Minimum 4GB (8GB+ recommended for agent orchestration)
Disk: 2GB free space for dependencies and models

Clone the Repository

Clone JARVIS

git clone https://github.com/your-org/jarvis.git
cd jarvis

Verify project structure

You should see the following structure:

jarvis/
├── backend/          # Python FastAPI server
├── frontend/         # Next.js application
├── .env.example      # Environment template
└── scripts/          # Utility scripts

Backend Setup

Navigate to backend directory

cd backend

Install Python dependencies

uv sync

This installs all required dependencies including:

FastAPI - Web framework
browser-use - Web agent orchestration
mediapipe - Face detection
opencv-python - Image processing
anthropic - Claude API client
google-genai - Gemini API client
loguru - Logging

Install development dependencies (optional)

For testing and linting:

uv sync --extra dev

Verify installation

python -c "import fastapi; print('FastAPI installed')"
python -c "import mediapipe; print('MediaPipe installed')"

Frontend Setup

Navigate to frontend directory

cd ../frontend

Install Node.js dependencies

npm install

This installs:

Next.js 16 - React framework
Convex - Real-time database
Framer Motion - Animations
Tailwind CSS 4 - Styling
Lucide React - Icons

Verify installation

npm list next convex framer-motion

Environment Configuration

Copy environment template

From the project root:

cp .env.example .env

Configure required variables

Open .env and configure the following:

Frontend (Required)

NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud

Backend Core (Required)

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

Convex Integration (Required)

CONVEX_URL=https://your-project.convex.cloud

Get your Convex URL by signing up at convex.dev and creating a new project.

Configure AI services

At minimum, configure one AI provider:

# OpenAI (GPT-4o for vision and synthesis)
OPENAI_API_KEY=sk-...

# OR Anthropic (Claude for synthesis)
ANTHROPIC_API_KEY=sk-ant-...

# OR Google (Gemini for synthesis and transcription)
GEMINI_API_KEY=...

Without at least one AI provider configured, person identification and dossier synthesis will not work.

Configure optional services

These enhance functionality but aren’t required:

Browser Use Cloud (for authenticated agent sessions)

BROWSER_USE_API_KEY=...

Get your key at cloud.browser-use.com

Research & Enrichment

# Exa API for structured web search
EXA_API_KEY=...

# SuperMemory for long-term dossier caching
SUPERMEMORY_API_KEY=...

MongoDB (for persistent storage)

MONGODB_URI=mongodb+srv://...

Observability

# Laminar for LLM tracing
LAMINAR_API_KEY=...

Telegram Integration (for Meta glasses)

TELEGRAM_BOT_TOKEN=...

Database Setup

Convex Setup

Install Convex CLI

npm install -g convex

Navigate to frontend directory

cd frontend

Initialize Convex

npx convex dev

This will:

Prompt you to log in (or create a Convex account)
Create a new Convex project (or select existing)
Generate your NEXT_PUBLIC_CONVEX_URL
Deploy your schema and functions

Copy the Convex URL

After initialization, copy the URL from the terminal output and add it to your .env:

NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
CONVEX_URL=https://your-project.convex.cloud

MongoDB Setup (Optional)

MongoDB is used for persistent storage of raw captures and historical data. It’s optional - JARVIS will use in-memory storage if MongoDB is not configured.

Create MongoDB Atlas account

Create a free cluster

Follow the MongoDB Atlas setup wizard to create a free M0 cluster.

Get connection string

Click “Connect” on your cluster
Choose “Connect your application”
Copy the connection string
Replace <password> with your database password

Add to environment

MONGODB_URI=mongodb+srv://username:[email protected]/jarvis?retryWrites=true&w=majority

Verify Installation

Check backend health

Start the backend server:

cd backend
uv run uvicorn main:app --reload --port 8000

In another terminal, test the health endpoint:

curl http://localhost:8000/api/health

You should see:

{
  "status": "healthy",
  "version": "0.1.0",
  "services": {
    "convex": "configured",
    "face_detector": "ready",
    "face_embedder": "ready"
  }
}

Check frontend

In a new terminal:

cd frontend
npm run dev

Open http://localhost:3000 in your browser. You should see the JARVIS corkboard interface.

Check Convex connection

In the frontend terminal, look for:

✓ Convex client connected
✓ Real-time subscriptions active

Troubleshooting

MediaPipe installation fails on Apple Silicon

If MediaPipe fails to install on M1/M2 Macs:

# Install Rosetta 2 if not already installed
softwareupdate --install-rosetta

# Install under x86_64 architecture
arch -x86_64 pip install mediapipe

Port 8000 already in use

Change the backend port in your .env:

SPECTER_API_PORT=8001

Then start with:

uv run uvicorn main:app --reload --port 8001

Convex connection fails

Verify your Convex URL is correct:

# Check Convex status
npx convex dev --once

Ensure both frontend and backend have the same CONVEX_URL.

OpenCV 'No module named cv2' error

OpenCV headless might not be installed correctly:

pip uninstall opencv-python opencv-python-headless
pip install opencv-python-headless==4.10.0

Browser Use agent errors

If you see browser automation errors:

Ensure BROWSER_USE_API_KEY is set
Check your Browser Use credits at cloud.browser-use.com
Verify network connectivity to Browser Use cloud

Frontend shows 'No Convex data'

This is expected on first run. The frontend works with or without live data:

With Convex configured: Real-time updates will appear
Without Convex: Demo fallback data is shown

To verify Convex is working, check the Network tab in browser DevTools for WebSocket connections to convex.cloud.

Development Tools (Optional)

Backend Testing

cd backend

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=. --cov-report=term-missing

# Run linting
uv run ruff check .

Frontend Testing

cd frontend

# Run unit tests
npm test

# Run tests in watch mode
npm run test:watch

# Run end-to-end tests
npm run test:e2e

# Type checking
npm run typecheck

# Linting
npm run lint

Next Steps

Quickstart Guide

Run your first capture and see JARVIS in action

Architecture

Understand how JARVIS components work together

API Reference

Explore the backend API endpoints

Configuration

Advanced configuration options

Get Started

Core Concepts

Hardware Integration

Backend Services

Agent System

Frontend

Data & Storage

Deployment

​Prerequisites

Python 3.11+

Node.js 20+

Git

uv

​System Requirements

​Clone the Repository

​Backend Setup

​Frontend Setup

​Environment Configuration

​Frontend (Required)

​Backend Core (Required)

​Convex Integration (Required)

​Browser Use Cloud (for authenticated agent sessions)

​Research & Enrichment

​MongoDB (for persistent storage)

​Observability

​Telegram Integration (for Meta glasses)

​Database Setup

​Convex Setup

​MongoDB Setup (Optional)

​Verify Installation

​Troubleshooting

​Development Tools (Optional)

​Backend Testing

​Frontend Testing

​Next Steps

Quickstart Guide

Architecture

API Reference

Configuration

Build docs developers (and LLMs) love

Prerequisites

System Requirements

Clone the Repository

Backend Setup

Frontend Setup

Environment Configuration

Frontend (Required)

Backend Core (Required)

Convex Integration (Required)

Browser Use Cloud (for authenticated agent sessions)

Research & Enrichment

MongoDB (for persistent storage)

Observability

Telegram Integration (for Meta glasses)

Database Setup

Convex Setup

MongoDB Setup (Optional)

Verify Installation

Troubleshooting

Development Tools (Optional)

Backend Testing

Frontend Testing

Next Steps