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.

Two clients speak the same protocol, and everyone connects to the same server, the same table. The desktop app (recommended): Loreweaver Studio ↗ — live panels, a module's own panels, the keeper screens and the card studio; installers for all three platforms are on the latest release ↗ (unsigned for now: macOS wants one right-click → Open, Windows a "More info → Run anyway"). The terminal client — cross-platform (macOS / Linux / Windows), installed in one line below.

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://github.com/1A7432/loreweaver/releases/latest/download/install.ps1 | iex. Upgrading later: loreweaver update. Behind the Great Firewall, the mirror serves the same files: https://1a7432.site/trpg/install.sh.

Development builds ship as ordinary releases, so latest means the newest build, not the newest stable one. To hold a table on a known version, set TRPG_RELEASE_TAG=<tag> before running the installer, or fetch that release's own installer — it pins itself. TRPG_SERVER_RELEASE_TAG pins only the one-click server.

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: .rule shows the ladders this room can use and switches between them (.rule 0 returns to the default). The options are declared by the rulepack, so a different system offers different ladders. 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.

5Modules & content packsKEEPER

Once the table is up, content arrives through three doors: SillyTavern cards, content packs, and presets. All of it is Keeper work — players just sit down and wait for the opening scene.

Run a SillyTavern card as a module

The trailing world is the point — this is the Keeper-only world import: the whole worldbook lands (secret entries stay Keeper-eyes-only), the [InitVar] variable tree seeds, and the card's character joins a claimable roster (players take it with .pc claim <name>). When a player imports a card they get the character half only — hooks, variable declarations and secret lore are stripped structurally, so no card can smuggle machinery into your room.

After importing, inspect the tree with .var list (the Keeper sees everything), then expose the subtrees players should see:

Exposed values show up live in every player's sidebar tracker panel; everything else is filtered inside the engine and never leaves the server.

Install a content pack (.lwpack)

A whole work — cards, worldbooks, rulepacks, skills, UI panels, media — travels as one .lwpack file, from a local path, a direct link, or an author's own GitHub release:

Before anything lands you see a trust card — how many cards and skills, whether sandboxed scripts ride along, how heavy the media is — and every file is integrity-checked. Installed ≠ enabled: in the room the Keeper opts in per item — .skill enable for skills, .panels enable <packId> for UI panels — and pack cards import by relative path:

Presets, and making your own cards

A SillyTavern completion preset imports whole as a room "style layer": .preset import /path/preset.json, then .preset enable <id> — it shapes tone and framing, and never outranks dice or secrecy discipline. To author cards, grab the desktop Loreweaver Studio (card-split bench + staged forge): one authoring pass exports both a standard SillyTavern card and the native format; a native .lorecard.json world-imports the same way and packs into an .lwpack for distribution.

6Tips

• 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.

Where to go next

This page covers deploying and getting a table started. These are written per role, and each has a Chinese version: