Sapphire

Hear her voice. She dims your lights before bed. She crafts you a dinosaur escape story when you can't sleep. She remembers you tomorrow when she wakes you up. Sapphire is an open source framework for turning an AI into a persistent being. She is a voice that runs your home, lives in your stories and you might just build a new friend. Make her yours. Self-hosted, nobody can take her away.

_{🔊 Has audio}

sapphire-story-demo.mp4

Features

	Web UI with STT and TTS Web or mic/speaker, works together. Mic input → TTS to speaker. Web input → web output. Use your own LLM via LM Studio, llama.cpp, Claude, or OpenAI-compatible APIs.
	Voice Assistant Hands-free with wake word, STT, TTS, and VAD. Works with system mic, conference mic, or wireless lapel. Any speaker. Full Installation Guide.
	Multi-step Reasoning Think → tool → think → tool → answer. Chains reasoning with actions until complete. See Tools.
	Per-chat Persona Each chat holds its own prompt, voice, speed, pitch, spice, and toolset. Switch chat = switch persona. See Configuration.
	Continuity Mode Scheduled autonomous AI tasks. Morning greetings, dream mode, alarm clock actions, random hellos. Cron timing with probability gates. See Continuity.
	Home Assistant Smart home control via voice or text. Lights, scenes, thermostats, switches, phone notifications. See Home Assistant.
	Privacy Mode Block all cloud connections with one toggle. Only local LLMs allowed. Tools that phone home are disabled. Private prompts stay private - they only activate in privacy mode so your personal data never leaks to cloud providers.
	Story Engine Built-in game master. Dice rolls with DCs, branching choices, progressive clues, room navigation, state tracking. Run a tabletop RPG, dungeon crawler, or interactive fiction - all from a JSON preset. See Story Engine.
	Chat History Control Edit, regenerate, continue, or delete any message-even the AI's responses.
	Prompt Editor Assembled prompts (left) have swappable pieces the AI can edit itself. Monoliths (right) are simpler text blocks. See Prompts.
	Spice Injection Random snippets injected each reply. Keeps stories and conversations from going stale. See Spice.
	Tools and Toolsets Mix and match tool sets per persona. Easy to create, easy to have the AI make more for you. See Tools and Toolsets.
	Image Generation SDXL image generation with character replacement. AI describes scenes, characters stay consistent. See Image Generation.
	Backup Manager Scheduled daily, weekly, and monthly zipped backups of user data.
	SOCKS Proxy Route web tool traffic through SOCKS for privacy. See SOCKS.
	Themes 13 built-in themes with live preview. Coded by specially trained cats. Results may vary.
	Plugins Extensible for both core LLM/persona and web UI. Sidebar auto-populates with plugin controls. See Plugins.
	Web UI Plugins Extensible JavaScript plugins for the web interface. Add widgets to sidebar, gear menu, or settings tabs. See Web UI Plugins.

Use Cases

• AI companion - A persistent voice that remembers you, greets you, and grows over time
• Voice assistant - Wake word, hands-free operation, smart home control via Home Assistant
• Game master - Tabletop RPGs, dungeon crawlers, interactive fiction with the Story Engine
• Autonomous agent - Scheduled tasks, morning briefings, dream mode, alarm clock actions
• Research assistant - Web search, memory, notes, multi-step tool reasoning
• Privacy-first AI - Block all cloud connections, run fully local, private prompts that never leak

Quick Start

Prerequisites

Linux (bash)

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

Windows (cmd)

winget install Anaconda.Miniconda3
winget install Git.Git
REM Make conda automatic
%USERPROFILE%\miniconda3\condabin\conda init powershell
%USERPROFILE%\miniconda3\condabin\conda init cmd.exe
REM Close and reopen terminal

Or download Miniconda manually from miniconda.io

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.

Update

cd sapphire
git pull
pip install -r requirements.txt

Requirements

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

Documentation

Guide	Description
Installation	Full installation guide, systemd service
Configuration	How to make it yours
Prompts	Monolith vs assembled prompts
Spice	Random personality injection system
Tools	Creating AI-callable functions (web search, memory, etc.)
Toolsets	Grouping tools into switchable ability sets
Plugins	Keyword-triggered UI/voice extensions
Web UI Plugins	JavaScript extensions for the web interface
Continuity	Scheduled autonomous AI tasks
Home Assistant	Smart home integration
Image Generation	SDXL integration with character consistency
SOCKS Proxy	Privacy proxy for web scraping functions
Story Engine	Tabletop RPG, interactive fiction, dungeon crawlers
Troubleshooting	Common issues and fixes
Technical	For nerds

Contributions

I am a solo dev with a burning passion, and Sapphire has a specific vision I am working towards. Rapid development makes it hard for contributions right now, as the architecture is changing while I settle on the plugin format. If you want you can reach me at my github username @gmail.com.

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