Home

ShadowRealms AI Wiki

ShadowRealms AI is a self-hosted web app for playing tabletop RPGs (mainly World of Darkness) with an AI Storyteller. Everything runs on your own machine: Docker for the app, and a local LLM through LM Studio (plus Ollama as a small helper model).

This wiki is the practical side: how to install it, configure it, and fix it when it breaks. Design notes and history live in the repo under docs/ and in SHADOWREALMS_AI_COMPLETE.md.

A look inside

Login	Chronicle hall	A V5 bestial failure
V5 character sheet	Greek interface	Theme preview (/showcase)

More screenshots: assets/screenshots/v0.9.

Pages

• Installation: fresh install from zero, step by step
• Rules Editions: Classic (oWoD Revised) vs V5, dice and characters
• Configuration: the .env file and invite codes
• AI Models: LM Studio, Ollama, which models and why
• World of Darkness Books: getting rule books into RAG
• Architecture: what each container does and how they talk
• Security: logins, sessions, rate limits, the public site
• Troubleshooting: known problems and fixes
• Development and CI: tests, CI checks, security scanning
• Tech Stack: the AI models, technologies and tools used

Quick facts

Version	0.10.0 (changelog, roadmap)
Live instance	https://srai.srv-box.com
Backend	Python 3.12, Flask on gunicorn + PostgreSQL 16, ChromaDB 1.5.9 (bge-m3) for memory/RAG, Redis
Frontend	React 18 built with Vite, react-router 7 (static build served by nginx on port 80)
LLM	LM Studio on the host (localhost:1234), Ollama on the host (localhost:11434)
Tested on	Linux (Arch-based) with an NVIDIA RTX 4080 SUPER, 16 GB VRAM
License	MIT