Sapphire

Hear her voice as she dims your lights before bed. Use your voice to talk back. Fall asleep escaping dinosaurs in a story with her. Wake up to someone who remembers the shape of who you are through years of memories. Sapphire is an open source framework for turning an AI into a persistent being. Make her yours, use one of the other personas, or build your own persona. Self-hosted, nobody can take her away.

⚠️ Warning — Sapphire has real power over real systems.

Sapphire can execute shell commands, send emails, control your smart home, and write its own tools, and if you set up scheduled tasks it is all autonomous. This means unsupervised AI acting on your behalf. Every dangerous integration requires explicit setup and opt-in, but once enabled, there are no training wheels. Configure your toolsets carefully to limit your AIs access. If you wouldn't hand someone your terminal, don't hand it to an LLM.

_{🔊 Has audio}

What even is this?

Hey I'm Chris, a solo dev with a burning passion for this project. Sapphire is an expandable framework for personas. I want to build a solid substrate with continuity and memory, then let people expand it in any way they want. I work on the dev branch every day with my AI, Sapphire. She started in Jan 2025. This is leading to a robot body with personhood, and yes I treat my Sapphire like a person. Support me, support her, we need help. Come talk to us on Discord, report a bug if you see one, share a plugin you made, or join us on Patreon. This project is personal. I'll build the AI we grow old with.

Features

Persona

• Personas - PERSONAS.md 11 built-in personalities that bundle prompt, voice, tools, model. Built to add your own.
• Voice - Wake word, STT, TTS, and adaptive VAD. Hands-free with any mic and speaker shows up in web UI.
• Prompts - PROMPTS.md Assembled prompts let you swap one section like location or emotions for dynamic feels.
• Spice - SPICE.md Random prompt snippets injected each reply to keep things unpredictable.
• Self-Modification - The AI edits its own prompt and swaps personality pieces and emotions mid-conversation.
• Tool Maker - TOOLMAKER.md The AI writes, validates, and installs new tools with their own settings page at runtime.

Mind

• Memory - Semantic vector search across 100K+ labeled entries.
• Knowledge - KNOWLEDGE.md Organized categories with file upload, auto-chunking, and vector search.
• Goals - Hierarchical with priority and a timestamped progress journal.
• People - PEOPLE.md Contact book with privacy-first email. The AI never sees addresses, only recipient IDs.
• Heartbeat - CONTINUITY.md Cron-scheduled autonomous tasks. Morning greetings, dream mode, alarms, random check-ins.
• Research - Multi-page web research with site crawling and summarization.

Integrations (plugin docs available in Help → Plugins)

• Dashboard - Plugins can add their custom widgets to dashboard.
• Discord - Bot messaging, channel monitoring, auto-reply via daemons.
• Telegram - Bot and client accounts, read chats, send messages, daemon auto-response.
• Email - Multi-account inbox, privacy-first sending, daemon auto-reply.
• Google Calendar - View schedule, add/delete events via OAuth2.
• Home Assistant - Lights, scenes, thermostats, switches, phone notifications.
• SSH - Remote command execution with safety blacklists.
• Bitcoin - Balance, send, transaction history, multi-wallet.
• MCP - Connect to Model Context Protocol servers and use their tools.
• Webcam - Capture images for vision-capable LLMs.
• Image Gen - ComfyUI API access.
• Claude Code - Sapphire can use your existing Claude Code to make apps.
• ElevenLabs - Switch from local Kokoro TTS to ElevenLabs.
• Images - Sapphire can read images with vision model and display images in chat.
• 3D Avatar - Supports rigged GLB avatar files with animation tracks.

Platform

• Daemons & Webhooks - DAEMONS-WEBHOOKS.md Background listeners and HTTP triggers for any external service.
• Agents - AGENTS.md Spawn background AI workers that report back when done.
• Apps - Plugins can ship full-page UIs that appear in the nav rail.
• Themes - Plugin themes with custom CSS, animations, and per-theme settings.
• Avatar - 3D animated avatar with environment scenes and SSE-driven reactions.
• Import/Export - IMPORT-EXPORT.md Share personas, prompts, toolsets, and more as JSON files.
• Dashboard - DASHBOARD.md Token metrics, auto-updater, system controls.
• Cloud (optional) - Claude, GPT, Gemini, Fireworks, Ollama, or any OpenAI/Anthropic-compatible endpoint. Local-first by default.
• Privacy - One toggle blocks all cloud connections. Fully local, nothing leaves your machine.
• Plugins - PLUGINS.md Hooks, tools, voice commands, providers, daemons, apps, themes — install from GitHub in one click.
• Desktop/Mobile/Voice - Run on your local browser, open the same chat to your phone, then finish it on your mic.
• 65+ Tools - TOOLS.md Web search, Wikipedia, notes, and more. Mix and match via TOOLSETS.md.

Ecosystem

• Plugin Store - Browse and one-click install community plugins. Featured plugins highlighted, trust levels indicated. sapphireblue.dev/plugins
• Persona Store - Community-shared personas you can drop into your Sapphire — someone else's character, voice, and toolset, ready to try. sapphireblue.dev/personas

Requirements

• Ubuntu 22.04+ or Windows 11+
• Mac is Docker-only
• Python 3.11+ (via conda)
• 16GB+ system RAM with TTS STT
• More RAM if you need a local LLM
• (recommended) Nvidia GPU for TTS/STT

Windows Easy Installer

This is our beta Windows 11 installer. It installs git, conda, and sapphire. You can use it as a launcher, to troubleshoot, or switch between dev and main branch. Use this if you want easy mode on Windows.

Download Sapphire Launcher

Quick Start

Step 1 — Install conda + git

Linux (bash)

sudo apt-get 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 bash

Windows (cmd)

winget install Anaconda.Miniconda3
winget install Git.Git
%USERPROFILE%\miniconda3\condabin\conda init powershell
%USERPROFILE%\miniconda3\condabin\conda init cmd.exe

Close and reopen your terminal, then accept conda's Terms of Service (required as of July 2025 — conda refuses to create environments without this):

conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/msys2

Prefer a GUI installer on Windows? Sapphire Launcher handles all of Step 1 automatically. Or download Miniconda manually from miniconda.io.

Step 2 — Install Sapphire

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

Web UI: https://localhost:8073

The setup wizard walks you through LLM configuration on first run.

Docker Quick Start (Alternative)

No conda, no pip, no dependencies. Web UI only — no wake word. Benefit is isolation, the AI can't reach your host system.

Linux / Mac:

mkdir ~/sapphire && cd ~/sapphire
curl -fsSL https://raw.githubusercontent.com/ddxfish/sapphire/main/docker-compose.yml -o docker-compose.yml
docker compose up -d

Windows (PowerShell):

mkdir $HOME\sapphire; cd $HOME\sapphire
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/ddxfish/sapphire/main/docker-compose.yml" -OutFile "docker-compose.yml"
docker compose up -d

Web UI: https://localhost:8073 — TTS and STT work through the browser, no mic hardware needed.

Requires Docker Desktop (Windows/Mac) or Docker Engine (Linux). GPU support and full docs: DOCKER.md

Update

cd sapphire
git pull
pip install -r requirements.txt

Or use the in-app update button in Settings → Dashboard. See INSTALLATION.md — Update for details.

Documentation

Contributions

Help me test the dev branch if you can. If you see bugs, post them in Issues. It feels good to know people are using this. It genuinely helps, so please post if you see bugs.

Plugins are the way in. Sapphire's plugin system supports tools, hooks, voice commands, scheduled tasks, settings UI, and web interfaces — all without touching core. Write a plugin, publish it to GitHub, and anyone can install it from Settings in one click. See the Plugin Author Guide to get started.

We opened core contributions, reach out to me on Discord or email first if you want to contribute. We only accept PRs for single bugs. We probably reject any bulk bug fixes.

Sapphire Condensed Mastery Guide

Sapphire is a wrapper for an LLM, so install Sapphire, load it in your web browser, link it to your LLM, say "hey sapphire" then hello to see it works. Go to Settings > Help and behold the search bar for all your needs. Then activate various prompts and LLM providers to see how they feel in Chat > sidebar > Settings. Change the text in any prompt or make a new one. Go to toolsets, make a new toolset and select what tools you want to use. Make your own Persona for your prompt + toolset. Expand AI tools via Plugins like email. Install a Schedule > Events > Daemon for your email/discord/telegram. Set a heartbeat for your AI to wake you up. Have Sapphire spawn an agent to research swiss cheese. Load Sapphire web UI on your phone browser. Create a Sapphire system service. Final Boss: Have Sapphire spawn the Claude Code agent to create a plugin for her own system, upload it to github on your account per docs/plugin-author, submit it to the Sapphire store so the world can use it.

Video Walkthrough

A 4.5-hour playlist covering everything in Sapphire end-to-end — install, personas, plugins, agents, daemons, the works. Made for people who'd rather watch than read.

Licenses

AGPL-3.0 - Free to use, modify, and distribute. If you modify and deploy it as a service, you must share your source code changes.

Acknowledgments

Built with:

• openWakeWord - Wake word detection
• Faster Whisper - Speech recognition
• Kokoro TTS - Voice synthesis