Read a novel. Meet its characters. Shape a new path through the story.
📚 Features · 🚀 Quick start · 🛡️ Limits · 🧰 Development · 📖 Docs
NovelWorld is an open-source, self-hosted platform for interactive reading. Import a novel, read by chapter, talk with its characters, and explore story branches as an original player.
Note
NovelWorld is a private, single-node preview. It does not support public Internet exposure. Keep it on localhost. Use an encrypted private-network or TLS boundary before remote access. Model quality, recovery, and accessibility are not qualified. Read the product contract and roadmap.
- 📚 Bring your own books. Paste text or import TXT, EPUB, and text-based PDF files.
- 📖 Read and track progress. Follow chapters and request a Simplified Chinese rendering of the current chapter.
- 💬 Talk with characters. Continue saved conversations within server-owned reading boundaries.
- 🧭 Choose what happens next. Follow branches or enter an open world as an original player at an unlocked chapter.
- 🌐 Use your language. The interface defaults to English and also supports Simplified Chinese. UI language does not change novel text or generation language.
- ⚙️ Choose your model setup. Configure DeepSeek for story generation. Embeddings can use a local model or an external OpenAI-compatible endpoint.
Interface presentation only. The story text is a static sample. This image does not show an authenticated journey or model quality.
Install Git and Docker with Compose v2. On Windows, install Docker Desktop. Before you start the server on Windows, start Docker Desktop.
git clone https://github.com/Wisdoverse/novelworld.git
cd novelworldRun the server launcher:
# Linux
./start.sh# Windows PowerShell
.\start.cmdWhen setup completes, open http://localhost. Create the first administrator account. This step needs no model API key. Open Settings. Configure the provider, model, and key for AI features. See the provider guide.
The default setup uses PostgreSQL. Redis is optional. Story generation needs an Internet connection and a configured key. Source excerpts and conversations are sent to the configured provider. Review that provider's data and billing policies. Upload only works that you have the right or permission to process.
The default configuration disables embeddings. Set EMBEDDING_PROVIDER,
EMBEDDING_API_URL, and EMBEDDING_MODEL in .env for an external endpoint.
Local embeddings also require the explicit local-embedding Compose profile.
See .env.example for both configurations.
| Area | Current boundary |
|---|---|
| Inputs | Pasted text: 5 MiB. TXT: 10 MiB (UTF-8, BOM-marked UTF-16, or GBK). EPUB or text-based PDF: 20 MiB per file. Extracted text: 20 MiB. |
| Batch upload | Select up to 50 files. The client sends at most 5 files and 40 MiB per request. Per-file limits still apply. |
| Language | English and Simplified Chinese have deterministic chapter-splitting and lore-retrieval fixtures. Generated narrative transitions require Chinese text. No language or model combination is release-qualified. |
| Unsupported files | NovelWorld does not support scanned or image-only PDFs or DRM-protected files. Accepted files do not guarantee extraction or translation quality. |
| Server platforms | Docker launchers target Linux and Windows 10/11. macOS server deployment is not qualified. |
| Desktop | Check GitHub Releases for available experimental, unsigned builds. Migrations are forward-only. Keep application data paired with a compatible version. |
| Optional previews | D20 rules and series worlds are structural previews. Full D&D gameplay and matching or adjudication quality are not claimed. |
The server uses five Rust/Axum services and a shared PostgreSQL database. PostgreSQL owns authoritative state. Redis is an optional projection. Settings may show token-cost estimates. They are not account bills. Database isolation, horizontal scaling, and public-cloud readiness are outside the current claim. See architecture, provider pricing, and the data lifecycle.
Read CONTRIBUTING.md for setup and validation guidance. Common checks include:
cargo test -p novel-service
cargo run --locked -p architecture-check -- checkcd frontend
pnpm install --frozen-lockfile
pnpm devThe Vite frontend runs at http://localhost:5173 and needs a configured backend
gateway. CI is the authoritative merge gate. Coding agents should read
AGENTS.md before changing the repository.
- 🚀 Setup, upgrades, and recovery
- 📋 Product contract and limits
- 🗺️ Roadmap and active work
- 🏗️ Architecture and data ownership
- 📑 Specification and conformance · ledger
- 🔐 Data lifecycle · account export
- 🤝 Contributing · all documentation
Read CONTRIBUTING.md before preparing a change. Report bugs through GitHub Issues. Report vulnerabilities through the private process in SECURITY.md.
NovelWorld is available under the MIT License.