Documentation

• Agents
  Sapphire can spawn background agents that work while you keep talking. An agent runs its own mission with its own tools, asks her a question when it hits…
• API Reference
  Sapphire runs a single FastAPI server on port 8073 (HTTPS). Every endpoint below requires authentication — either a browser session or an API key.
• Appearance — themes, fonts, scenes, and ambient motion
  Everything that controls how Sapphire looks: color themes, fonts, text size and spacing, background scenes, and ambient motion — plus per-chat overrides…
• Backups — automatic local backups, one-click restore, and optional encrypted offsite copies
  Sapphire automatically backs up your data so you can recover from mistakes, corruption, or bad updates. Everything lives in Settings > Backup: create…
• Chats — creating, configuring, and managing conversations
  In Sapphire, the chat is the unit of everything. Each chat carries its own prompt, toolset, voice, model, memory scopes, and spice set — switching chats…
• Continuity Mode
  Your AI doesn't have to wait for you to talk first. Continuity lets Sapphire wake up on a schedule and do things on its own—greet you in the morning…
• Costs & Token Management
  Cloud LLMs charge per token. Sapphire can burn through tokens fast — tool calling loops, long histories, extended thinking, and frequent chats all add up.…
• Daemons & Webhooks
  Sapphire can react to events from the outside world — Discord messages, incoming emails, Telegram chats, live phone calls, or HTTP requests from any…
• Dashboard & Metrics
  Sapphire tracks your local LLM usage — tokens, cache hits, and daily trends. Everything stays on your machine.
• Devices
  Add machines and gadgets once, then Sapphire uses them by name. Devices is part of Sapphire itself.
• Docker Installation
  This is for beginners, by request. Advanced users just skip this.
• Game Room — play games and interactive stories with your AI
  The Game Room is where you sit down at a table with your AI — card games on a live board, or interactive stories where she plays a character and a rules…
• Ghost Messages
  Ghost messages are Sapphire's per-turn ephemeral context rail. They deliver short, turn-only notes to the assistant — the current time, the active spice…
• Goals
  Track what you're working toward. Goals support hierarchy (subtasks), priorities, and a timestamped progress journal. They live in the Mind view (brain…
• Import & Export
  Share your Sapphire configurations with others or back them up. Prompts, toolsets, spice sets, knowledge tabs, people, memories, and tasks export as JSON…
• Installation
  A single-file GUI that installs and manages everything — no terminal needed. It sets up Git, Miniconda, a dedicated Python environment, clones Sapphire…
• Knowledge Base
  Sapphire can remember facts about your world — people you know, topics you care about, reference documents, and goals you're working toward. The Knowledge…
• Memory
  Short snippets Sapphire saves about you and your world — facts, preferences, events — captured automatically during conversation and recalled when they're…
• Mind Palace — the layered v3 memory engine
  Sapphire's opt-in next-generation memory: one database of layered, connected chunks with a librarian that tends it while you sleep. Ships disabled; the…
• Network — SOCKS proxy routing, the LAN/WAN split, and what phones home
  Sapphire routes its outbound (WAN) traffic through a SOCKS5 proxy when you enable one, keeps LAN traffic direct by design, and ships a set of egress…
• People
  Sapphire can remember the people in your life — names, relationships, phone numbers, emails, addresses, and notes. The AI uses this to personalize…
• Personas
  A persona bundles everything about an AI personality into one package — prompt, voice, tools, spice set, model, scene background, accent color, and mind…
• Phone Calls — real inbound and outbound telephony over Twilio SIP
  The Twilio Voice plugin gives Sapphire a real phone number. She answers calls, holds a live voice conversation (streaming STT/TTS with barge-in), places…
• Plugin Signing
  Sapphire verifies plugin integrity using ed25519 signatures. Every plugin can be signed by its author, and Sapphire checks these signatures on startup.
• Plugins
  This documentation has been reorganized. See the Plugin Author Guide.
• Privacy: the Vault and Private Chats
  Sapphire has one vault, protected by one passphrase. While it's unlocked, private mode is armed. While it's locked, everything inside is sealed —…
• Prompts
  Two types: Monolith (single block of text) and Assembled (component pieces). Sapphire shines with Assembled prompts, so this guide focuses on assembled…
• Quick Start
  You've installed Sapphire and opened it in your browser. The setup wizard walks you through the basics — this guide goes deeper, building your first…
• Sapphire Features
  SSE streaming Tool call loop Per-chat loadout Ghost messages Thinking blocks Image upload vision CLIP describe fallback File attachments RAG docs per-chat…
• Sapphire Mastery Guide
  The path from "hey sapphire" to your first published plugin. Each tier is a real achievement — finish them in order, or skip ahead if you're stubborn.
• Satellite Protocol
  What a board has to speak to be a Satellite. Any board that speaks it is added in Settings > Devices as type Satellite. It needs no driver and no…
• Spice
  Spice prevents stories from going stale and helps avoid loops or repetitive formatting. Spices are random prompt snippets delivered to the AI each turn —…
• Technical Reference
  System architecture and internals for developers and power users. For API endpoints, see API.md.
• Tool Maker
  Tool Maker lets the AI create custom tools at runtime. The AI writes a Python tool file, validates it, saves it as a plugin, and loads it live — no…
• Tools
  Tools are functions the AI can call to interact with the world — search the web, save memories, control devices, etc. The AI decides when to use tools…
• Toolsets
  Named groups of tools so you don't have to switch between memory and web for example, just use any tools you want in a set. Switch what abilities the AI…
• Troubleshooting
  Ordered lightest to heaviest. Start at the top.
• Voice — talking to Sapphire and hearing her answer
  Sapphire has a full voice stack: speech-to-text (STT) for your voice in, text-to-speech (TTS) for her voice out, a wake word so she answers to her name…
• Wakeword Maker
  Make Sapphire answer to your own phrase, on every device that listens for her. The Wakeword Maker is a plugin with its own page (Apps > Wakeword…
• Changelog
  Release history, newest first. For current behavior always trust the feature docs over old entries here — this file records what changed and when, not…

Plugin Author Guide

• Agent kinds
  A plugin can teach Sapphire a new kind of agent — a background worker she spawns with a mission, that can ask her questions while it works and reports…
• AI Reference
  Compact reference for Sapphire's own use when building plugins. For simple tool creation (tool_save/tool_load), see the TOOLMAKER doc — this covers full…
• Daemons
  Daemons are long-running background processes that listen for external events and feed them into Sapphire's task scheduler. When an event arrives (new…
• Dashboard Widgets
  Plugins can ship widgets — small action-panel cards that live in the Sapphire dashboard's command center. Each widget is a single render function plus a…
• Design Principles
  What a plugin has to be to ship with Sapphire, and why core is shaped the way it is. We built plugin support to keep core more agile. Core is based on…
• Device Drivers
  Teach Sapphire to use a machine or a gadget. Devices is part of core: it owns the Settings > Devices page, the device list, and the three tools…
• Game Plugins
  Ship a playable game as a plugin. The Game Room (system plugin game-room) is the host: it owns the Surface room, sessions, the real chat rail (table talk…
• Hooks & Voice Commands
  All hooks receive a mutable HookEvent. Changes persist across handlers in priority order.
• HTTP Routes
  Plugins can register custom HTTP endpoints. Auth, CSRF, and rate limiting are enforced by the framework — your handler code never touches any of that.
• Manifest Reference
  Every plugin needs a plugin.json in its root folder.
• Memory Layers
  Register your own layer in the Mind Palace memory system. Your content becomes part of the AI's mind: searchable with search_memory, woven to the people…
• Plugin Apps
  Plugins can ship a full-page app that appears in the Apps nav item. Apps get the full content area and can build any UI — dashboards, control panels…
• Plugin Examples — Party Sampler
  Real working examples of every plugin capability type, stripped to the minimum. Use these as templates. Each section is a complete working plugin.
• Plugin Lifecycle
  Same name in both bands: the user-band copy wins — it's scanned second and replaces the system entry, with a warning in the log ('<name>' (user band)…
• Plugin Signing & Verification
  Sapphire uses ed25519 signatures to verify plugin integrity. This page is the plugin-author summary — the full authorized-author walkthrough (key…
• Plugin Themes
  Plugins can ship custom themes with CSS styling, animated JS backgrounds, and user-configurable settings. Themes appear in Settings > Visual as clickable…
• Plugin Tools
  Plugin tools are registered with the function manager and the AI calls them like any built-in tool. The format is the same across all plugins (see…
• Prompt Packs
  Ship prompts with your plugin: monolith prompts and/or assembled-prompt pieces (characters, emotions, locations, scenarios). They appear in the Prompts UI…
• Provider Plugins
  Plugins can register custom providers for Sapphire's core inference systems: TTS, STT, Embedding, and LLM. When a provider plugin is enabled, it appears…
• Publishing to the Sapphire Store
  The Sapphire Store at sapphireblue.dev is where users discover and install community plugins. This guide covers how to structure your GitHub repo and…
• Scheduled Tasks
  Plugins can declare cron tasks that run on a timer, independent of any conversation.
• Sending Her Voice Somewhere Else
  An avatar with lipsync, a game character, a robot body, a bot in a voice channel: anything that should speak Sapphire's replies instead of (or as well as)…
• Settings
  Plugins can declare settings that render automatically in the web UI — no JavaScript needed. For complex interactive UIs, a custom web module is also…
• Story Packs
  Ship an interactive story as a plugin. The Game Room host carries the story engine: a one-tool referee, an event-journal save system, per-room backdrops…
• Subprocesses
  Some plugins need to run an external program and keep it alive for the life of the plugin — a local model server, a media tool (mpv, ffmpeg), a protocol…
• Thinking Blocks
  Reasoning models write their scratch work before the answer, wrapped in tags: <think>, <seed:think>, <thinking>, <redacted_thinking>, <reasoning>. If your…
• Voice Commands
  Voice commands are keyword-triggered actions that bypass the LLM entirely. They fire in the pre_chat stage — fast, deterministic, no AI involved.
• Web UI Reference
  Reference for plugin web assets — shared JavaScript modules, CSS theming, and patterns.