⚠️ Serene Pub is in beta! Expect bugs and rapid changes. This project is under heavy development.

🌐 Website • 📚 Documentation • ⬇️ Downloads • 🐛 Issues • 💬 Discord • ☕ Buy Me a Coffee

---

🦊 Serene Pub

Modern, Open Source AI Roleplay Chat

Play more, tweak less.

Serene Pub is an open source chat app for AI roleplay and creative writing, built for stories that hold together over the long run. It remembers what happened, keeps every character honest about what they know, and lets you share the story with friends. Run it on your own hardware or point it at any AI provider.

Never run an LLM before? You don't need to know how. The Setup Wizard downloads, installs and runs a local model for you in a few clicks. No terminal, nothing to configure by hand. Prefer a hosted provider? Plug in an API key.

Long stories drift. Characters forget what happened chapters ago, secrets slip to people who were never in the room, and playing with friends means passing a browser tab around. Serene Pub fixes those three things: structured memory that grows with the story, characters who only act on what they've seen, and a server you can share.

---

Table of Contents

• Multiplayer
• Screenshots
• Features
• Is Serene Pub Right For You?
• Platforms
• Quick Start
• Docker
• Documentation
• Roadmap
• Contributing
• License
• Special Thanks

---

🤝 Multiplayer

Most AI roleplay tools are built for one person in one browser tab. Serene Pub isn't.

Turn on multi-user accounts and one server becomes a shared instance. Invite a friend into a chat as a guest and they arrive as themselves, with their own persona and their own characters pulled from their own library.

• Multi-tenant accounts — each account's characters, personas, chats and lorebooks stay private to it
• Guests bring their own cast — friends join with their own persona and characters
• Live, not turn-passing — every message, edit and generation syncs to everyone over WebSockets

_{One scene, two accounts, live. The owner (left) and an invited guest (right) each bring their own persona; every message syncs to both.}

---

🖼️ Screenshots

_{Click any image for full size. Shots use the community-library cast aboard Seraphis Station, generated locally via the KoboldCPP Manager.}

💬 Chatting

Home Your cast and recent chats, one click from picking up where you left off.	Character Library The characters sidebar in card view — full art, searchable, open alongside whatever you're doing.
Group Chat As many characters as you like, replying in drag-to-reorder turn order.	Participants & Visibility Add cast mid-scene, reorder turns, set Full / Minimal / Hidden per character.
One-on-One Just you and one character, with your chat library alongside.	Message Actions Edit, branch, summarize, hide or delete any message.

🧠 Memory & Worldbuilding — Lorebooks+

World Lore Facts about your setting, retrieved when they matter.	Character Lore Scoped to one character. “Private to Kiran” stays private.	History Timeline Dated in-world events, with a marker for “now”.
Bindings Bind your cast to {{char:N}} tokens, usable in every entry.	Narrative Graph Who knows whom, and how. Replies come from each character’s vantage point.
Graph Traversal Select anyone to isolate the ties they hold.	Relationships Every edge cites its source. Review before anything saves.	Long-Term Memory (RAG) Pick a local embedding model, or any OpenAI-compatible endpoint.

🖥️ Local Models, No Terminal

KoboldCPP — Get the Binary Pick a build; Serene Pub downloads and runs it.

KoboldCPP — Models Browse, download and switch GGUF models.

KoboldCPP — Managed Mode Version, port, unload timers and capabilities at a glance.

Ollama Manager Search, download and activate Ollama models in-app.

📚 Community Libraries

Character Library Browse and import community cards, including CharaVault.

Persona Library Ready-made personas for however you want to show up.

Connections Any provider, per-task overrides, sampling and context configs.

⚙️ Prompts & Context Control

Context Config Builder Build the prompt from reorderable cards, or edit the raw template.

Per-Task Prompt Configs Chat, narrator, summarizers and graph builder each get their own model.

🚀 First Run

Setup Wizard Seven guided steps from empty install to first chat.

Connect an AI Never run a model before? Pick “Easy” and it’s handled.

Document View High-contrast, keyboard/screen-reader-first UI. Ctrl+Shift+Y.

🎨 Themes, Backgrounds & Mobile

Catppuccin	Vintage	Wintry (Light)	Mobile Same app, fully responsive.
Custom Backgrounds Pick a built-in image or upload your own, then set the opacity.		Gradients If a photo is more than you want behind the text.

_{Three of the 20+ built-in themes. A custom theme editor ships too.}

---

🚀 Features

Memory & Worldbuilding

A story that remembers itself, so you don't have to keep notes.

• Lorebooks+: World lore, character lore and a dated history timeline, all bindable to your cast via {{char:N}} tokens
• Scenes: Capture a run of chat messages as a standalone summary, pinned to a point in your story's history
• Summarization: Compress chat messages, scenes and history entries into permanent, editable lorebook content on demand
• Narrative Graph: Tracks who is connected to whom, and how. Build it from your scenes and history, then extend it as the story grows
• Relationship Visibility: Every relationship is secret, acknowledged or public, and replies come from each character's own vantage point. A one-sided crush stays one-sided
• Long-Term Memory (RAG): Finds lore, history and past messages by meaning rather than keywords, scoped to what each character knows. Runs on-device or against any OpenAI-compatible embeddings API

Characters & Perspective

• Character & Persona Management: Import, create and edit with rich metadata, avatars and image galleries
• Library Browsers: Search and import thousands of community-made cards without leaving the app, including direct CharaVault integration
• Per-Character Visibility: Full / Minimal / Hidden per character, per chat. A context-budget control, separate from relationship secrecy
• On-Demand Narrator: Trigger a response from the environment (weather, scenery, an NPC shopkeeper) with no permanent "Narrator" in your cast
• Group Chats: As many characters at once as you like, with drag-to-reorder round-robin turn order
• Branch Chat: Fork the story at any message into a full copy, carrying the cast, lorebook, settings and history up to that point. Any participant can branch
• Built for Coherence: Character and lore data reaches the model structured, not as freeform prose. A deliberate choice after side-by-side testing

AI Connections & Local Models

Bring your own model, or download and run one from inside the app.

• AI Model Agnostic: OpenAI, Anthropic, Ollama, KoboldCPP, LM Studio, Llama.cpp and more
• KoboldCPP Manager: Download the binary, browse and download GGUF models, load or switch between them, all in-app
• Ollama Manager: Search, download and activate Ollama models from a built-in UI. No command line
• Per-Task AI Override: Point chat, narrator and summarizer at different connections. Run dialogue on a fast local model, summarization on a heavyweight cloud one
• Context Config Builder: Decide what the model sees and in what order, with drag-and-drop cards and a live preview. The raw Handlebars template is still there
• Prompt Statistics & Context Debugging: Inspect the compiled prompt and retrieval diagnostics behind any reply, so "why did it forget that" has an answer

Getting Started & Polish

• Mobile-First Design: Fully responsive on phones and tablets. See Platforms for desktop, Docker and Android builds
• Setup Wizard: A guided first run that can install and start a model for you, then walks you through your first character, persona and chat
• Built-In Docs Browser: The full documentation, searchable, inside the app
• Document View: A high-contrast, keyboard- and screen-reader-friendly interface with one plain page per feature. Ctrl+Shift+Y
• Themes & Dark Mode: 20+ built-in themes, instant switching, accessibility options, and an editor for building and sharing your own
• Custom Backgrounds: Put an image behind the interface, built-in or your own, with an opacity slider. Per-account, so everyone on a server gets their own
• Tags: Organize and filter chats, characters, personas and lorebooks
• Chat & Context Tools: Auto response, message editing, streaming and regenerate, hidden responses, swipe between alternatives, live token stats
• Portable & Secure: Embedded database, no cloud required, runs anywhere
• SillyTavern Import/Export: Import cards and avatars, or a whole SillyTavern data directory with chat history. Exports in the same format

---

🤔 Is Serene Pub Right For You?

• Already have a character library? SillyTavern cards import directly, or point Serene Pub at a whole data directory for characters and chat history at once.
• Want to play with friends? Multi-user accounts and guest-invited chats, self-hosted end to end. Everyone plays their own persona and brings their own characters onto a server you control.
• Writing long-form solo? Lorebooks+, Summarization and the Narrative Graph keep characters and world facts straight well past where flat lorebooks break down.

---

🧩 Platforms

The core app is the same everywhere. Two features depend on native binaries that don't exist for every platform, and the app says so up front rather than failing at runtime.

Platform	Distribution	Local embedding models	KoboldCPP / Ollama Manager
🪟 Windows (x64)	GitHub Release .zip	✅	✅
🍎 macOS — Apple Silicon (arm64)	GitHub Release .zip	✅	✅
🍎 macOS — Intel (x64)	GitHub Release .zip	⚠️ Unavailable¹	✅
🐧 Linux (x64)	GitHub Release .zip	✅	✅
🐧 Linux (arm64)	Docker only²	✅	✅
🐳 Docker (linux/amd64, linux/arm64)	ghcr.io/doolijb/serene-pub	✅	✅
📱 Android (arm64, API 26+)	GitHub Release .apk	⚠️ Unavailable³	⚠️ Unavailable⁴

Annotations:

1. macOS Intel — no local embedding models: onnxruntime-node, which powers in-app embeddings, stopped shipping Intel Mac binaries at v1.24.3. Use any OpenAI-compatible /embeddings endpoint instead, which behaves identically. The Docker image keeps full local support, since the container runs Linux binaries.
2. Linux arm64 — Docker only: GitHub-hosted CI runners can't cross-compile the native dependencies, so there's no standalone desktop build. The multi-arch Docker image covers this architecture with the full feature set.
3. Android — no local embedding models: Android's Bionic userspace isn't glibc-compatible and onnxruntime-node requires glibc. Not fixable by packaging. Use an external embeddings API, as on Intel Mac.
4. Android — no KoboldCPP/Ollama Manager: the managed auto-download-and-run modes are hidden, since KoboldCPP publishes no Linux arm64 binary. Connecting to a remote KoboldCPP or Ollama server still works, via the Connections panel.

See android/README.md for all Android-specific constraints.

---

🛠️ Quick Start

No config files, no build step, no separate services to wire up.

Platform	Get Serene Pub
🪟 Windows	Download → extract → run run.cmd
🍎 macOS	Download → extract → run run.sh (first launch may need right-click → Open; see Troubleshooting)
🐧 Linux	Download → extract → run run.sh (install-desktop-shortcut.sh adds a desktop icon)
📱 Android	Download the APK → install → open
🐳 Docker	docker compose -f docker-compose.dist.yml up -d — see Docker below

Desktop opens at http://localhost:3000; Android opens straight into the app. The Setup Wizard connects an AI provider (or installs KoboldCPP/Ollama for you), then walks you through your first character, persona and chat.

From Source

Requirements

• Node.js 24 or later
• (Optional) Ollama for local models

Steps

1. Clone this repo
2. npm i to install dependencies
3. npm run dev to start the dev server, or npm run dev:host
4. Visit http://localhost:5173

Prefer Docker? docker compose -f docker-compose.dev.yml up -d --build builds from local source into its own data volume, for testing changes without touching the release image.

🐳 Docker

Pre-built images are published to the GitHub Container Registry on every release:

ghcr.io/doolijb/serene-pub:latest   ← always the latest stable release
ghcr.io/doolijb/serene-pub:0.5.0    ← exact version pin

Quickstart — download docker-compose.dist.yml from the release assets, then:

docker compose -f docker-compose.dist.yml up -d

The web UI will be at http://localhost:3000.

Data directory — database, model cache and uploads live under SERENE_PUB_DATA_DIR, defaulting to /data and mounted as a named volume. For a host path instead:

docker run -p 3000:3000 -p 3001:3001 \
  -e SERENE_PUB_DATA_DIR=/data \
  -v "$(pwd)/serene-pub-data":/data \
  ghcr.io/doolijb/serene-pub:latest

See DOCKER.md for ports, volumes and reverse proxies, and Hosting Serene Pub or Environment Variables for env vars and tunnels.

Need help? Start with the Getting Started guide.

---

📚 Documentation

Complete Documentation Available in docs/

The same documentation ships inside the app on a built-in Docs page.

Popular pages:

• Getting Started - The setup wizard, step by step
• Connections - Connecting to AI models and managing local ones
• Characters and Personas - Your cast, and your own identity in a chat
• Lorebooks - World-building, history, scenes and the narrative graph
• Embeddings & RAG - How semantic retrieval keeps long stories coherent
• Prompt Configs and Context Configs - Customizing prompts and the context builder
• Document View - The accessible alternative interface
• Troubleshooting - Common issues and solutions

---

🗺️ Roadmap

Upcoming releases are tracked as GitHub Milestones, each holding the issues that make it up. Nothing is promised on a timeline.

• 0.6.0 — a modular node pipeline, with core logic and AI workflows converted onto it, plus further RAG and Lorebooks+ improvements
• 0.7.0 — maturing those pipelines into an SDK for modders: custom pipelines, server-side logic, free-form data storage and limited-scope UI components

Text-to-Speech was targeted for 0.5.0 and held back. No integration found yet that's small, fast, expressive and tunable without voice cloning or a large sample library.

---

❤️ Contributing

Bug fixes, features and feedback are all welcome. Please open an issue or start a discussion before submitting large changes.

For development setup and contribution guidelines, see CONTRIBUTING.md.

---

🛡️ License

AGPL-3.0. See LICENSE and NOTICE.md for details.

---

🙏 Special Thanks

Special thanks to Nivelle for creating Serene Pub community library characters, and subpanopticon for feedback and testing.

---

Serene Pub — Play more, tweak less. 100% open source.
🌐 serenepub.com • 📚 Read the full documentation