tai/settings.md

settings.md

Vault-backed settings: one catalog, three functions, env always wins. Every TAI_* knob that behaves like a setting lives in the settings table and is readable and overridable through get_or_create_settings / upsert_settings / get_all_settings. SettingsTests.test_settings_doc_names_every_key fails when this file drifts from the code.

Precedence

For every catalog key, the effective value resolves in this order:

1. env: a non-empty ${ENV_VAR} (empty counts as unset, matching every existing reader)
2. db, own scope: the profile row when one is stored
3. db, global scope: the shared fallback row
4. catalog default

Two run-scoped inputs outrank even env: CLI --theme beats the theme setting, and CLI --no-opencode beats the stored opencode flag. A stored model pin counts as explicit, so per-directory model defaults do not override it.

Boot applies vault settings in boot() (and in default_runner for workers) through boot_settings: Config fields first, then the peripheral keys are exported into os.environ so the existing readers, which all run later, pick them up unchanged. Applied keys are printed (settings from vault: ...) and also exported for nested processes. A second boot pass is idempotent: exported env wins, so nothing is applied twice.

Row shape

Every function returns the same row dicts:

Field	Meaning
key, env, desc	catalog identity and one-line docs
type	string, bool, or float
default	python value used when nothing is set (may be null)
required	null and empty are rejected; a required key must always resolve
nullable	whether null (unset) is a legal stored value
options	strict list the value must be one of, or null
preferred	suggestions that still allow free input, or null (reserved: no v1 entry uses it)
encrypted	sealed at rest with the vault key when true
stored	decrypted canonical string in the vault, or null
value	effective typed value after precedence
source	where value came from: env, db, or default
scope, created, updated	owning scope and ISO UTC timestamps

Canonical stored forms: bool as 1/0, float as str(float), strings raw. Env bools accept 1/true/yes/on and 0/false/no/off (case-insensitive, surrounding whitespace ignored); anything else falls back to the default, exactly like the readers. Env floats use plain decimals (12, 2.5); anything else falls back to the default. Three bool keys extend the env word sets (see catalog): those legacy spellings stay readable from env but are never written by upsert.

API

• get_or_create_settings(keys=None, scope="global"): ensure rows exist (all 28 when keys is None, a subset or single key otherwise) and return their merged rows. Unknown keys and bad scopes raise ValueError, as does a required key that resolves to nothing.
• get_all_settings(scope="global"): the same merge, read-only: creates no rows.
• upsert_settings(items, scope="global"): validate a {key: value} mapping and store it atomically; anything invalid raises ValueError and writes nothing. None clears a nullable key back to null. Returns fresh rows for the written keys.

Scopes are global or a profile name (PROFILE_RE). A profile literally named global shares the global scope.

Encryption

Keys marked encrypted are sealed with seal.lock on write and opened on read; plaintext vaults store them as-is, same as vault secrets. At rest they are indistinguishable from other sealed blobs (tai1$...). Passphrase rotation re-seals every sealed settings value and leaves plaintext values alone. Booting a vault that holds sealed settings without the passphrase refuses to start, like the other sealed tables. Encrypted settings are config, not vault secrets: they are not covered by secret redaction, exactly like their env equivalents.

Catalog

28 keys. Types, defaults, and flags below are asserted by SettingsTests.test_catalog_self_check, so this table cannot drift silently.

Key	Env	Type	Default	Req	Null	Options	Enc	What it does
model	TAI_MODEL	string	muse	yes	no	-	no	Default model id. A stored pin counts as explicit.
backends	TAI_BACKENDS	string	null	no	yes	-	yes	Extra OpenAI-compatible backends: ;-separated label|base|key[|model][|profile]; a $VAR key reads another env var.
openrouter_key	OPENROUTER_API_KEY	string	null	no	yes	-	yes	OpenRouter key. Most free models work without one.
openrouter_models	TAI_OPENROUTER_MODELS	string	null	no	yes	-	no	Comma-separated model ids. Null means live discovery.
openrouter_enabled	TAI_OPENROUTER	bool	true	no	no	-	no	Offer the OpenRouter backend.
opencode_enabled	TAI_OPENCODE	bool	true	no	no	-	no	Offer the opencode backend. CLI --no-opencode wins.
opencode_models	TAI_OPENCODE_MODELS	string	null	no	yes	-	no	Comma-separated model ids. Null means live discovery.
devplace_key	DEVPLACE_API_KEY	string	null	no	yes	-	yes	DevPlace key. Null disables the fallback backend.
devplace_base	TAI_DEVPLACE_BASE	string	https://devplace.net/openai/v1	no	no	-	no	DevPlace API base URL. Trailing slashes stripped.
devplace_models	TAI_DEVPLACE_MODELS	string	null	no	yes	-	no	Comma-separated model ids. Null means live discovery.
pollinations_enabled	TAI_POLLINATIONS	bool	true	no	no	-	no	Offer the Pollinations backend.
pollinations_models	TAI_POLLINATIONS_MODELS	string	null	no	yes	-	no	Comma-separated model ids. Null means live discovery.
zen_enabled	TAI_ZEN	bool	false	no	no	-	no	Opt in to the opencode.ai zen backend.
zen_models	TAI_ZEN_MODELS	string	null	no	yes	-	no	Comma-separated model ids. Null means live discovery.
retry_seconds	TAI_RETRY_SECONDS	float	0.0	no	no	-	no	Seconds to retry all backends on total failure. 0 means forever.
voice	TAI_VOICE	string	en-US-EmmaMultilingualNeural	no	no	-	no	Edge TTS voice name for speak.
theme	TAI_THEME	string	dark	no	no	dark, light, nord, gruvbox, ansi	no	TUI theme, strict. CLI --theme wins.
gemini_plan	TAI_GEMINI_PLAN	bool	false	no	no	-	no	Try the Gemini plan approval variant first. Env also accepts plan.
codex_sandbox	TAI_CODEX_SANDBOX	bool	false	no	no	-	no	Re-enable Codex sandbox flags. Env also accepts read-only.
box_caps	TAI_BOX_CAPS	bool	true	no	no	-	no	Apply caps to old sandbox boxes. False skips. Env honors only 0 as false.
muse_bin	MUSE_BIN	string	null	no	yes	-	no	muse CLI path override. Null means PATH lookup.
opencode_bin	OPENCODE_BIN	string	null	no	yes	-	no	opencode CLI path override. Null means PATH lookup.
grok_bin	GROK_BIN	string	null	no	yes	-	no	grok CLI path override (then grokcli). Null means PATH lookup.
claude_bin	CLAUDE_BIN	string	null	no	yes	-	no	claude CLI path override. Null means PATH lookup.
codex_bin	CODEX_BIN	string	null	no	yes	-	no	codex CLI path override. Null means PATH lookup.
gemini_bin	GEMINI_BIN	string	null	no	yes	-	no	gemini CLI path override. Null means PATH lookup.
opencode_client_name	OPENCODE_CLIENT_NAME	string	null	no	yes	-	no	x-opencode-client header override. Null means built-in.
opencode_client_ua	OPENCODE_CLIENT_USER_AGENT	string	null	no	yes	-	no	User-Agent override for zen. Null means built-in.

Deliberately not cataloged

Var	Why it stays out
TAI_HOME	locates the vault; cannot come from inside it
TAI_PASSPHRASE	unlocks the vault; cannot come from inside it
TELEGRAM_BOT_TOKEN	owned by telegram.env plus the service unit; move it only with a migration
TAI_SESSION	per-process derived context, resolved around store boot
TAI_TUI_SOCK	per-process socket rendezvous path
TAI_TUI_VERIFY	dev-only pipeline verification switch
GRR_URL	owned by grr.json (env wins there too)
CAP_SESSION_CONFIG	wire passthrough for one speak turn, not a setting
TAI_PLEXER_*	runtime plexer state, not settings
TERM, NO_COLOR, SHELL, TMUX*, EDITOR, VISUAL, HISTFILE, USER, TZ, VIRTUAL_ENV, XDG_*, COLORFGBG, TERMINFO	foreign standards tai reads but does not own

Internal tuning constants (WORKER_STEPS, CAP_*, BOX_*, scheduler intervals) are code, not settings: promoting one means a catalog entry, a wiring decision, and a test, not a silent centrally-stored override. mplex.toml, CAP fleet files, and per-directory backend pins (dir_defaults) keep their own homes for the same reason.

Maintenance

To add a setting: append a setting_spec to SETTINGS_CATALOG, route it through CONFIG_SETTING_FIELDS (read at Config build) or SETTING_EXPORT_KEYS (read later at call sites), extend the catalog table above, and extend SettingsTests. The catalog self-check asserts every default validates, every options list holds its default, env names are unique, and the two routing tuples partition the catalog exactly. The theme row is pinned against TUI_THEMES so a new theme breaks the test until the options list follows.