If you like the project and want to support it: https://ko-fi.com/latenightai
A local-first, LLM-powered interactive-fiction engine. Corvus runs the game master for persistent open-world text RPGs — narrating scenes, playing NPCs in distinct voices, tracking stats / inventory / money / relationships, generating portraits and scene art, and (optionally) speaking the whole thing out loud. Everything lives on your machine.
The model is yours. The data is yours. The story is yours.
- Bring your own model. Works with any OpenAI-compatible
/v1/chat/completionsendpoint — LM Studio, vLLM, llama.cpp's HTTP server, LocalAI, OpenRouter, OpenAI. Point the URL where you want. - Multi-game library. Each game is fully isolated: its own world info, NPCs, history, summaries, images, and state.
- Real game-master loop. Every player turn runs a narrator/character pass, a hidden GM pass that extracts structured deltas (stats, money, items, NPC dispositions, world events), and a state manager that applies them to disk.
- NPCs that remember. Auto-generated character cards with personality, voice, disposition, and a running memory of past interactions. Per-NPC chat colors so dialogue is easy to read.
- Create-with-AI. Spawn a new world or a new character chat from a one-line prompt; the model fills in setting, tone, rules, starter NPCs, and openers.
- Story-aware image generation. Optional ComfyUI integration. Tell it "draw the woman at the bar" and it pulls her appearance from the NPC card and the recent scene.
- Text-to-speech. Optional Chatterbox integration via
the OpenAI-compatible
/v1/audio/speechendpoint. Supports both the devnen and travisvn forks. Per-NPC voices, narrator voice, queued playback, pause / resume, volume. - Rolling memory. Old chat gets summarized into chapter notes automatically so context stays clean over long sessions.
- No database, no cloud, no telemetry. All game data is JSON files
under
~/corvus-data/. Move them, version them, back them up, hack on them. - One-click install.
./install.sh+./start.shon Linux/macOS,setup.bat+run.baton Windows.
Color-coded speakers, per-character voices, group / individual targeting.
Personality, appearance, background, disposition, voice/style, memory, identity seed, and portrait prompt — all editable, all persisted.
Any OpenAI-compatible server works. Optional global "jailbreak" system prompt prepended to every request.
Chatterbox auto-detection — works with both devnen and travisvn forks.
Tune the summarizer threshold, context window budget, and auto-NPC creation.
| Node.js | 18+ (recommended: 20+) |
| OS | Linux, macOS, or Windows |
| LLM | Any OpenAI-compatible chat endpoint — LM Studio, vLLM, llama.cpp, etc. |
| ComfyUI | Optional. Only needed if you want image generation. |
| Chatterbox | Optional. Only needed if you want voiced characters. |
Corvus does not ship a model. You point it at one you already run.
Clone or extract the project, then from inside the project folder:
Linux / macOS
./install.sh # one-time setup (checks Node, installs deps, builds client)
./start.sh # launchWindows — double-click setup.bat, then double-click run.bat.
Open http://localhost:5173 (dev mode) or http://localhost:3000 (production mode) in your browser.
Environment overrides for start.sh / run.bat:
| Variable | Default | Effect |
|---|---|---|
PORT |
3000 |
Server port |
HOST |
127.0.0.1 |
Bind host |
CORVUS_PROD |
0 |
=1 skips Vite HMR and serves only the built bundle |
If you'd rather drive npm yourself:
npm install
(cd client && npm install)
npm run build # optional, only for production mode
npm run dev # dev mode (server + Vite HMR)
# or
npm start # production mode (server serves built client)- Launch Corvus and open it in your browser.
- Click the Settings gear icon (top right).
- LLM Endpoint tab — point the API URL at your model server.
Hit Test connection.
- LM Studio default:
http://localhost:1234/v1 - vLLM default:
http://localhost:8000/v1 - OpenAI:
https://api.openai.com/v1+ API key + model name
- LM Studio default:
- ComfyUI tab (optional) — enable it and point the URL at your ComfyUI install.
- TTS tab (optional) — enable it and point the URL at your Chatterbox server. Hit Test connection to populate the voice list.
- Engine tab — tune the context window budget to match your model's actual context length.
You have two paths:
A. Quickstart with AI. Click + New Game → toggle "Create with AI" → describe what you want in one sentence ("a haunted lighthouse on the Maine coast, 1920s, melancholic and slow") → the model fills in setting, tone, rules, currency, and starting NPCs.
B. Manual. Click + New Game and fill in the fields yourself: name, genre, world description, tone, rules, currency name, player character (name, backstory, appearance, stats, money, abilities, inventory).
Either way, hit Create and you're playing.
When you send a message, three passes run in sequence:
- Narrator / Character agent. Reads your input, the world state, the relevant NPC cards, and the recent history; generates the in-fiction response (narration + dialogue, color-coded by speaker).
- Game Master agent (hidden). Reads the same exchange and extracts structured changes — stat deltas, money changes, new items, NPC relationship shifts, world events.
- State manager. Applies the GM's deltas to your game files. The right-side info panel updates in real time.
The prompt assembler keeps things coherent over long sessions:
- Recent chat messages go in verbatim.
- Older messages get summarized into chapter notes once they cross the summarizer threshold.
- Relevant NPC cards (whoever's in the current scene) are pulled in.
- World state, world rules, and player stats are always included.
- Total token budget is configurable in Settings → Engine.
- Click Studio in the header to open the image studio.
- The Quick chat input takes natural-language instructions ("draw Mira at the rooftop bar, rain"). The image agent reads the story to resolve references.
- Three modes: text-to-image, image-to-image, inpainting. Send images between modes with one click.
- Every generated image is stored in the per-game gallery with its full prompt + settings.
- Identity seed support — lock a seed per NPC for consistent faces across generations.
- Enable in Settings → TTS and point at your Chatterbox server.
- Pick a narrator voice for narration / unknown speakers.
- Per-NPC voice + enable toggle on each NPC card.
- A floating dock (bottom right) shows the now-speaking line with pause / resume + volume.
- Messages stream into a queue and play in chat order — multiple speakers never overlap.
All game data lives at ~/corvus-data/ (configurable) as plain JSON.
No database. No migrations. cp -r is your backup tool.
~/corvus-data/
config.json ← Global settings
games/
your-game-name/
game.json ← Game metadata
world.json ← Setting, tone, rules, currency, era
player.json ← Player character sheet
characters/ ← NPC cards (one JSON per NPC)
history/ ← Chat messages (JSONL per chapter)
summaries/ ← Auto-generated chapter summaries
images/ ← Generated images + sidecar metadata
state/
world-state.json ← Persistent world events / location flags
| Key | Action |
|---|---|
| Enter | Send message |
| Shift+Enter | New line in message |
| Escape | Close any open modal |
- Your model server isn't running, or the URL is wrong.
- LM Studio: make sure the local server is enabled in its Server tab and a model is loaded.
- vLLM / OpenAI / OpenRouter: the Model field is required. LM Studio ignores it.
Connection refused— Chatterbox isn't listening on that port. Start it, or fix the URL.Host unreachable— different machine on your LAN? Make sure Chatterbox is bound to0.0.0.0(not127.0.0.1) and any firewall allows the port.Timed out— the server is reachable but slow to respond. Often a cold start; try again.- No voices in the dropdown — older Chatterbox builds don't expose a
catalog. Type the voice filename (e.g.
female_01.wav) directly.
- Bump Context window budget in Engine settings.
- Your model's actual context length matters — 8K is the practical minimum.
- Check that summaries are being created (look in
~/corvus-data/games/<game>/summaries/).
- ComfyUI not running, or the configured model name isn't installed.
- Check the ComfyUI console for the real error — Corvus surfaces a short summary but ComfyUI's log is the source of truth.
- Backend — Node.js, Express, TypeScript (
tsxwatch in dev) - Frontend — React, TypeScript, Tailwind CSS, Vite
- LLM transport — OpenAI-compatible
/v1/chat/completions - Image gen — ComfyUI HTTP API
- TTS — Chatterbox
/v1/audio/speech(OpenAI-compatible) - Storage — File-based JSON / JSONL
- No database. No cloud. No telemetry.
PRs welcome. See CONTRIBUTING.md. The codebase is
small and deliberately readable; server/services/orchestrator.ts and
server/services/gameMaster.ts are good places to start reading.
See CHANGELOG.md for the full history. Recent highlights:
- 1.1.45 — one-click installers (
install.sh,start.sh,setup.bat,run.bat) - 1.1.44 — proper devnen/Chatterbox-TTS-Server support with grouped voice catalog
- 1.1.42 — Chatterbox text-to-speech with per-NPC voices, queue, pause / resume
- 1.1.41 — global jailbreak system prompt
- 1.1.40 — generalized LLM endpoint (vLLM, OpenAI, OpenRouter, etc.)
- 1.1.39 — create-with-AI for both worlds and character chats
MIT — see LICENSE.