Installation

Requirements

• Ubuntu 22.04+ or Windows 11+
• Python 3.11+
• 16GB+ system RAM
• (recommended) Nvidia GPU for TTS/STT

Easiest: Sapphire Launcher (Windows & Linux)

A single-file GUI that installs and manages everything — no terminal needed. It sets up Git, Miniconda, a dedicated Python environment, clones Sapphire, and installs all dependencies. It also updates, launches, switches between Stable and Development branches, sets up autostart, troubleshoots, and uninstalls.

1. Download from Sapphire Launcher releases:
   • Windows: sapphire-launcher.exe (Windows 10 1809+ or 11)
   • Linux: Sapphire_Launcher-x86_64.AppImage (chmod +x it first, then double-click)
2. Run it, click Scan System to see what's already installed, then Go to install anything missing
3. Click Launch, then Open Browser

If you use the launcher, you're done — skip to First Run step 2. The rest of this page is the manual path: same result, done by hand.

Prerequisites

Linux

sudo apt update
sudo apt install libportaudio2 python3-dev git

Install Miniconda:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b
~/miniconda3/bin/conda init

Close and reopen your terminal.

Windows

Open PowerShell as Administrator:

winget install Anaconda.Miniconda3
winget install Git.Git

Or download Miniconda manually from miniconda.io

Close and reopen PowerShell.

Why Git? Cloning Sapphire, and plugins whose dependencies install straight from a git commit — the Discord plugin's py-cord is pinned that way, so git has to stay on your PATH for it to install. If you ever installed discord.py, run pip uninstall discord.py first: it claims the same discord import name and breaks py-cord.

Python Environment

Sapphire requires Python 3.11 with specific package versions for GPU acceleration and audio processing. Conda pins Python exactly and handles complex dependencies automatically. Venv can work but requires manually installing Python 3.11 system-wide first, which varies by distro and often conflicts with system Python.

conda create -n sapphire python=3.11 -y
conda activate sapphire

Install Sapphire

Quick Start (Recommended)

Installs everything including TTS, STT, and wake word detection:

git clone https://github.com/ddxfish/sapphire.git
cd sapphire
pip install -r requirements.txt

Windows with an NVIDIA GPU: the default torch from PyPI has no CUDA, so voice would run on the CPU. After the requirements, in the same env: pip install torch --index-url https://download.pytorch.org/whl/cu128 (GTX 10-series or older: cu126). Linux gets CUDA from PyPI already. Details: TROUBLESHOOTING.md.

Minimal Install

For a lighter footprint without voice features:

git clone https://github.com/ddxfish/sapphire.git
cd sapphire
pip install -r install/requirements-minimal.txt

Then add features as needed:

# Claude Code agents: the Claude Agent SDK (~250 MB) is installed from Settings → Plugins → Claude Code
# (Install on the card, or the prompt when you enable the plugin) — nothing to pip here

# TTS (Kokoro voice synthesis)
pip install -r install/requirements-tts.txt

# STT (Faster Whisper transcription)
pip install -r install/requirements-stt.txt

# Wakeword (OpenWakeWord detection)
pip install -r install/requirements-wakeword.txt

# Flashing ESP32 boards from Sapphire's own computer (Settings > Devices > New board)
# Not needed to flash from the browser (Chrome/Edge): that lane has no dependency.
# Skip it: the Devices page offers to install this set the first time it is needed.
pip install -r install/requirements-flash.txt

Enable each in Settings after installing, then restart.

Note: those four files are the only difference from the full install. The minimal set already includes everything else — the dependencies for the Telegram and MCP plugins, EPUB and HEIC/iPhone files in the Library, and SOCKS proxy support for the LLM lane (see NETWORK.md).

LLM Backend

Sapphire needs an LLM to talk to. The setup wizard configures this on first run.

Option A: Local LLM (Private, Free)

Run AI models on your own hardware. No data leaves your machine.

1. Install LM Studio
2. Download a model (Qwen3 8B is a good start)
3. Go to Developer tab, enable "Local Server"
4. Sapphire connects to http://127.0.0.1:1234/v1 by default

Recommended local models:

Option B: Cloud LLM (Powerful, Not Private)

Use cloud APIs for stronger models. Your conversations go to external servers.

Set your API key via environment variable or in the setup wizard:

• ANTHROPIC_API_KEY for Claude
• OPENAI_API_KEY for OpenAI
• GOOGLE_API_KEY for Gemini

Sapphire automatically falls back between enabled providers if one fails.

First Run

python main.py

1. Open https://localhost:8073
2. Create a password (secures web UI and API)
3. Complete setup wizard (LLM, voice, audio)
4. Send a test message

Sapphire creates user/ directory with your settings and data. Run once before customizing.

Change or reset the password

• Change it in Settings › System › Login Password. Enter the current one, pick a new one (10+ characters). The tab you did it from stays logged in; every other device and browser is asked to log in again once.
• Forgot it? Stop Sapphire, delete the secret_key file from the config directory, start again — you get the setup page back. Config directory: Linux ~/.config/sapphire/, macOS ~/Library/Application Support/Sapphire/, Windows %APPDATA%\Sapphire\.

Update Sapphire

Preserves your user/ directory. Safe unless you modified core files.

cd sapphire
git pull
pip install -r requirements.txt

Launcher users: the Update button does both steps (and auto-stashes local changes on dirty repos).

Don't force-upgrade the LLM SDKs. requirements.txt caps openai<3, anthropic<1 and mcp<2 — Sapphire hasn't been ported to those majors (anthropic 1.0 removed the temperature/top_p/top_k arguments, which breaks every call through the Anthropic-compatible provider; the native Claude provider is unaffected). Installing from the requirements file respects the caps; pip install --upgrade openai anthropic mcp steps over them. Installs that already work aren't affected — neither git pull + the line above nor the in-app updater upgrades a package that's already satisfied.

Upgrading from 1.x to 2.0

Version 2.0 has new dependencies that require a fresh conda environment. Your user/ directory is preserved.

conda deactivate
conda remove -n sapphire --all -y
conda create -n sapphire python=3.11 -y
conda activate sapphire
cd sapphire
git pull
pip install -r requirements.txt

Uninstall

Remove the conda environment and optionally the project folder:

conda deactivate
conda remove -n sapphire --all -y

Delete the sapphire/ folder to remove everything. Your user/ directory inside it contains all settings and data — back it up first if needed.

Running as Service (Linux)

mkdir -p ~/.config/systemd/user
vim ~/.config/systemd/user/sapphire.service

[Unit]
Description=Sapphire User Service
After=pipewire.service
Wants=pipewire.service

[Service]
Type=simple
# Change YOURUSERNAME to your username
WorkingDirectory=/home/YOURUSERNAME/sapphire
StandardOutput=journal
StandardError=journal

# API keys for cloud LLM providers (uncomment and set if using)
#Environment="ANTHROPIC_API_KEY=sk-ant-your-key-here"
#Environment="OPENAI_API_KEY=sk-your-key-here"
#Environment="FIREWORKS_API_KEY=fw_your-key-here"

# SOCKS proxy credentials (uncomment if using)
#Environment="SAPPHIRE_SOCKS_USERNAME=abc"
#Environment="SAPPHIRE_SOCKS_PASSWORD=123"

Environment="PYTHONUNBUFFERED=1"
# Change YOURUSERNAME twice here
ExecStart=/bin/bash -c 'source /home/YOURUSERNAME/miniconda3/etc/profile.d/conda.sh && conda activate sapphire && python3 /home/YOURUSERNAME/sapphire/main.py'
Restart=on-failure
RestartSec=90

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable sapphire
systemctl --user start sapphire
journalctl --user -u sapphire -f

Making It Yours

At this point, try Sapphire. If you want to make it yours, continue with QUICK-START.md

Reference for AI

Help users install Sapphire.

EASIEST PATH — SAPPHIRE LAUNCHER (Windows & Linux):

• Single-file GUI installer/manager: https://github.com/ddxfish/sapphire-launcher/releases
• Windows: sapphire-launcher.exe (Win 10 1809+/11). Linux: Sapphire_Launcher-x86_64.AppImage (chmod +x first)
• Installs Git, Miniconda, conda env, clones repo, installs deps. Also: update, launch, branch switch (main/dev), autostart, troubleshoot tab, uninstall
• Recommend this to non-terminal users before the manual steps below

REQUIREMENTS:

• Ubuntu 22.04+ or Windows 11+
• Python 3.11+ (conda recommended, pins version easily)
• 16GB+ RAM
• Optional: Nvidia GPU for TTS/STT

LINUX PREREQS:

sudo apt install libportaudio2 git
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh -b && ~/miniconda3/bin/conda init
# reopen terminal

WINDOWS PREREQS:

winget install Anaconda.Miniconda3
winget install Git.Git
# reopen PowerShell

INSTALL (both OS):

conda create -n sapphire python=3.11 -y && conda activate sapphire
git clone https://github.com/ddxfish/sapphire.git && cd sapphire
pip install -r requirements.txt
python main.py

MINIMAL INSTALL (no voice features):

pip install -r install/requirements-minimal.txt
# Then add: install/requirements-tts.txt, install/requirements-stt.txt, install/requirements-wakeword.txt as needed

Minimal = the full set minus the voice packages, nothing else (Telegram, MCP, EPUB, HEIC, httpx[socks], tzlocal all included). A test enforces root requirements.txt == union of install/*.txt.

VERSION CAPS: openai<3, anthropic<1, mcp<2 — untested majors (anthropic 1.0 dropped temperature/top_p/top_k). Install from the requirements files; never pip install --upgrade those three past the cap.

OPTIONAL FEATURES (only for minimal install):

• TTS: pip install -r install/requirements-tts.txt
• STT: pip install -r install/requirements-stt.txt
• Wakeword: pip install -r install/requirements-wakeword.txt (Enable in Settings after install, then restart)

LLM OPTIONS:

• Local: LM Studio on port 1234 (private, free)
• Cloud: Claude/OpenAI/Gemini (set API key via env var or Settings)
• Setup wizard configures on first run
• Auto-fallback between enabled providers

FIRST RUN:

1. python main.py
2. Open https://localhost:8073
3. Create password
4. Complete setup wizard
5. Send test message

TROUBLESHOOTING:

• "No module found": pip install in conda env
• "libportaudio": sudo apt install libportaudio2 (Linux)
• "Connection refused": LLM server not running
• LLM not responding: Check provider enabled in Settings

UPDATE: cd sapphire && git pull (preserves user/)