Installation Guide

This guide covers detailed installation steps, configuration options, and troubleshooting for Jarvis.

System Requirements

macOS Version

Jarvis currently only supports macOS. Linux and Windows support is not available.

Minimum macOS version: macOS 13.0 (Ventura) or later The setup script checks your macOS version automatically:

setup.sh

# Check macOS version (13.0+)
MACOS_VERSION=$(sw_vers -productVersion | cut -d. -f1)
if [[ "$MACOS_VERSION" -lt 13 ]]; then
    echo "Error: macOS 13.0 (Monterey) or later is required"
    exit 1
fi

Python Version

Required: Python 3.10 or newer Jarvis requires modern Python for async features and type hints. The setup script will automatically detect compatible Python installations:

# Check available Python versions
python3 --version

# If you need to install Python 3.10+
brew install python@3.12

The setup script checks for python3.12, python3.11, python3.10, and python3 in that order.

Swift Version

Required: Swift 5.9 or newer Swift is included with Xcode Command Line Tools:

# Check if Swift is installed
swift --version

# Install Xcode Command Line Tools if needed
xcode-select --install

Hardware Requirements

Metal-compatible GPU: Required for the 3D orb renderer (all Macs from 2012+ support Metal)
RAM: 8GB minimum, 16GB recommended for multiple AI panels
Storage: ~2GB for dependencies and models
Microphone: Required for voice input features

Step-by-Step Installation

1. Clone the Repository

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

2. Run the Setup Script

Jarvis includes an automated setup script that handles all installation steps:

./setup.sh

What the setup script does

The setup script performs the following operations:

Pre-flight checks:
- Verifies macOS version (13+)
- Checks for Xcode Command Line Tools
- Validates Swift installation
- Finds compatible Python 3.10+ installation

Directory structure:

mkdir -p jarvis/config
mkdir -p jarvis/commands
mkdir -p jarvis/session
mkdir -p tests
mkdir -p resources/themes
mkdir -p ~/.config/jarvis

Python environment:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Swift build:
```
cd metal-app
swift build -c release
```
Configuration:
- Creates default config at ~/.config/jarvis/config.yaml

3. Install Python Dependencies

If you skipped the setup script, manually install dependencies:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install requirements
pip install -r requirements.txt

View requirements.txt

requirements.txt

# Core dependencies
websockets>=12.0
sounddevice>=0.4
numpy>=1.24
google-genai>=1.0
httpx>=0.27
python-dotenv>=1.0
rich>=13.0
aiohttp>=3.9
pywhispercpp>=0.2

# Configuration
pydantic>=2.6
pyyaml>=6.0

# Crypto
cryptography>=42.0

# Testing
pytest>=8.0
pytest-asyncio>=0.23

4. Build the Metal App

Compile the Swift/Metal frontend:

cd metal-app
swift build -c release

# Optimized for performance
swift build -c release

The compiled binary will be at:

Release: metal-app/.build/release/JarvisBootup
Debug: metal-app/.build/debug/JarvisBootup

Configuration

Environment Variables

Create a .env file in the project root:

touch .env

Add your credentials:

.env

# Required for Claude Code assistant
CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token

# Optional: enables Gemini-powered voice routing
GOOGLE_API_KEY=your-gemini-api-key

# Optional: custom presence server
PRESENCE_URL=wss://your-presence-server.com

# Optional: custom trivia game URL
TRIVIA_URL=https://your-trivia-instance.com

Never commit .env to version control. Add it to .gitignore:

echo ".env" >> .gitignore

Claude OAuth Token Setup

The code assistant skill uses the Claude Agent SDK, which requires OAuth authentication.

Ensure Claude Max subscription

You need an active Claude Max subscription to use the Agent SDK.

Run the login script

./login.sh

This opens the Claude Code OAuth flow in your browser.

Authenticate in browser

Follow the prompts to log in with your Claude account.

Token extracted automatically

The script extracts the access token from macOS Keychain and writes it to .env:

# Pull token from macOS Keychain
OAUTH_TOKEN=$(security find-generic-password -s "Claude Code-credentials" -w 2>/dev/null \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['claudeAiOauth']['accessToken'])")

# Update .env file
if grep -q "CLAUDE_CODE_OAUTH_TOKEN" "$ENV_FILE" 2>/dev/null; then
    sed -i '' "s|^CLAUDE_CODE_OAUTH_TOKEN=.*|CLAUDE_CODE_OAUTH_TOKEN=$OAUTH_TOKEN|" "$ENV_FILE"
else
    echo "CLAUDE_CODE_OAUTH_TOKEN=$OAUTH_TOKEN" >> "$ENV_FILE"
fi

Token expiration: OAuth tokens expire periodically. If the code assistant stops authenticating, re-run ./login.sh to refresh the token.

Google Gemini API Key (Optional)

Gemini powers voice routing and optional skills like domain hunting and paper matching.

Get API key

Visit Google AI Studio and create an API key.

Add to .env

echo "GOOGLE_API_KEY=your-key-here" >> .env

Restart Jarvis

./start.sh

You should see: Config loaded from ~/.config/jarvis/config.yaml (no warnings about disabled skills)

Configuration File

Jarvis creates a YAML config at ~/.config/jarvis/config.yaml on first run:

# View current config
cat ~/.config/jarvis/config.yaml

# Edit config
nano ~/.config/jarvis/config.yaml

The setup script generates this automatically:

setup.sh

# Run Python to create default config
source .venv/bin/activate
python3 -c "from jarvis.config.loader import load_config; load_config()" 2>/dev/null

Running Jarvis

Start Script

The recommended way to launch Jarvis:

./start.sh

What start.sh does

start.sh

#!/bin/bash
set -e
cd "$(dirname "$0")"

# Create venv if it doesn't exist
if [ ! -d ".venv" ]; then
    echo "Creating virtual environment..."
    python3 -m venv .venv
fi

source .venv/bin/activate

# Install/update dependencies
pip install -q -r requirements.txt

# Build Metal app if binary is missing or sources changed
METAL_BIN="metal-app/.build/debug/JarvisBootup"
if [ ! -f "$METAL_BIN" ] || [ -n "$(find metal-app/Sources -newer "$METAL_BIN" 2>/dev/null)" ]; then
    echo "Building Metal app..."
    cd metal-app && swift build 2>&1 | tail -1 && cd ..
fi

python main.py

The script:

Activates the virtual environment
Updates Python dependencies if needed
Rebuilds the Metal app if source files changed
Launches main.py

Manual Launch

You can also run components manually:

# Activate virtualenv
source .venv/bin/activate

# Run main Python process
python main.py

Command-Line Options

# Launch with custom base path
python main.py --base /path/to/jarvis

# Launch Metal app directly (advanced)
./metal-app/.build/debug/JarvisBootup --jarvis --base $(pwd)

Controls & Shortcuts

Once Jarvis is running, use these controls:

Push-to-Talk

Left Control (hold) — Primary PTT keyOption + Period — Alternative PTT hotkey

Navigation

Cmd + G — Toggle hotkey overlayEscape — Close current panel or quit

Verification

After installation, verify everything works:

Launch Jarvis

./start.sh

Expected output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
JARVIS — Personal AI Assistant
Metal display active. PTT: Left Control
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Test voice input

Hold Left Control
Say: “Help me with code”
Release the key

A chat panel should open with the assistant ready.

Test Metal rendering

The 3D orb should:

Animate smoothly (60 FPS)
React to voice input when PTT is active
Display the hex grid background

Check logs

tail -f jarvis.log

Should show:

=== Jarvis starting ===
Config loaded from ~/.config/jarvis/config.yaml
Config sent to Swift

Troubleshooting

Swift Build Errors

Command line tools not found

xcode-select --install

If that fails, install full Xcode from the App Store, then:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Swift version too old

Update Xcode Command Line Tools:

softwareupdate --all --install --force

Or install the latest Xcode from the App Store.

Build hangs or fails

Clear Swift build cache:

cd metal-app
rm -rf .build
swift build -c release

Python Issues

Module not found errors

Ensure virtual environment is activated:

source .venv/bin/activate
pip install -r requirements.txt

Whisper model download fails

The first run downloads the Whisper model. This can take a few minutes.Check logs:

tail -f jarvis.log | grep whisper

Manual download:

python -c "from pywhispercpp import Whisper; Whisper('base')"

sounddevice errors

Install PortAudio:

brew install portaudio
pip install --force-reinstall sounddevice

Runtime Issues

Metal window doesn't open

Check if the binary exists:

ls -la metal-app/.build/debug/JarvisBootup

If missing, rebuild:

cd metal-app && swift build && cd ..

No audio / microphone permission denied

Grant microphone access:

System Settings → Privacy & Security → Microphone
Enable for Terminal (or your terminal app)
Restart Jarvis

Claude assistant not responding

Token may be expired or invalid:

./login.sh

Verify token is set:

grep CLAUDE_CODE_OAUTH_TOKEN .env

Check for errors:

tail -f jarvis.log | grep -i claude

Presence/chat not connecting

Check presence server is reachable:

# Default server
curl https://presence.jarvis.dev/health

Override with custom server in .env:

PRESENCE_URL=wss://your-server.com

Updating Jarvis

Pull latest changes and rebuild:

# Update code
git pull origin main

# Update Python dependencies
source .venv/bin/activate
pip install -r requirements.txt

# Rebuild Metal app
cd metal-app
swift build -c release
cd ..

# Restart Jarvis
./start.sh

Uninstallation

To remove Jarvis:

# Remove config
rm -rf ~/.config/jarvis

# Remove project directory
cd ..
rm -rf jarvis

# (Optional) Revoke Claude OAuth token
# Log into claude.ai and revoke the "Claude Code" integration

Next Steps

Quickstart

Jump straight into using Jarvis

Skills & Commands

Learn all available voice commands

Plugin System

Build custom panels and integrations

Manual

Complete technical documentation

Get Started

Core Features

Configuration

Plugins

Installation

Installation Guide

System Requirements

macOS Version

Python Version

Swift Version

Hardware Requirements

Step-by-Step Installation

1. Clone the Repository

2. Run the Setup Script

3. Install Python Dependencies

4. Build the Metal App

Configuration

Environment Variables

Claude OAuth Token Setup

Google Gemini API Key (Optional)

Configuration File

Running Jarvis

Start Script

Manual Launch

Command-Line Options

Controls & Shortcuts

Push-to-Talk

Navigation

Verification

Troubleshooting

Swift Build Errors

Python Issues

Runtime Issues

Updating Jarvis

Uninstallation

Next Steps

Quickstart

Skills & Commands

Plugin System

Manual

Get Started

Core Features

Configuration

Plugins

​Installation Guide

​System Requirements

​macOS Version

​Python Version

​Swift Version

​Hardware Requirements

​Step-by-Step Installation

​1. Clone the Repository

​2. Run the Setup Script

​3. Install Python Dependencies

​4. Build the Metal App

​Configuration

​Environment Variables

​Claude OAuth Token Setup

​Google Gemini API Key (Optional)

​Configuration File

​Running Jarvis

​Start Script

​Manual Launch

​Command-Line Options

​Controls & Shortcuts

Push-to-Talk

Navigation

​Verification

​Troubleshooting

​Swift Build Errors

​Python Issues

​Runtime Issues

​Updating Jarvis

​Uninstallation

​Next Steps

Quickstart

Skills & Commands

Plugin System

Manual

Installation Guide

System Requirements

macOS Version

Python Version

Swift Version

Hardware Requirements

Step-by-Step Installation

1. Clone the Repository

2. Run the Setup Script

3. Install Python Dependencies

4. Build the Metal App

Configuration

Environment Variables

Claude OAuth Token Setup

Google Gemini API Key (Optional)

Configuration File

Running Jarvis

Start Script

Manual Launch

Command-Line Options

Controls & Shortcuts

Verification

Troubleshooting

Swift Build Errors

Python Issues

Runtime Issues

Updating Jarvis

Uninstallation

Next Steps