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 you through years of memories. She checks your email on a heartbeat. She builds tools on the fly when you need them. Sapphire is an open source framework for turning an AI into a persistent being. Make her yours. 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 Bitcoin, send emails, control your smart home, and write its own tools — all autonomously, without asking first. Combined with scheduled tasks, 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. If you wouldn't hand someone your terminal, don't hand it to an LLM.
🔊 Has audio
sapphire-dino-intro.mp4
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.
- Stories - STORY-ENGINE.md Interactive stories, the AI is your dungeon master and partner, can't see the next room.
- Images - IMAGE-GEN.md SDXL with character replacement for visual consistency across scenes.
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
- Home Assistant - HOME-ASSISTANT.md Lights, scenes, thermostats, switches, phone notifications.
- Bitcoin - Balance, send, transaction history, backup wallet.
- SSH - Local and remote command execution on configured servers.
- Email - Inbox, send to whitelisted contacts. AI resolves recipients server-side.
- Cloud (optional) - Claude, GPT, Fireworks. Only active when you enable them. Local-first by default.
- Privacy - One toggle blocks all cloud connections. Fully local, nothing leaves your machine.
- Plugins - PLUGINS.md Hooks, tools, voice commands, scheduling, web settings — all in one system.
- 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.
- Autonomous agent - Scheduled tasks, use email, manage money, run its own website
- AI companion - A persistent voice that remembers you and grows over time
- Voice assistant - Wake word, hands-free operation, smart home control
- Research assistant - Web search, memory, knowledge base, multi-step tool reasoning
- Interactive fiction - Story engine with dice, branching choices, and state tracking
- Privacy-first AI - Block all cloud connections, run fully local
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 terminalwinget 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 terminalOr download Miniconda manually from miniconda.io
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.pyWeb UI: https://localhost:8073
The setup wizard walks you through LLM configuration on first run.
cd sapphire
git pull
pip install -r requirements.txtVersion 2.0 has new dependencies that usually 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.txtconda deactivate
conda remove -n sapphire --all -yThis removes the Python environment. Delete the sapphire/ folder to remove everything. Your user/ directory inside it contains all settings and data.
- Ubuntu 22.04+ or Windows 11+
- Python 3.11+ (via conda)
- 16GB+ system RAM
- (recommended) Nvidia GPU for TTS/STT
| Guide | Description |
|---|---|
| Installation | Setup guide, systemd service |
| Configuration | LLM, scopes, thinking, privacy |
| API | All 221 REST endpoints |
| SOCKS Proxy | Privacy proxy for web tools |
| Troubleshooting | Common issues and fixes |
| Technical | Architecture and internals |
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.
For core contributions or ideas, reach me at ddxfish@gmail.com.
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.
Built with:
- openWakeWord - Wake word detection
- Faster Whisper - Speech recognition
- Kokoro TTS - Voice synthesis