Every key

The authority is the error message config set prints for an unknown key. It lists exactly what the binary in front of you accepts, and no page can be more current than the build it is describing.

⚠ This table and that error message are two different lists, and neither one contains the other. This table describes the configuration file, which is the larger surface: the [oauth_server] and [gateway] sections below are read when those servers start and are not keys config set writes at all. In the other direction, this table is maintained by hand, so a key can be accepted by the product before it is described here. ⇒ Where the two disagree, the error message decides what your build takes, and this page decides nothing — if you are refused a key that appears below, read that as an answer about your build rather than as a typo.

How a key on this page becomes a line in the file

saphan config set takes one dotted key. The file has sections. The two spellings are related by one rule, and it is the same rule for every family below: the last dotted segment is the key; everything before it is the section header.

That is why a repeated section below is headed [lane.<alias>] and [host.<id>] rather than [lane] and [host]: the variable segment belongs to the section name, not to the key.

⚠ So no key name on this page contains a dot. If you are reading a dotted name anywhere, you are reading a config set argument, and it splits at its last dot before it reaches the file. ⛔ Getting the split wrong matters, because most sections will not tell you. Only the three sections marked below refuse an unknown key by name at load; in the rest, a key written under the wrong header is not refused — it is simply not read, and a configuration that is quietly not read looks exactly like one that is.

[identity]

[engine]

[workspace]

[run]

[store]

[evidence]

[oauth]

⚠ Not [oauth_server]. This section says which authorization server the engine trusts as a resource server. The next section says what our own authorization server is. oauth.issuer is somebody else's name; oauth_server.issuer is ours. An operator who sets one where the other belongs gets a server that trusts itself.

[oauth_server]

⚠ Not [oauth]. This section configures the authorization server this product runs — the saphan-oauth binary: its own name, its own certificate, its own database. The section above configures which other authorization server the engine believes. Setting oauth.issuer when you meant oauth_server.issuer makes the engine trust a server that does not exist; setting oauth_server.issuer when you meant oauth.issuer makes this product announce itself under a name it cannot serve.

Unknown keys in this section are refused by name at load, unlike most sections (§6.1). The error message lists exactly the keys in the table below; if the two ever disagree, the error message is the authoritative one.

Signing keys are never created automatically. A server with no published key refuses to start and names the command that fixes it. See §13 for the runbook.

[gateway]

This section configures saphan-gateway, the separate stateless process serving the client HTTP contract. It is intentionally smaller than [oauth_server]: the gateway terminates no TLS and binds only to loopback; a local reverse proxy owns the public certificate.

Unknown keys in this section are refused by name at load. There is one key:

The required --workspace is deliberately not a config key: every start names the absolute workspace it serves. The complete human start/check/stop ceremony and the current operation coverage are in the client-contract gateway.

[trust]

[org]

[server]

⚠ Not [oauth_server]. This section configures saphan server — the ENGINE, which is a resource server: it accepts tokens. [oauth_server] configures the authorization server that issues them. Both have an issuer-shaped key and they are different names.

Unknown keys in this section are refused by name at load (since server.public_base_url landed), unlike most sections (§6.1). A typo here is the one class of mistake that must never be silent: public_base_urls = "https://…" quietly ignored leaves the engine naming itself from its own socket while the operator reads a file that says otherwise.

What public_base_url decides, and what happens when it is absent

Set it, and nothing a caller sends can change the name this engine asserts. Not the Host: header, not X-Forwarded-Host, not RFC 7239 Forwarded: host=, not an absolute-form request target, not HTTP/2 :authority, not the TLS server name the client asked for — and not a trusted proxy either. The value stops depending on the request at all.

Leave it absent, and the engine names itself from the address it observed on its own socket — the local address of the connection, which no client can set. On the solo tier (nothing configured, bound to 127.0.0.1:7654) that is http://127.0.0.1:7654, byte for byte what earlier releases produced. If a trusted hop reports X-Forwarded-Proto: https, the scheme — and only the scheme — follows it.

An engine behind a proxy MUST set this key. Unconfigured, it will name itself by its own loopback address, which its clients cannot reach. Earlier releases papered over this by believing X-Forwarded-Host from any loopback peer — which on that host means every local process, so any of them could rename the server and have tokens signed under that name. That hole is closed; the key is what replaces it.

Setting it changes one thing for local clients: an engine reached as http://localhost:7654 used to advertise http://localhost:7654 and now advertises the address it is actually on. Clients follow the discovery documents, so they follow the change.

The ISSUERS.md row that goes with it

Enrolling an authorization server is an owner act — the engine never writes that record. The row's audience column is this engine's resource identifier, which is public_base_url + /mcp. See Issuer enrolment for the numbered runbook and the exact line to paste.

[headroom]

[probe.model]

Set the lists through the dotted config keys:

saphan config set probe.model.claude-code "opus,fable"
saphan config set probe.model.codex "gpt-5.6-sol,gpt-5.5"

The list distinguishes “this seat is spent” from “this seat is spent for this model.” fleet headroom stops at the first model that answers and reports that model plus every earlier model that did not. The trade-off is direct: each failed model before the answer is another real, potentially billable probe spawn. A seat that answers the first listed model still receives exactly one spawn. Omitting a key applies and prints the documented default; an empty list is refused, and any backend other than claude-code or codex is refused by name at both load and config set.

The command-line fleet headroom --model <name> remains an explicit one-model override for the separate question “can every applicable seat run this exact model?” It applies that one-element list to every backend for that invocation.

[scheduler]

[fleet]

The three [notice…] sections — the outbound chat notices

These are the fourteen keys behind Notifications: a binding is a destination plus the credential and rendering to reach it, a route says which notice type goes to which binding, and one key names the single machine that does the sending. <name> is a binding name you choose; <n> is a route number — both are variable segments, so by the rule at the top of this page both belong to the section header and neither appears in a key.

⚠ These fourteen keys are not in the Known keys: list on the generated saphan config reference, which was produced from one build's own help text, and which release first accepts them is not stated anywhere on this site. So the paragraph at the top of this page is the one that applies here in particular: if config set refuses one of them, the refusal is telling you about your build.

[notice.binding.<name>] — repeated section, keyed by the binding name you choose

[notice.route.<n>] — repeated section, keyed by route number

[notice.sender]

So a binding called person is [notice.binding.person] in the file, its first route is [notice.route.1], and the sending machine is primary under [notice.sender] — saphan config set notice.route.1.binding person writes binding = "person" under [notice.route.1], the same split this page applies to lane.local.credentials_env and probe.model.claude-code.

[host.<id>] — repeated section, keyed by machine id

[lane.<alias>] — repeated section, keyed by alias

A [lane] with no alias, or a [host] with no id, is a named load failure, not an ignored block: an unaddressable lane is not a lane, and a per-machine override with no machine is not an override.