Skip to content

How to host for browsers and SSH

Everyone's at home on the same network, or on Tailscale, and nobody wants to install the app. The players open the saga in a web browser while it stays on your computer.

The app and the saga file never leave your computer. Each player who opens the page gets their own copy of the app, running on your machine.

You need a private network that you and the players share. The app doesn't come with one, so use your home network, Tailscale or ZeroTier (recipes below). Never host on an address the whole internet can reach. Anyone who reaches it gets a copy of the app and its sign-in, and the page isn't encrypted beyond what the network adds. The app refuses such an address, and "every address" (0.0.0.0), unless you tick I know this is reachable from the internet. What can go wrong, and what the app does about it, is in the app's threat model (docs/threat-model-browser-and-ssh-hosting.md beside its source).

What the players get in their browser, or over SSH, is the terminal version of the app, so their screens look like it rather than like this window. You keep using the desktop window while you host. It and the players' copies all save into the same saga file, each change merged with the others.

Before the first session

  1. Add the players. Open the saga page's Saga Management chapter, where the Players sit beside Host for Players. Add each with Add: a name, the Role Player, and a passcode you give them yourself. Add a Storyguide too if another storyguide will sign in from a browser.
  2. Say who plays whom. For each player's characters, open the character, click Edit on Biographical Detail in its Description chapter, and tick who it's Played by. Tick several players, or everyone in the troupe, for a shared character.
  3. Let them keep the books. Tick May change covenants on a player who should keep the covenant's books.
  4. Join the network. Set up the private network (Tailscale or ZeroTier below) and note your computer's address on it.

Keeping secrets from the players

Write what the players mustn't learn on each record's Secrets chapter (Add there), one secret at a time, not in its summary or notes. A player who signs in sees only the secrets you reveal, in the record's Known section, and a record they export carries only those. Everything else on the sheet they can read.

A record they mustn't know of at all yet, such as a hidden grove or a rival covenant, you hide with Hide from the Players. Reveal it when they learn of it (see Player view and How to reveal a record).

The Roll Tables of places, threats, factions and lords are yours alone too. A player doesn't see them and can't roll. A row's "(SG: ...)" note shows on your roll but never in the Diary line it writes.

Tailscale

Everyone, you and each player, installs Tailscale and signs in with an existing Google, Microsoft, GitHub or Apple account.

  1. Find your address. On your computer, Tailscale shows its address, starting with 100.. That's the ADDRESS to host on.
  2. Share your computer. In Tailscale's admin page, share your computer with each player by their email. They accept the invite, and can then reach only your computer.
  3. Open the saga. Players open http://ADDRESS:8000.

ZeroTier

Only you need a ZeroTier account. Players just install the ZeroTier app.

  1. Make a network. On ZeroTier's website, create a network and copy its 16-character Network ID. Keep it Private.
  2. Join it yourself. On your computer, join that network from the ZeroTier icon. On the website, tick Auth for your computer and note its Managed IP. That's the ADDRESS to host on.
  3. Make it Private in Windows. Windows often marks the ZeroTier connection as a Public network. Set it to Private in Windows' network settings, or the firewall keeps players out.
  4. Let the players in. Each player installs ZeroTier and joins with the Network ID, and you tick Auth for their device.
  5. Fence it. On a ZeroTier network every device can reach every other one. To let players reach only the app on your computer, set the network's Flow Rules along these lines, with your address, then check a player can still connect.
accept ethertype arp;
accept ipdest ADDRESS/32 and ipprotocol tcp and dport 8000;
accept ipsrc ADDRESS/32 and ipprotocol tcp and sport 8000;
drop;

Starting and stopping

  1. Open Host for Players. Open the saga and, in its Saga Management chapter, click Host for Players. In the Host for Players window, choose Browser or terminal (On your private network), then click Host.
  2. Choose where. Choose your Address on the private network. The Tailscale one is marked, and Another address... lets you type one. Leave the Browser port at 8000 unless another program has it. Tick Also over SSH to take SSH clients too (see below).
  3. Host. The line under the fields says what players will open. Click or press Host. The form remembers what you chose for next time.
  4. Let it through the firewall. The first time, Windows asks whether to let Python (armarius-terminal, in a downloaded copy) through the firewall. Allow it on private networks.
  5. Send the players in. Players open http://ADDRESS:8000 in their browser, choose the saga and sign in. Saga Management (and, on the desktop, the Host for Players window) shows the address for as long as you host.
  6. Keep your computer awake while people play. Nobody can reach the saga while it sleeps.
  7. Stop. Click Stop Hosting in the Host for Players window. Every player's copy closes at once, and what they saved is kept. Closing the app stops hosting too, after asking.

If you choose an address the computer doesn't have, or a port another program is using, the app says so and nothing starts. An address the internet can reach is refused too, until you tick I know this is reachable from the internet. That tick shows only for such an address, or one you type, and it's never remembered.

Players must open the address you host on, as Saga Management shows it. The host refuses a request made to another name for your computer, such as its Windows name, to keep hostile web pages out.

Every few seconds each player's copy picks up what the others saved. If it finds the saga file damaged, say edited by hand or cut short by another program, it says so once and goes on with its own data. Its next save writes the whole file again.

From a terminal instead. The same host runs in a terminal in the app's folder with uv run python tools/serve.py --host ADDRESS, or, in a downloaded copy, armarius-terminal host --host ADDRESS. Add --port 8001 for another port, or --ssh-port 2222 for SSH. It hosts until you press Ctrl+C there, whichever window of the app you have open. It refuses an address the internet can reach unless you add --allow-public.

Over SSH instead of a browser

A player who prefers a terminal can connect with SSH. Tick Also over SSH when you start hosting, and the browser page keeps working alongside. The SSH port is 2222 unless you change it (from a terminal, add --ssh-port 2222).

The SSH server is the app's own. No Windows accounts are involved, and any user name is accepted, because who the player is comes from the same sign-in as in a browser.

The first time, the app makes a host key and keeps it in your computer's keychain, such as Windows Credential Manager, macOS Keychain or a Linux Secret Service. It's never kept in the save folder, which a cloud service may sync. Players' SSH clients ask once whether to trust it. A key an older version left in the save folder (ssh_host_key) is moved into the keychain and the file deleted, so players' clients still know your computer. With no keychain, SSH hosting is refused and says why.

Players connect with ssh -p 2222 player@ADDRESS from Windows Terminal (Windows 10 and 11 include ssh), macOS Terminal or any Linux terminal. They get the same saga list and sign-in. Their terminal should be at least 120 columns by 45 rows, with true colour and Unicode. Windows Terminal, iTerm2, macOS Terminal and the usual Linux terminals have both, and the old Windows console doesn't. Over SSH, Export isn't offered, since the file could only land on your computer.

What players see

  • The app fills the browser window. It's laid out for at least 120 columns by 45 rows. On a 1080p screen, add ?fontsize=12 to the address (http://ADDRESS:8000/?fontsize=12) or zoom the browser out.
  • The browser keeps some keys for itself, such as Ctrl+W, Ctrl+T and F5, so don't use them in the app.
  • A player changes only the characters they play and what belongs to them. Everything else they can look at and Export, which downloads in their browser. See Players.
  • Everyone's changes reach the others within a few seconds. See Signing in.

What the app does for you. The host answers only requests addressed to the address you chose, and the app's own connection only from its own page, so a web page from another site can't open a copy. After three wrong passcodes for one name, each try waits longer, and a passcode shorter than 14 characters asks for a new one (see Signing in). A copy opened from a browser or over SSH has no command palette and can't change your settings. Its file chooser (Import, for a storyguide who signs in) shows only your exports folder.

See also: How to host a saga for your troupe, Players, Signing in, Saga picker