Sign-in	Chronicle hall	Bestial failure

V5 character sheet	Playing in Greek	Theme preview

More: all v0.9 screenshots with captions and a V5 roll, animated.

ShadowRealms AI is a web app for running World of Darkness chronicles with an AI Storyteller. You host it yourself: Docker for the app, and local language models through LM Studio and Ollama, so the stories stay on your machine. Every chronicle is either Classic (oWoD Revised) or V5, and the interface and the Storyteller work in English and Greek.

• Each chronicle picks Classic (Vampire, Werewolf, Mage on the Revised rules) or V5 (Vampire: The Masquerade 5th edition) when it's created, and keeps it.
• Classic dice follow Revised: difficulty 2 to 10, 1s cancel successes, a botch only when nothing succeeded, specialties re-roll 10s, Willpower as one uncancellable success.
• V5 dice: Hunger dice, pairs of 10s, messy criticals, bestial and total failures, Willpower rerolls, Rouse checks.
• The Storyteller's prompt and the rule-book search follow the chronicle's edition. The rules as the app implements them: Classic and V5.

• Discord-style chat: grouped messages, unread counts, jump to present, in-character and out-of-character rooms.
• Live updates over server-sent events (falls back to polling).
• Dice cards: rolls are made and posted by the server, so a dice card in the chat is always a real roll.
• When the Storyteller calls for a roll, the server works out the pool from your sheet (specialties, Hunger, impairment) and the chat shows a roll chip that fills in the dice dialog.
• Copy, reply (with a quote) and delete on messages: players delete their own, the Storyteller and admins delete any. Scroll up to load older history.
• Slash commands with autocomplete: /roll, /me, /chat for everyone, and /ai commands for admins (/ai help lists them).
• One "Speaking as" control: your character, yourself out of character, or the Storyteller voice for staff.

• A character forge per edition: Classic with the Revised budgets (7/5/3, 13/9/5, virtues, 15 freebies), V5 with attribute and skill spreads, Predator type, disciplines, advantages and flaws.
• Read-only sheets with trackers (Hunger, Willpower, Humanity), portraits, and one playing character per chronicle.
• Sheets lock after creation; later changes go through downtime requests the Storyteller approves.

• Roles instead of one model: English Storyteller, Greek Storyteller, utility and classifier, each set in the admin panel.
• Greek replies with llama-krikri-8b-instruct; the Storyteller answers in the player's language.
• Long-term memory and rule-book search with multilingual bge-m3 embeddings in ChromaDB.
• OOC rooms are moderated by the Laya classifier (trained locally from ml/laya/) or the loaded LLM; warnings and bans apply per chronicle.
• Optional cloud providers: an admin can add Anthropic or OpenAI API keys (stored encrypted, off by default).

• 97 original SVG glyphs and sigils, animated dice, fog, candle glow and blood effects on botches.
• An atmosphere setting per account: Full, Subtle or Off.
• A guided theme preview at /showcase.

• Rate limits and lockouts, 30-minute access tokens with refresh rotation and revocation, a password policy, a login audit.
• Log lines can't be forged: control characters in anything a client sends are escaped.
• gunicorn behind nginx with a strict Content-Security-Policy; only nginx is reachable from the network.
• See SECURITY.md and docs/SECURITY_MODEL.md.

• Invite codes, all chronicles, users (bans, password resets), downtime requests, the moderation log.
• Logins & lockouts: lift a lockout by username or IP, and a paged login audit.
• Laya: label player chat and run an evaluation of the classifier against those labels (docs/laya/).
• AI system: models per role, cloud keys, embeddings and re-embedding.

You need Linux with Docker and the Compose v2 plugin (docker compose), LM Studio with its lms command, and Ollama on the host. An NVIDIA GPU is strongly recommended. The Installation page in the wiki has every step in detail.

1. Clone the repository and create your config:

git clone https://github.com/Somnius/shadowrealms-ai.git
cd shadowrealms-ai
cp env.template .env
cp backend/invites.template.json backend/invites.json
python3 scripts/generate_secret_key.py

2. Edit .env: put your own keys in FLASK_SECRET_KEY and JWT_SECRET_KEY, and generate POSTGRES_USER and POSTGRES_PASSWORD (how). Never keep the template values.
3. Edit backend/invites.json: replace the example codes with your own random ones and keep one admin code for yourself. Registration needs an invite code.
4. Download llama-krikri-8b-instruct and text-embedding-bge-m3 in LM Studio, then load them. gemma-4-e2b is an optional smaller English chat model (lms get gemma-4-e2b --gguf -y).

lms server start
lms load llama-krikri-8b-instruct -y    # Storyteller, English and Greek
lms load text-embedding-bge-m3 -y       # memory and rule-book embeddings
ollama pull llama3.2:3b                 # utility model

5. Start the stack and build the frontend:

./docker-up.sh
./scripts/build-frontend.sh

6. Open http://localhost, register with your admin invite code (passwords need 12+ characters), create a chronicle, and type /ai health in its chat to check LM Studio, Ollama and ChromaDB.

For development, docker compose --profile dev up -d frontend starts the live-reload frontend (point nginx at it, see docs/DOCKER_ENV_SETUP.md), and APP_SERVER=flask with FLASK_ENV=development in .env runs the Flask dev server instead of gunicorn. Don't use the dev server on anything reachable from outside.

• It's developed on Linux with a 16 GB NVIDIA GPU. Krikri needs about 5 GB of VRAM.
• If something else holds the GPU, load only Krikri in LM Studio: the English role follows the loaded model, so Krikri then answers in both languages.
• A Storyteller reply gets 45 seconds per model and 55 seconds in total before it falls back (STORYTELLER_ATTEMPT_TIMEOUT, STORYTELLER_TIME_BUDGET).
• More in the wiki's AI Models page and docs/AI_SYSTEMS.md.

The full list with versions, how Laya was trained, and how each release was built and reviewed: docs/TECH_STACK.md.

• docs/README.md: index of everything in docs/
• docs/TECH_STACK.md: the AI models, technologies and tools used
• Wiki: Installation, Configuration, Rules Editions, AI Models, Architecture, Security, Troubleshooting
• docs/CHANGELOG.md: every release
• docs/ROADMAP_v0.10.md: the plan from v0.9.2 to v0.10
• docs/ROADMAP_v0.9.md: the v0.9 plan

Contributions are welcome. Read docs/CONTRIBUTING.md first, and use GitHub Issues for bugs and feature ideas.

Please don't open a public issue for a vulnerability. Report it privately from the Security tab of this repository; SECURITY.md has the details.

MIT, see LICENSE.

• Made with ❤️ for tabletop RPG games by Lefteris Iliadis (Somnius, @SomniusX).
• Built with the help of AI coding tools: Cursor AI, OpenCode, and Claude Code with Claude Opus 5.5 and Claude Fable 5.1 (see Tech stack).
• Greek Storyteller model: Llama-Krikri by ILSP. Embeddings: bge-m3 by BAAI.

Not affiliated with or endorsed by Paradox Interactive or White Wolf/Renegade; World of Darkness and Vampire: The Masquerade are their trademarks. All glyphs and sigils are original; no rulebook text is included — bring your own books.

▶️ Watch the demo on YouTube

Version 0.7.0 Preview: This demo showcases the frontend interface in its current state. Please note that not all features are fully functional yet—this is a first look at the user interface and design direction of ShadowRealms AI.

The current interface is very different; see the screenshots at the top.