Skip to content

Configure the essentials

This guide sets the values most setups change and shows where every other setting lives. It assumes SASE is installed; defaults work until you have a reason to change them, so read first and edit only what you need.

Before you start

You need to know where configuration lives. The base file is ~/.config/sase/sase.yml; overlay files matching ~/.config/sase/sase_*.yml merge on top of it, and a project-local sase/sase.yml usually takes highest priority. Check for drift without writing anything:

sase init --check

1. Set the default model

Launches without an explicit request use llm_provider.default_model (@large unless changed). Set it when most of your work wants a different level:

llm_provider:
  default_model: "@medium"

See Choose providers and models for the alias levels and how to check provider readiness.

2. Keep automatic recovery on

Agents interrupted by a live update restart automatically while agent_auto_restart.enabled is true. Leave it on unless you are debugging the recovery itself:

agent_auto_restart:
  enabled: true

3. Size the runner capacity

max_running_agents caps how many agents run at once (default 10). Raise it on a large machine, lower it when agents compete with other work:

max_running_agents: 10

Lowering the cap never kills running agents; new work simply waits until capacity frees up. See Unstick a queued agent when runs wait longer than expected.

4. Confirm the result

Validate the configuration layer and re-check initialization drift:

sase doctor -C config
sase init --check

Both report clean when the values parse and nothing needs to run.

If it goes wrong

sase doctor -C config names the layer and key at fault; fix that value and re-run the two confirmation commands. For failures outside configuration, start with Diagnose problems with sase doctor.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.