Start Here
What LocalRPG is, and the order to read the guides in.
LocalRPG is a local-first, turn-based tabletop RPG client: one Go binary that serves a desktop app, a terminal client and an HTTP API over the same engine. It doesn't need an account or a network connection, and nothing about a campaign is hidden behind a service.
The engine is schema-agnostic. No hit points, mana or character classes are built in; systems and worlds are files you author, and the app reads them. Read that first, because it explains why the guides spend so long on file formats.
Where to begin
- Architecture & Core Concepts - Schema-agnostic design, three-tier separation, and how AI agents drive tabletop adventures.
- Campaigns & Turns - The turn lifecycle, canonical history log, non-destructive rewinding, and living-world progression.
- Building Worlds Studio Guide - Walkthrough for creating custom worlds, defining lore prompts, and authoring starter entities.
- Building Custom Systems Guide - Authoring system rules prompts, coding mechanics.js hooks, and testing dice expressions.
- AI & Media Providers - Configuring LLMs, voice synthesis, speech recognition, image generation, and spend tracking.
- Local-First and Offline Play - What runs locally in LocalRPG, what hardware each tier requires, and how to configure a zero-network tabletop stack.
Every guide
Grouped as the app's own documentation viewer groups them: one section per category, in the order the categories first appear.
Core Concepts
- Architecture & Core Concepts - Schema-agnostic design, three-tier separation, and how AI agents drive tabletop adventures.
- Worlds & Lore - Anatomy of a world, starting location resolution, and system overrides.
- Systems & Mechanics - Rules prompts, action modes, dice expressions, and the sandboxed JavaScript mechanics engine.
- Campaigns & Turns - The turn lifecycle, canonical history log, non-destructive rewinding, and living-world progression.
Configuration & Providers
- AI & Media Providers - Configuring LLMs, voice synthesis, speech recognition, image generation, and spend tracking.
- AI Agents & Roles - Assigning models to GM, Narrator, and Extractor roles, plus token budgets and fallback chains.
- Storage & Directories - Standard XDG directories, workspace mode, and disposable SQLite caching.
- Usage, Cost & Pricing - Reading the spend ledger and setting the provider prices that turn usage into a cost figure.
- Provider & Model Catalogue - Every registered provider ID, its presets and models, and the ledger key that prices match against.
- Configuration Reference - Every key LocalRPG reads from config.yaml, with the accepted values for the enumerated ones.
- Style Packs - Theme the procedural art and the app chrome with a pack, or keep the built-in look.
- Trace & Telemetry - Record what a turn did in a local JSONL trace, or export spans and metrics to an OpenTelemetry collector.
Studio Guides
- Building Worlds Studio Guide - Walkthrough for creating custom worlds, defining lore prompts, and authoring starter entities.
- Building Custom Systems Guide - Authoring system rules prompts, coding mechanics.js hooks, and testing dice expressions.
- AI World Generation - Draft a world from a sentence, a folder, or a set of pages, then review it before it is committed.
Codex & Content Reference
- Codex YAML Frontmatter & Graph Reference - Complete YAML frontmatter schema, entity types, custom state, and wikilink graph modeling.
- Editing Content Outside the App - The on-disk and package formats as the interchange contract, so systems, worlds, and campaigns can be edited in any editor.
Local AI & Self-Hosting
- Setting Up Ollama for Local LLMs - Hardware requirements, native/Docker setup, recommended models for tabletop RPGs, and connecting Ollama to LocalRPG.
- Setting Up Kokoro-FastAPI for Neural TTS - Running Kokoro-FastAPI via Docker (CPU/GPU), voice profile selection, and connecting to LocalRPG.
- Setting Up Fish Audio S2 with vLLM-Omni - GPU requirements, Docker/vLLM-Omni container setup, voice cloning, and how emotion tags steer the performance.
- Setting Up Faster-Whisper for Speech Recognition - OpenAI-compatible speech-to-text server setup via Docker, hardware considerations, and LocalRPG voice input configuration.
- Setting Up ComfyUI for Local Image Generation - ComfyUI API configuration, model setup (SDXL/Flux/SD1.5), and connecting LocalRPG for scene and entity illustration.
- Fully Local AI Stack with Docker Compose - One Docker Compose project that runs Ollama, Kokoro, Faster-Whisper, and ComfyUI together, with recommended models, system requirements, and the matching LocalRPG configuration.
- Local Semantic Search with a Built-in Encoder - How LocalRPG turns entities and turns into searchable vectors, why the default projection ranks unrelated words together, and how to switch on the built-in BGE encoder that separates them.
- Local-First and Offline Play - What runs locally in LocalRPG, what hardware each tier requires, and how to configure a zero-network tabletop stack.
Command Line & Terminal
- Command-Line Reference - Every command, its flags, what it prints, and the exit code it leaves behind.
- The Terminal Client - The keys, action modes, and slash commands for playing a campaign in a terminal.
Using the App
- The Desktop App - A tour of the desktop window, from the launcher to the campaign screen, its drawers, and the settings panels.
- Story Theatre, Audio & Portraits - Replay a campaign as a visual novel, control the spoken lines, and give characters portraits.