Configuration

Every setting a station reads lives in one file, config.toml, in its data directory. This page lists every key with its default and what it means.

Hand-written from the source. This page mirrors the [StationConfig] structs in crates/rrn-station/src/config.rs of the station repo, which are the authority. It is not generated. If a key here and the code disagree, the code is right and this page needs an edit; re-check it whenever a change to that file lands.

Where it lives and how it is created

The data directory is ~/.railroad/station unless you pass --data-dir to station. station init creates the directory and writes a default config.toml: a writer with no peers, listening for other stations on a loopback port chosen at random between 7400 and 7499, and every other section at its default. Every section except [network] may be omitted entirely and takes its defaults.

A malformed file is an error with a line number. It is never silently replaced. The station reads the file once at start; edit it, then restart.

Values are TOML: strings in quotes, numbers bare, lists in square brackets. Amounts are in centicommons, whole numbers, one hundredth of a Common. Durations are in seconds.

Two complete examples

A community’s station, the normal case. It owns the log and never pulls from anyone, so it has no peers:

[network]
listen = "127.0.0.1:7400"      # station-to-station port; loopback is correct for a lone writer
role = "writer"                # the default

[mobile]
listen = "0.0.0.0:7500"        # where phones and command-line wallets connect
advertise = true               # announce on the LAN so the app finds it by name
# name = "Railroad Station — Maple Street"

An optional read-only replica of that writer, for audit or an off-site copy. It pulls the writer’s log and admits nothing:

[peers]
list = ["192.168.4.1:7400"]    # the writer's [network] listen address

[network]
listen = "127.0.0.1:7401"
role = "replica"

A writer with a non-empty [peers] list refuses to start and names the fix. A replica with an empty list is valid but useless, and the station warns. The rule is ADR-0020: one log, one writer.

[network]

Where this station accepts connections from other stations, and its role. This is a different port and protocol from the one phones use.

[peers]

[mobile]

How paired phones and command-line wallets reach this station.

[settlement]

The delay between a payment being confirmed and balances moving, per tier. The rule is ADR-0011.

[credit]

How far into debt a member may sign themselves, and the headroom certificates that reserve credit ahead of an outage. The rules are ADR-0018 and ADR-0021.

[timers]

How often each background sweep fires. All in seconds. The defaults suit a pilot; a demo shortens the first two.

On a replica the sweeps that would append to the log do not run.

[dtn]

Delay-tolerant delivery: the receipts the station signs for records that arrive by courier, paper, radio, or text.

[sidecar]

The supervised Reticulum daemon, rnsd, which carries traffic over mesh and LoRa radio. Off by default. Reticulum is strictly a carrier and never the security boundary, per ADR-0013 and ADR-0026. You install rnsd yourself; see Radio and text message.

A crashed or degraded sidecar never takes the station down. rrn status shows its state.

[lora]

The airtime budget the radio transport paces to, and the adapter that drives it. Radio throughput is small and duty-cycle rules cut it further; the station sends money before governance before bulk.

[lora.rnode]

The physical RNode LoRa radio. Absent by default: a station never transmits on a frequency or power nobody chose. Spectrum compliance is the operator’s responsibility per region, and every node on one network must share frequency, bandwidth, and spreading factor. See Radio and text message.

[sms]

Text messages as a carrier for records a member’s phone already signed. Off by default, and the modem gateway that would carry the texts is not built: enabling this section today leaves the carrier supervised but idle. The format is in the wire specifications.

[storage]

The at-rest profile. Chosen when the station is provisioned, not a runtime toggle. The encrypted profile is ADR-0024; see Encrypted at rest.

[storage.encrypted]

Read only when at_rest = "encrypted". Written for you by station encrypt-in-place.

The holder set is deliberately not stored here. A list of holders on the unencrypted boot directory would hand whoever seized the machine a list of people to pressure. The authoritative record lives inside the container and is readable, once unlocked, with station vmk status.

Environment variables

The rrn console finds the station’s socket at ~/.railroad/station/station.sock; pass --socket for a station elsewhere.

The data directory

Plaintext profile. One flat directory, ~/.railroad/station by default:

station backup bundles the right ones into a single encrypted archive.

Encrypted profile. The directory you pass as --data-dir becomes the unencrypted boot directory, holding only config.toml, station.sock, the container state.img, and a tiny vmk.descriptor that records the threshold and nothing about who the holders are. Everything else above lives inside the container, mounted at state/ once unlocked, alongside vmk.rrnrecovery, the full holder record. Backups cover what is inside the container but not the boot directory’s config.toml, so keep a copy of that file with your archives.