Deploy & play

1Overview

Loreweaver is a game, not a chat. An AI Keeper (KP) runs the table; one or more players play investigators. The Keeper narrates, adjudicates, and plays every NPC — but the dice are rolled by the engine, never made up. Roles at the table:

• Keeper: connects with a Keeper key; can import modules, switch models, issue invites, and manage rooms. Usually one at a time.
• Player: connects with a player key; plays one investigator — builds the sheet, rolls, acts.
• AI companions: empty seats can be filled by AI party members — each with its own sheet, its own rolls, acting only on what it actually knows.

There is one client: the terminal client — cross-platform (macOS / Linux / Windows), installed in one line, and everyone connects to the same server, the same table.

2Getting to the table

Hosting: one button is enough

Install the client, click the green button on the connect screen — "Host locally & play" — and that's it. There is no step two.

It downloads the server build for your OS (self-contained — no Python, no environment setup), starts it, issues your Keeper key, and drops you into the main menu as the Keeper. We've verified the whole path from clean installs of Windows 10/11, macOS (Apple silicon), and Linux.

Installing the client

One line (macOS / Linux):

Windows (PowerShell): irm https://raw.githubusercontent.com/1A7432/loreweaver/main/clients/install.ps1 | iex. Upgrading later: loreweaver update.

Joining a friend's game (ticket + invite key)

Once installed, run loreweaver and fill in the connect screen:

Long-term self-hosting (optional)

The server builds are also yours to take and run long-term on a machine of your own: GitHub Releases has loreweaver-server-* for all four platforms — unzip and run, with a --doctor self-check built in.

3Characters

Once connected, open the main menu and pick "My character → Create". Or build one with commands. Four ways in — and every one of them passes through the rules at the end: out-of-range stats and blown budgets get blocked, no matter what the AI says.

House rules: .setcoc 2 picks the CoC crit/fumble convention. Renaming: .nn NewName (or .rename).

4The core loop: say what you do

Playing is simple — say what your investigator does, in plain language. No commands required:

One rule never breaks: roll first, narrate after. The moment you attempt something uncertain, the engine rolls real dice, and the Keeper tells the outcome by its success level — never a pre-written ending, never "you succeed" without a roll. You can also roll yourself with the commands in the command manual.

5Tips

• The model matters — a lot. The Keeper lives and dies by tool calling and instruction following. Capable models (deepseek-v4-pro with thinking, GPT-4-class, Claude) roll honestly and stay on module; bargain models narrate without rolling and wander off script.
• Module import takes minutes — that's normal. A real model analyzing a big module takes a while; watch the progress bar walk through its stages. It isn't stuck.
• Call on an AI companion by name. When the Keeper wants an AI party member to act, it summons them through a tool, and they show up playing their own sheet.
• The terminal experience is the full experience. Dice cursors, animations, shortcuts, the top-bar HUD (scene / clock / context usage / connection light) — one-line install, every platform.
• Updating the client: loreweaver update.