configuration & models

Everything lives in one file, config.yaml, seeded on first run from the tracked template config.default.yaml. A clone keeps it beside the install, and pipx/uv installs keep it in ~/.saturn. /config <dotted.key> <value> sets most of it live. Edits persist by default, and --session keeps one for this session only. Trust keys are the exception (see below).

::tiers

Each tier binds one chat model, used for the agent's calls and the background work (compaction, the memory review, /init), plus an embedder. Swapping hardware is a one-line active_tier change.

active_tier: 4b

tiers:
  4b:
    model: "qwen3.5:4b"
    embedder: qwen3-embedding:8b
  9b:
    model: "qwen3.5:9b"
    embedder: qwen3-embedding:8b
  27b:
    model: "qwen3.8:27b"
    embedder: qwen3-embedding:8b
  35b:
    model: "qwen3.6:35b"
    embedder: qwen3-embedding:8b

The ladder is a recommendation, not a gate. Any Ollama model with native tool-calling binds with /models use <id>. capabilities: declares each model's context window, and an unknown model falls back to an 8,192-token window. /config runtime.num_ctx <size|auto> overrides every window at once. Ollama is the only backend.

::/models

The model page reads your machine (on Apple silicon: the chip, its GPU cores, unified memory, and memory bandwidth) and prices two ladders against it, the four chat tiers and three qwen3-embedding sizes: weights, the memory each needs at its window, an estimated decode speed, and whether it's pulled. The recommendation is the largest tier that fits and decodes at 10 tok/s or better. A tier that fits but would crawl reads fits · slow and is never the default. Below the ladders come every other model you've pulled, chat models and embedders in separate sections, each with its size, parameter count, and whether it fits. The rows are numbered: pick a chat model to run it on the active tier, or an embedder to switch to it. A chat model that can't call tools reads no tool calling and can't be picked. The first launch runs this page.

/models                  the page, then pick a row (Enter takes the recommendation)
/models list             the page only
/models use <id>         run any Ollama tool-calling model on this tier
/models embedder <id>    switch the embedding model (re-embeds the corpus)

A pick whose model isn't pulled asks first (y/N, default no) and switches only after the pull succeeds. Every switch persists to config.yaml; --session applies it live only.

::runtime

::other sections

::what persists

• –Ordinary keys set with /config persist to config.yaml by default; --session keeps the change for this session. A save rewrites the key's existing line in place, comments kept. A setting added to Saturn after your config.yaml was written gets its line appended to the end of its section, and nothing else in the file changes. A key Saturn doesn't know is never written.
• –Trust keys (runtime.auto_approve, runtime.airgap, runtime.quarantine, runtime.grant_scope, and shell.env_scrub) and the /policy toggles are session-only unless you pass --save. A loosened posture is never written to disk silently.
• –/policy risk --save overrides, the shell prefix allowlist, and the Shortcuts allowlist persist in database/permissions.json. /policy allow <prefix> always persists; a gate a grant follows grant_scope.
• –The live config.yaml is user data that git doesn't track, so saved settings never dirty the repo or break /update.