realm.toml Reference

realm.toml lives at the root of your realm directory. It is the single configuration file — identity, SSH, harbormaster, customs, federation, narrator register. Changes take effect on reload; the beacon stays lit.

All paths are relative to the realm directory unless otherwise noted.

[realm]

[realm]
name        = "winding-stair"
hostname    = "winding-stair.example.com"
operator    = "did:archi:you"
mood        = "calm"
description = "A waystation on the northern strait."
capacity    = 64

Field	Type	Default	Notes
`name`	string	required	Short identifier. Appears in room headers, log files, and federation metadata. No spaces; hyphens permitted.
`hostname`	string	required	Fully-qualified domain name travelers connect to. Must match your DNS record.
`operator`	string	required	Your DID. Run `pharos identity` after first boot to see the value generated for you.
`mood`	string	`"calm"`	Ambient register. See Mood.
`description`	string	`""`	Shown in `/about` and paraphrased by the harbormaster when addressed directly.
`capacity`	integer	`64`	Maximum concurrent SSH sessions.

[realm.ssh]

[realm.ssh]
port     = 22
host_key = "keys/realm.key"
banner   = ""

Field	Type	Default	Notes
`port`	integer	`22`	Inbound SSH port. Must be open in your firewall.
`host_key`	path	required	Path to the realm’s Ed25519 private key.
`banner`	string	`""`	Displayed before authentication. Some operators use it for a brief customs notice or a line from the harbormaster.

[realm.harbormaster]

The harbormaster is the first voice a traveler hears. It is configured here, not authored through build mode.

[realm.harbormaster]
name  = "Old Cael"
brief = "A weathered man in an oilskin coat, standing by the gate."
lines = [
  "Welcome to the Stair. Road's washed out tonight. You'll stay.",
  "Your cargo's your own, long as it stays sheathed.",
  "The beacon's been dark since sundown. Don't expect news from the north.",
]

[realm.harbormaster.greetings]
familiar = "Back again. Good crossing?"
partner  = "Welcome back. The usual room is free."
known    = "I remember you. Come in."
neutral  = "Evening. Papers in order?"
stranger = "First time here. Mind the customs."

Field	Type	Default	Notes
`name`	string	required	The harbormaster’s name as it appears in the room occupant list.
`brief`	string	required	One-line present-tense description. Shown in the room’s occupant list.
`lines`	array	required	Canned responses drawn from when the harbormaster is addressed. Cycles without immediate repetition.

Greetings are trust-tier specific. The harbormaster selects based on the traveler’s trust level — familiar, partner, known, neutral, or stranger. All are optional; if a tier is absent, the harbormaster falls back to lines. On a traveler’s first visit to the realm, it delivers the greeting followed by the customs notice.

For guidance on writing a harbormaster with character, see Writing the Harbormaster.

[realm.customs]

Customs policy controls what foreign-made items can cross your borders and what happens to them when they arrive.

[realm.customs]
default_policy = "accept"

[[realm.customs.trust]]
origin = "thornwood.example.com"
policy = "accept"

[[realm.customs.trust]]
origin = "ashpit.example.com"
policy = "quarantine"

default_policy applies to any item not covered by a specific trust rule.

Value	Effect
`accept`	Item crosses the border unchanged.
`quarantine`	Item is held at the border and flagged for operator review. The traveler is informed.
`inert`	Item crosses but its scripted behaviour is stripped. It becomes a mundane object. Provenance record is preserved.

Trust rules are evaluated top to bottom; the first match wins. origin is a realm hostname or * for a catch-all. If no rule matches, default_policy applies.

[realm.federation]

[realm.federation]
port    = 3456
enabled = true

[[realm.federation.peer]]
hostname    = "thornwood.example.com"
pubkey      = "ed25519:3b4af2…"
trust       = "partner"
attenuation = 1

Field	Type	Default	Notes
`port`	integer	`3456`	Porthmos listening port. Open inbound from peer addresses only.
`enabled`	boolean	`true`	Set `false` to run as a standalone island. Disables all federation.

Each [[realm.federation.peer]] block declares one peering relationship.

Field	Type	Default	Notes
`hostname`	string	required	The peer realm’s hostname.
`pubkey`	string	required	The peer’s Ed25519 public key. Verify this out of band before adding. The peer’s `/about` command displays it.
`trust`	string	`"neutral"`	Default trust level assigned to travelers arriving from this realm: `partner`, `known`, `neutral`, or `stranger`.
`attenuation`	integer	`1`	Signal distance in hops. `1` means direct neighbor. Higher values reduce signal strength for cross-realm narration — voices from further away arrive quieter, more uncertain.

Federation is bidirectional: both realms must declare each other as peers before the lane opens. A one-sided declaration results in a refused handshake, narrated as fog on the strait.

Mood

The mood field sets the ambient register of the island — the tonal disposition the narrator uses for weather, light, and atmosphere. A grim island in rain describes the same room differently from a calm island in rain. Mood does not override room descriptions; it inflects them.

Value	Character
`calm`	Clear skies, steady beacon, neutral narration. The default.
`uneasy`	Something is off. Fog at the edges.
`tense`	A storm is building.
`grim`	Settled into difficulty. The weather has been this way for a while.
`festive`	Lights, noise, warmth.
`fog`	Visibility reduced. Cross-realm signals arrive distorted; the ◈ indicator dims.
`storm`	Active weather. Arrivals are delayed. Transitions are rougher.

Mood can be changed at runtime without a reload:

watch> set mood tense

Mood set: tense. Next room refresh will carry it.

[realm.narrator]

[realm.narrator]
register = "standard"

Value	Character
`standard`	Full prose descriptions, mixed register. The default.
`formal`	Elevated diction, more archaic constructions. Suits councils and courts.
`sparse`	Short sentences, minimal description. Suits frontier outposts and working harbors.

Register affects system-generated narration — travel transitions, NPC reactions, consent prompts, system events. It does not rewrite room descriptions authored by builders.

Reloading

Configuration changes take effect on reload. The beacon stays lit:

systemctl reload pharos-winding-stair

Or from admin mode inside the realm:

watch> reload

Config reloaded. 0 errors.

The keypair and event store are never touched by a reload. If pharos reports errors on reload, the previous configuration remains active.