The Lost Realms

Start HereWhat a vault is

The Lost Realms runs perfectly well as a single HTML file opened from your own disk. In that arrangement — Direct mode — the provider keys live in the browser, encrypted at rest, and every call to Anthropic or an image service is made by the page itself. Nothing else is involved, and for one person playing on one machine nothing else is needed.

A vault is what you run when that stops being true. It is a small Node server that hosts the game and proxies its calls, so that the keys sit on the server and never reach a browser at all. The client asks for “a GM turn” or “an image from this provider id”; the vault owns the endpoint, injects the key, and answers. The page never names a URL, which is the whole of the SSRF boundary: a proxy that cannot be told where to go cannot be turned into an open relay.

What it gives you

The vault is optional and detected, never configured. The app probes GET /vault/config on load: served by a vault it switches to Vault mode, opened any other way it stays in Direct mode. There is no setting to get wrong on the client.

Five minutes to a vault

Two variables and you are playing. Everything else in this guide is something you add to that.

cd Server
npm install

VAULT_ACCESS_TOKEN="$(openssl rand -hex 24)" \
VAULT_ANTHROPIC_KEY="sk-ant-..." \
npm start
# → open the printed http://localhost:8787/ and play. The key stays on the server.

On localhost the browser is handed the access token automatically, so there is nothing to paste. From anywhere else the token goes only to a signed-in player — see Who may play.

A .env file instead

Everything here can live in Server/.env rather than on the command line; the vault loads it at boot. VAULT_ENV_FILE points somewhere else if you keep it outside the repo, which is the better habit on a real server.

Where everything lives

One directory holds everything a running vault writes. Knowing which file is which is most of knowing what to back up and what must never be committed.

Each of those paths is an environment variable away from being somewhere else; Appendix A names them all. The one that moves for a real reason rather than tidiness is VAULT_WORLDS_DIR.

Part IThe environment

A vault is configured entirely by environment variables. They are listed in full in Appendix A; this section is the shape of them — which ones you must set, which ones you set once you have decided something, and which ones exist only because you are debugging.

The two that are not optional

Once VAULT_MASTER_KEY is set and you have entered keys on the admin page, the stored key wins and the environment key becomes the bootstrap for a fresh install rather than the live setting.

Deciding where the vault is

Three variables answer three different questions, and conflating them is the most common way a remote vault half-works.

Keys & the encrypted store

A vault can hold a key two ways. From the environment, which needs nothing else and means editing a file and restarting to change one. Or in the store, which is a file of AES-256-GCM ciphertext that the admin page can write to while the server runs.

The store is off until you set VAULT_MASTER_KEY — 32 bytes, as 64 hex characters or base64. It encrypts the store and is never written beside it: a backup of the data directory alone is not a backup of your keys, and that is deliberate.

VAULT_ACCESS_TOKEN=... VAULT_MASTER_KEY="$(openssl rand -hex 32)" npm start
# → http://localhost:8787/admin — add keys there instead of in the environment.

The providers it knows

Each row on the Keys tab is one provider, and its name is a link to the page where that key is created — the one step the admin page cannot take for you. Two are marked required, which is a claim about the game being playable rather than about the server booting: the desktop launcher gates its Play button on exactly those two.

An admin can also author a provider the vault has never heard of, on the Providers tab, as a validated descriptor: an endpoint, an auth style, a request template and a response rule. It is data, not code — the vault runs every descriptor through one trusted executor with the host pinned, so adding a provider can never mean running something new on the server.

HTTPS

The vault speaks HTTPS the moment it has a key and a certificate, and it requires them to bind anything but loopback. For local work, generate a self-signed pair:

./make-cert.sh                 # localhost + 127.0.0.1 + ::1
./make-cert.sh 192.168.1.20    # ...plus another address you reach the vault by

On Windows make-cert.ps1 is the same script, using openssl when it is on PATH and .NET's own APIs when it is not — that fallback needs PowerShell 7, and says so if you are on 5.1.

Both files are written beside server.js, both are gitignored, and the vault picks them up with no configuration. Set one without the other and it is a fatal misconfiguration, not a quiet fall back to http: a server that has been told to be encrypted and silently is not is worse than one that refuses to start.

A certificate must carry a subjectAltName; browsers stopped honouring the Common Name years ago. For anything genuinely public, terminate TLS at a reverse proxy with a real certificate and let the vault stay on loopback behind it.

Sign-in with Auth0

Set four variables together and the whole game requires a sign-in, not just the admin page. An unauthenticated request to any app page is redirected to Auth0's Universal Login; only a successful login gets the game. The same session gates /admin, which additionally requires an email on the admin list.

VAULT_ACCESS_TOKEN=...  VAULT_MASTER_KEY="$(openssl rand -hex 32)" \
AUTH0_ISSUER_BASE_URL=https://auth.example.com \
AUTH0_CLIENT_ID=... \
AUTH0_SESSION_SECRET="$(openssl rand -hex 32)" \
VAULT_PUBLIC_URL=https://vault.example.com \
VAULT_ADMIN_EMAILS=you@example.com \
npm start

A Native application, not a Regular Web Application

The vault is a public client signing in with Authorization Code + PKCE. Create the Auth0 application as Native, with Token Endpoint Authentication Method None. A Regular Web Application is confidential, and Auth0 would issue it a client secret this code has nowhere to put — which is also what lets the vault ship inside the desktop app, where a secret would be sitting in every copy.

The two URLs to register

The custom domain matters

Where the tenant has a custom domain, AUTH0_ISSUER_BASE_URL must be that domain (https://auth.example.com), not the canonical https://TENANT.REGION.auth0.com. Auth0 keeps a separate login session per domain: a vault on one while your website signs people in through the other means two cookie jars, and somebody already signed in to the site gets the full login screen again at the vault. It reads as broken SSO and it is really just two domains. Every surface on the tenant must name the same one.

Part IIThe admin page

/admin is the whole of the running vault's controls, in the game's own palette. With Auth0 configured it is gated by the admin allow-list. With Auth0 not configured it is reachable only from loopback — so a local install needs no identity provider, and a remote one is never accidentally exposed.

The environment report

The fastest way to answer where are my worlds or is TLS on without a shell. Every row is the resolved value the process is using, plus whether it came from the environment or from a default — so a blank means “using the default” rather than “unset and broken”.

Who may play

Three lists and a switch, and the one that surprises people is the second.

A signed-in player is handed the access token by /vault/config exactly as a loopback client is, so the bearer-token proxy is unchanged and stays CSRF-immune. Nothing on the client changes when you turn a login on.

Worlds & the registry

A published world is one pretty-printed world.json in a directory named by its uid, written by rename so a reader always sees a whole file. The vault serves it, the Worlds tab lists it, and the directory — not an index beside it — is the record.

Making one public

Ticking Public offers the world to a central registry, so that players browsing it can find you. It sends the public URL, the name and the description, and nothing else. The box stays disabled, with reasons, until the listing would actually be accepted — which mostly means VAULT_PUBLIC_URL being a real https address.

Taking one back

Unticking Public withdraws the listing — whether the registry had approved it or still had it pending review. It asks first, because a withdrawal destroys the listing and, on a registry that queues arrivals, the place in the queue with it: a realm re-published afterwards arrives pending again, behind everything that was already waiting. When you confirm, the vault records the decision and then calls the registry, and a second dialog says what actually happened — whether the realm is off the registry, or still on it and why.

That second dialog is the point. The vault writes its own flag before it calls the registry, so a call that is refused leaves the box unticked here and the listing standing there — and the box, now unticked, is no longer a control that can ask again. So a refused withdrawal grows a Withdraw & try again button in that cell, the same one a realm the registry has denied gets, and pressing it makes the same request. A world carrying a key is the common case: the registry will not unlist it on this vault's word, because the private half of the key is the author's, so the withdrawal stops at a challenge and the row offers Choose key file… to finish it. Until somebody does, the realm stays listed.

The heartbeat, and the one route nobody gates

For each world marked Public the vault sends a heartbeat — shortly after boot and once a day — so listings do not lapse; a registry drops one a week after anything last confirmed it. The heartbeat carries nothing at all: no descriptor, no key, no signature. It cannot change a listing, only confirm it, which is what lets a keyed world stay listed without its author present to sign.

GET /vault/registry-proof is the single route a registry calls on your vault, and it is deliberately ungated: the asker is a registry you have no account with, arriving from an address nobody can predict, so a login gate here would mean a vault behind Auth0 could never be listed. It answers with the nonce echoed back only for a world hosted here and marked Public. Everything else is a 404 indistinguishable from “no such world”, so it cannot be used to enumerate what you hold privately. That is what stops a registry listing pointing at a server which never agreed to serve the world.

The media store

Generated art used to travel inside the save as a base64 data URI. The vault already holds those bytes — it is the thing that called the provider — so it keeps them on disk and hands back a URL instead. Files are named by the SHA-256 of their content, sharded by the first byte, so the same icon reachable from a catalogue, a pack and a room floor is one file rather than three, and regenerating an identical image is a no-op.

Each stored file also carries a provenance record: the provider, the model and a truncated prompt. That is the one place a prompt is written to disk rather than held in memory; VAULT_MEDIA_PROVENANCE=0 turns the capture off and leaves the store working.

Admin › Media lists what is held, shows what made each file, removes any of them, and can sweep every file no hosted world references. Removal refuses by default when a published world still points at the file, and names the worlds. Note that a vault can only see worlds published to it: art that a player's own browser save refers to counts as unreferenced.

Usage, cost & the call log

Every proxied call is tallied server-side: requests, tokens where the provider reports them, credits where it bills that way, and a cost in dollars. It is aggregate only — no prompts, no per-user rows — and it is the only place the whole bill is visible, since a browser's own ledger sees one browser.

Beside it, the call log holds the last sixty outbound provider calls with the resolved URL and the prompt that was sent, in memory, redacted of keys, and never written to disk. VAULT_CALL_LOG=0 turns it off; VAULT_CALL_LOG_QUIET=1 keeps it but stops it printing to the console.

Part IIIBackups & secrets

Three things are worth backing up, and they want three different treatments.

The claims this guide makes about what is stored, logged and sent are the same ones PRIVACY.md and SECURITY.md make, and those two documents are part of any change that moves data. If you are deciding whether to run a vault for other people, read them; they are short.

Worlds in a git repo

A world is a JSON file in a directory named by its uid — a git-shaped layout already. VAULT_WORLDS_DIR is what lets you put it in an actual repository: version history for your realms, a diff for every publish, and a way to move a world between machines that is not an emailed 400 MB file.

git clone git@example.com:you/realms.git /srv/realms
VAULT_WORLDS_DIR=/srv/realms/worlds  VAULT_ACCESS_TOKEN=... npm start

Leave it unset and nothing changes — the default is exactly where worlds have always lived, so an existing install keeps every one of them with no migration. Setting the variable is the only thing that relocates anything, and moving is then a mv:

mv Server/data/worlds/* /srv/realms/worlds/
cd /srv/realms && git add worlds && git commit -m 'Import the vault worlds'

Because the directory is the record, both things git does to a directory work. A world pulled in is listed without any publish, its record rebuilt from the file — it reports no publisher, because a file cannot say who published it, and shows as adopted. A world edited or reverted on disk is re-read or dropped on the next request. Unchanged worlds cost one stat each.

Upgrading

Pull, npm install if the dependencies moved, restart. Two things make that less alarming than it sounds.

The vault notices when its own source on disk has changed since the process booted and tells every connected client, which shows a “restart needed” banner. So the failure mode where you pull on the server, forget to restart, and spend an afternoon wondering why a fix did nothing is one the app announces rather than one you have to remember.

Nothing in the data directory is version-stamped or migrated on start: the key store, the access lists, the settings and the worlds are read as they are. An older world file is read by a newer vault, and the app's own backfill merges new built-in content into old saves on load rather than refusing them.

When it will not work

The failures a vault actually produces, and what each one means. Nearly all of them are one of three things: a variable naming somewhere you are not, a URL registered somewhere that does not match, or a key that is present in a place nothing reads.

Appendix AEvery variable

Everything the vault reads from its environment, grouped by what it is for. A blank default means unset and unused rather than unset and broken, unless the row says otherwise.

Required, and the keys

Where it listens, and where it is

Sign-in and access

Worlds, the registry and what it stores

Diagnostics

Appendix BRoutes

What a vault answers, and who may ask. You do not call these by hand — the app does — but knowing they exist is how you read a log line or a reverse-proxy rule.

Appendix CAbout this guide

This is the operator's companion to the Dungeon Master's Guide and the in-game Field Guide: same palette, same chrome, a different job. Where they describe authoring and playing a world, this one describes the machine that serves it.

Its source of record is the repository itself — Server/README.md for the configuration, SECURITY.md and PRIVACY.md for the boundaries and what is stored, and Designs/server-vault.html, Designs/vault-media-store.html and Designs/realm-registry.html for why each is shaped the way it is. Where this guide and the server disagree, the server is right, and the disagreement is worth reporting.

The Lost Realms · Vault Administrator's Guide · styled after the Field Guide. Copyright © 2026 Brave You Worlds, LLC. All rights reserved. This guide is Game Content, not software: licensed under LICENSE-CONTENT, with no Change Date — it does not become open source on any future date, the way the engine does. Free to read, print and use in personal or non-commercial play, permanently; commercial use needs a separate licence — licensing@braveyouworlds.com.