Where a key lives
An AI backend is a base URL, a model name and usually an API key. The app can hold that trio in three places. Which place you use depends on where the world lives.
The three places
| Place | Where you set it | Covers | Who sees the key |
|---|---|---|---|
| The device | The app's Story AI screen (home screen, Story AI button) | Every campaign on that device's world, new or old | Only the server inside the app. Never players, never the campaign's settings. |
| The campaign | The Settings tab's story fields, on a self-hosted server | That campaign only | Only an administrator can set a campaign's own backend address or key; a campaign anyone else owns uses the server's. It is scrubbed from every snapshot other members receive. |
| The server | Admin, Server settings, Text model and Images; or environment variables | Every campaign that has no setting of its own | Administrators only. |
Resolution is campaign, then admin panel, then environment, then built-in default. On an app-hosted world the Story AI choice is written to the world's admin settings, which is why every campaign follows it and why the Settings tab shows the device's choice rather than asking again.
What each door needs
| Door | Needs | Where |
|---|---|---|
| OpenAI | A key and a story model from its list; optional utility, image and speech models | OpenAI and compatible keys |
| OpenRouter or another OpenAI-compatible router | Base URL, model id, key | OpenRouter |
| Local model (llama.cpp, Ollama, LM Studio, vLLM) | A base URL on your network; usually no key | Local models |
| An agent program | Claude Code, Codex, opencode or Grok Build signed in on the computer; no key | Bring your own agent |
| Pictures | An OpenAI key, ComfyUI, or the FLUX worker | Image providers |
Tool calling is not optional
The Dungeon Master asks the model to call tools for every roll, every hit point and every encounter. A model or endpoint without function calling narrates a fight it never actually starts. Pick a model whose card advertises tool or function calling, and on a self-hosted server run Test backend in the admin panel, which checks a real tool call.
Two models, not one
Every backend can name a second, cheaper utility model for chapter summaries, compaction, lore checks and Ask the DM. Leaving it blank sends everything to the story model, which works and costs more. Pick both from the models the backend lists. On a local server a small tool-capable model can handle the utility work; it does not have to be the same model that tells the story.
Keys are secrets
- A key is stored on the server that uses it and sent to the provider over HTTPS. It is never sent to a browser or another player, and a saved key only goes to the host it was saved for.
- On a shared server, the administrator decides whose tables may spend a paid AI backend, and Admin, Usage shows the tokens each account and campaign used.
- On a self-hosted server, keys belong in the admin panel or
.env.server, never in code or a shared file. - If you ever set a per-campaign key on server 0.12.0, rotate it: that release leaked campaign keys into member snapshots and 0.12.1 fixed it.
- A backup includes database settings and any archived environment file, so it can contain provider keys. Keep it private and retain the matching database key separately if that key exists only in the process environment.
Privacy
With a remote key, each turn's prompt (the story so far, the sheets, the scene, the secret arc) goes to the provider. With a local model or a human Dungeon Master, nothing leaves your machine. See What leaves your machine.