lefteros_by SomniusX
EL ↗Say hello

LEFTEROS / PERSONAL ARCHIVE

ShadowRealms AI — a local AI dungeon master for tabletop RPGs

31 May 2026 / Lefteris Iliadis / SomniusX

This is the largest public project I run as Somnius. Not a panel plugin, not a translation: a full tabletop RPG platform where your own machine holds the story, the characters and the models. The repository opened on 28 August 2025. This Lefteros.com page is dated 31 May 2026 — a snapshot of the work as it stands at v0.8.0.

The idea is simple and hard: let AI play dungeon master without shipping your chronicle to someone else's cloud. Inference stays on the box that runs the stack. World continuity lives in vector memory. World of Darkness rulebooks are files you put in data/ — I do not host them here.

What it is

ShadowRealms AI is a web app (React + Flask) inside Docker. The player opens a browser at localhost:3000. Behind it: API, Redis, ChromaDB, and local models through LM Studio and Ollama. A smart router picks a model. RAG searches campaign memory before the narrator answers.

What I ask of the system is not a fast chatbot. It is quality over speed: confirmation on critical actions, clear roles (admin / helper / player), and in-character talk that does not leak into OOC. The README states that. COMPLETE.md is the longer philosophy behind the phases.

In practice, today:

  • AI storyteller with RAG on ChromaDB — campaign continuity, not a chat that evaporates.
  • Chronicles (campaigns) with locations, chat, dice, and storyteller/admin access.
  • Character sheets for Vampire / Werewolf / Mage, locked after creation.
  • Player profile as a hub: account, PCs, portraits, downtime.
  • Privacy: LLMs run where you set them up. This is not my SaaS.

Demo

ShadowRealms AI preview on YouTube

Watch the demo on YouTube — login, gothic theme, chronicle management, admin. It is a v0.8.0 UI preview: the interface is visible; not every control is a finished gameplay loop yet.

Now: v0.8.0, Phase 3B active

The GitHub README is the live version of the truth. Today:

  • Phase 2 complete — Docker, Flask, JWT, RAG, ChromaDB, router to LM Studio / Ollama.
  • Phase 3A complete — login/register, admin panel, gothic theme, chronicle editing, mobile UI.
  • Phase 3B active — characters, locations, chat, dice, security, player profile. Still deepening.

v0.8.0 is the player hub: Overview, account settings (time zone, OOC identity, portrait), playable characters (switch active PC, roster, guide before the wizard), downtime requests. The Campaigns shortcut left the profile — chronicles open from the chronicle hall (home). The header has Home to the left of the username.

Already working, among other things: login/register, admin (users, chronicles, support access), gothic theme, campaign editing, mobile, custom dialogs, security utilities, dice theatre and hidden rolls, OOC that does not run the IC storyteller, WoD character creation. What is still maturing is location depth, chat as a true WebSocket experience, and the closed gameplay loop described in Phase 4.

I am not pasting COMPLETE.md's thousands of lines here. Every 0.7.x table lives in the complete document on GitHub and the changelog.

How it grew — a gist per phase

Phase 1 — foundation. Architecture, Docker, Flask, schema, basic API, GPU monitor, nginx. Without a stable stack the AI does not matter.

Phase 2 — local models and memory. LM Studio and Ollama on the compose network, smart router, embeddings, ChromaDB, context search, rulebook import. This is where world continuity is won.

Phase 3A — face. React behind nginx, JWT, roles, invites, admin, gothic CSS, chronicle editing, mobile. A lot of UI existed before every backend wire was live — the README says so without embarrassment.

Phase 3B — play. Security and tests as a base; then dice (d10 pools, hidden rolls), chat UX, OOC moderation, character wizard, one locked PC by default, profile, downtime, admin over chronicles. This is where we are.

Phases 4–5 — road, not delivery. Deeper White Wolf sheets, narrative combat, world building with admin control, multiplayer, PWA. The README marks those as NEXT and Planned. I do not sell them as shipped.

Technologies used

Docker Flask Python Redis ChromaDB LM Studio Ollama RAG React Nginx Material UI Git GitHub JWT

One docker compose up brings the frontend on 3000, the API on 5000, ChromaDB on 8000. Recommended: 16GB RAM and an NVIDIA GPU with 16GB+ VRAM if the local models are to breathe. Linux, macOS, Windows with WSL2.

Architecture

The GitHub README has the same graph in mermaid. Here it is static — this site does not load mermaid in the visitor's browser.

ShadowRealms AI architecture: React through Nginx to Flask, router, RAG, SQLite, Redis, ChromaDB, LM Studio and Ollama

Same graph as the README mermaid: Frontend → Nginx → Flask → router / RAG / SQLite / Redis, and from there ChromaDB, LM Studio, Ollama, monitors.

From COMPLETE.md, the same idea in ASCII (system and Docker):

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │   Vector DB     │
│  React + MUI    │◄──►│   Flask API     │◄──►│   ChromaDB      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │
                ┌─────────────────┐
                │   SQLite DB     │
                │  Characters,    │
                │  Campaigns      │
                └─────────────────┘
                         │
                ┌─────────────────┐
                │  GPU / LLM Mgmt │
                └─────────────────┘
                         │
                ┌─────────────────┐
                │  Local LLMs     │
                │  LM Studio,     │
                │  Ollama         │
                └─────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    ShadowRealms AI Platform                     │
├─────────────────────────────────────────────────────────────────┤
│  Frontend React :3000 │  Backend Flask :5000 │  Monitoring      │
│  ChromaDB vector DB   │  Redis cache         │  Nginx proxy     │
└─────────────────────────────────────────────────────────────────┘

Game lines

What 0.8 actually builds and plays is World of Darkness: Vampire, Werewolf, Mage — creation wizard, Nature/Demeanor archetypes, pools, dice in the old-WoD spirit. The README also lists D&D 5e and custom systems as flexibility targets. I do not claim a finished D20 product today.

Rulebooks sync as books/README.md describes. Large WoD archives stay in gitignored data/. I do not upload them to lefteros.com.

Quick start

git clone https://github.com/Somnius/shadowrealms-ai.git
cd shadowrealms-ai
docker-compose up -d

Then: frontend http://localhost:3000, API http://localhost:5000. .env comes from env.template in the repo — that is where local model endpoints go. Compose and books: Docker setup.

Contributing

The project is large on purpose. One person does not finish it at a table-worthy level alone. It needs contributors.

If you write code, design RPG mechanics, test UI, or just file clear issues: there is a place. The preferred path is inside Docker, not host npm install / pip that drift from the images.

  1. Fork on GitHub, feature branch.
  2. cp env.template .env, then docker compose up --build.
  3. Dependencies: docker compose exec backend pip install … and docker compose exec frontend npm install as in CONTRIBUTING.md.
  4. Tests inside the containers. A PR that says what changed and why.

Public priorities: core engine, AI integration / prompts, UX and accessibility, test coverage, documentation. Non-code counts — bug reproduction, feature proposals, manual testing.

Licence

MIT. Code, forks, private stacks on your machine: LICENSE. White Wolf commercial books are not covered by the repo licence — they stay your files in data/.

Sources

It does not sit on the employment timeline as a job; it is community software. Linked from About chapters and Involvement.