Configuration
Where the operator's configuration file lives, its format, and the three verbs that write it.
For the operator who has to decide the values this product will not guess.
After reading it you can find the file, read its format, set a key without disturbing the others, and see which tier produced an effective value.
Before you start: an installed machine. Identity is minted here, so this is the first section after an install.
Read in this order. This page first — the file, its format and the three verbs that write it. Then the page for whichever decision you are making; the pages after it are independent of one another.
Location and format
One file per operator, not per workspace: ~/.saphan/config. The config set|show|init
verbs never resolve a workspace, unlike gate/merge/run/teardown. There is no
--config flag and no environment override for this file's location — it is always
~/.saphan/config, written mode 0600.
Format: bracketed sections, key = value, with blank lines and # comments ignored. Values
may be quoted or bare — one layer of surrounding double quotes is stripped on read.
An absent file is simply the empty configuration — no error. A present but
malformed file is a hard error: a line without = is a named load failure
(malformed line %q (want key = value)), never a silent skip.
The three verbs
| Verb | What it does |
|---|---|
saphan config set <key> <value> | Writes one dotted key, preserving every other key already in the file — the same round-trip discipline git config gives its own file. Unknown keys and invalid policy values are refused with the full accepted vocabulary in the error. |
saphan config show [--provenance] [--json] | Prints effective values; --provenance names which tier produced each one. |
saphan config init [--from git|system] [--actor …] | Mints identity: proposes from git or the system account, but identity.actor is always human-confirmed. With no TTY and no --from/--actor it refuses by name and writes nothing — it never guesses an identity. |
What this section does not cover
⚠ The complete generated key reference is not published on this site. These pages carry the keys an operator decides, with the vocabulary each one accepts; a page-per-key reference is not here. ⚠ A credential's VALUE is never a configuration key — every secret reaches the product as the NAME of an environment variable or the PATH of a file you bring, and the pages below say so per key. ⚠ Permission classes and egress policies are configured but not explained here: their reasoning is Security and Egress control.