Runtime and stored data configuration

Process history, service hosting, artifacts, disk use, and reading surfaces.

Defaults come from the schema when declared, otherwise from the bundled YAML. An object with listed children is expanded below; {…} and […] summarize compound defaults. A dash means the schema has no finite allowed-value list.

artifacts

Config key	Type	Default	Allowed values	Description
artifacts	object	{capture, retention} (values below)	—	Bounds automatic artifact capture and controls the opt-in retention policy for stored artifact data.
artifacts.capture	object	{max_stored_per_agent, max_history_scan, max_file_size_bytes, pool_max_bytes} (values below)	—	Limits copied bytes and history scanning for artifacts captured automatically at agent finalization.
artifacts.capture.max_stored_per_agent	integer	50	—	Maximum number of automatic artifact captures whose bytes are copied per agent run. Version-control-backed references are not counted and are not capped.
artifacts.capture.max_history_scan	integer	20	—	Maximum number of durable commits searched per file for an exact version-control-backed artifact revision.
artifacts.capture.max_file_size_bytes	integer	104857600	—	Maximum size of one file copied into the workspace-local prompt-artifact pool. Larger files are still hashed and recorded.
artifacts.capture.pool_max_bytes	integer	1073741824	—	Maximum workspace-local prompt-artifact pool size before opportunistic garbage collection.
artifacts.retention	object	{…} (6 keys; values below)	—	Policy for pruning and trashing captured artifact data after agent finalization.
artifacts.retention.enabled	boolean	false	—	Enable automatic artifact retention after agent finalization. When disabled, retention removes nothing.
artifacts.retention.empty_shard_removal_budget	integer	2000	—	Maximum number of empty ace-run month/day/run shard directories removed in one retention apply pass.
artifacts.retention.keep_per_label	integer	3	—	Number of newest automatic captures kept per label. Set to 0 to disable generation-based retention.
artifacts.retention.keep_recent_run_months	integer	2	—	Number of newest calendar months of ace-run directories kept whole before whole-run reclamation may select terminal, unreferenced runs.
artifacts.retention.max_age_days	integer	90	—	Trash automatic captures older than this many days. Set to 0 to disable age-based retention.
artifacts.retention.trash_grace_days	integer	14	—	Number of days artifact trash remains restorable before purge removes expired entries.

artifact_refs

Config key	Type	Default	Allowed values	Description
artifact_refs	object	not set	—	Artifact-reference policies.
artifact_refs.file	object	not set	—	Allow-listed roots for @file:<path> references.
artifact_refs.file.roots	array	not set	—	Allow-listed filesystem roots for absolute or home-relative @file prompt references.
artifact_refs.file.roots[]	object	not set	—	—
artifact_refs.file.roots[].name	string	not set	—	Stable logical root name used in published @file metadata.
artifact_refs.file.roots[].path	string	not set	—	Absolute or ~/ rooted local path that bounds @file references.
artifact_refs.file.roots[].path_globs	array	not set	—	Optional positive/negative root-relative POSIX globs.
artifact_refs.file.roots[].path_globs[]	string	not set	—	—

disk

Config key	Type	Default	Allowed values	Description
disk	object	{pressure} (values below)	—	Disk-pressure thresholds and disk-owner diagnostics.
disk.pressure	object	{warn_free_percent, error_free_percent, top_owner_min_bytes} (values below)	—	Thresholds used by the disk doctor check and pressure housekeeping.
disk.pressure.error_free_percent	number	1.0	—	Error when filesystem free space falls below this percentage, in addition to the absolute byte floor.
disk.pressure.top_owner_min_bytes	integer	1073741824	—	Minimum unowned disk row size named directly in pressure diagnostics.
disk.pressure.warn_free_percent	number	5.0	—	Warn when filesystem free space falls below this percentage, in addition to the absolute byte floor.

managed_tmp

Config key	Type	Default	Allowed values	Description
managed_tmp	object	{…} (5 keys; values below)	—	Retention horizons and pressure thresholds for the managed SASE temp root reaped by sase disk reap / the hourly managed_tmp_reap job.
managed_tmp.horizons	object	{command_scratch_seconds, handoff_seconds, build_scratch_seconds, run_artifact_seconds} (values below)	—	Age horizons, by bucket category, for the managed temp root's per-subdirectory buckets.
managed_tmp.horizons.build_scratch_seconds	integer	86400	—	Cargo and other build scratch created for one launched agent (build-targets, cargo-targets). Only the non-procfs fallback still waits this long; the dead-launch backstop reaps unheld launch scratch after its own grace.
managed_tmp.horizons.command_scratch_seconds	integer	43200	—	Scratch whose reader is the command that wrote it (editors, wrappers, and similar buckets).
managed_tmp.horizons.handoff_seconds	integer	259200	—	Files handed to a child process that may re-read them mid-run (handoff, muse-prompts, and similar buckets).
managed_tmp.horizons.run_artifact_seconds	integer	1209600	—	Artifacts sase's TUI Agents tab reads back long after the run finished (launch-prompts, workflow-artifacts).
managed_tmp.max_removals	integer	2000	—	Removal budget for one reaper invocation, so a long-neglected root converges across invocations instead of stalling one of them.
managed_tmp.pressure	object	{…} (7 keys; values below)	—	Size- and free-space-triggered pruning of aged build scratch, layered on top of the age horizons above.
managed_tmp.pressure.max_bytes	integer	17179869184	—	Managed-root size that triggers pressure pruning of aged build scratch. 0 disables the size trigger.
managed_tmp.pressure.target_bytes	integer	8589934592	—	Managed-root size the pressure pass tries to return to.
managed_tmp.pressure.min_available_bytes	integer	34359738368	—	Filesystem free-space floor that also triggers pressure pruning. 0 disables the free-space trigger.
managed_tmp.pressure.recovery_available_bytes	integer	51539607552	—	Filesystem free-space target used after crossing the low-space floor.
managed_tmp.pressure.min_age_seconds	integer	43200	—	Minimum age before pressure can prune a large scratch entry.
managed_tmp.pressure.low_free_space_min_age_seconds	integer	3600	—	Emergency minimum age before pressure can prune a large scratch entry once the free-space floor is breached.
managed_tmp.pressure.min_entry_bytes	integer	67108864	—	Small entries do not participate in pressure pruning. Largest-first ordering already prefers big entries; the typical 0.8-0.9 GiB per-launch target must stay eligible.
managed_tmp.dead_launch	object	{enabled, grace_seconds} (values below)	—	Backstop over launch-keyed scratch (agent-tmp, cargo-targets, legacy build-targets) for launches that never ran runner-exit cleanup.
managed_tmp.dead_launch.enabled	boolean	true	—	Run the dead-launch backstop pass in the reaper.
managed_tmp.dead_launch.grace_seconds	integer	7200	—	Quiet age before scratch no live process holds may be reaped.
managed_tmp.agent_cargo_incremental	boolean	false	—	Incremental Cargo check/clippy for launched agents. Only hosts with the splitting rustc wrapper (athena) should set this true; elsewhere incremental test builds cost ~9 GB per run.

markdown

Config key	Type	Default	Allowed values	Description
markdown	object	{print_width} (values below)	—	Markdown prose formatting policy for SASE-generated Markdown.
markdown.print_width	integer	88	—	Column width SASE wraps generated Markdown prose at: plan files, bead notes and pages, memory shims, generated skills, prompt archives, and the default --wrap for 'sase bead show' and 'sase plan show'. The prettier CLI cannot read this value, so repos whose Markdown SASE writes into need their own prettier config to match.

monitor

Config key	Type	Default	Allowed values	Description
monitor	object	{tool_wrap, evidence_limits} (values below)	—	Detached monitor and continuation settings.
monitor.tool_wrap	string	"verify"	"off", "verify", "all"	Which monitors run their command inside sase tool run: verify wraps only -p/--profile verify monitors, all wraps every monitor, off wraps nothing.
monitor.evidence_limits	object	{selected_diagnostics_bytes, fallback_tail_bytes, total_raw_excerpt_bytes, raw_tail_lines} (values below)	—	Resource limits for evidence projected into monitor continuation prompts. Strict file/none policies still embed no raw output.
monitor.evidence_limits.selected_diagnostics_bytes	integer	8192	—	Maximum UTF-8 bytes of Rust-selected stage diagnostics embedded for failed automatic continuations.
monitor.evidence_limits.fallback_tail_bytes	integer	4096	—	Maximum UTF-8 bytes of fallback raw tail embedded when structured diagnostics are unavailable or insufficient.
monitor.evidence_limits.total_raw_excerpt_bytes	integer	12288	—	Maximum UTF-8 bytes of raw evidence embedded into one continuation prompt.
monitor.evidence_limits.raw_tail_lines	integer	200	—	Maximum retained-output lines considered for raw-tail evidence projections.

pager

Config key	Type	Default	Allowed values	Description
pager	object	{syntax} (values below)	—	Standalone and embedded SASE pager reading-surface policy.
pager.syntax	string	"auto"	"auto", "never"	File-aware syntax highlighting for eligible raw pager sources. auto detects language from filename, trusted Markdown/diff provenance, shebang, or stdin diff. never keeps today's unhighlighted rendering. CLI --syntax overrides this; --color never also disables syntax.

procs

Config key	Type	Default	Allowed values	Description
procs	object	{history_limit, runtime_orphan_horizon_seconds, runtime_orphan_max_removals} (values below)	—	Retention limits for finished proc records and their orphaned runtime directories.
procs.history_limit	integer	100	—	Maximum number of finished procs kept in ~/.sase/procs. Running procs are never pruned. Lower values trim history sooner; the oldest finished procs (and their logs) are removed first.
procs.runtime_orphan_horizon_seconds	integer	259200	—	Age horizon before the hourly proc runtime owner may remove rowless runtime directories. Runtime directories for pruned rows are removed immediately.
procs.runtime_orphan_max_removals	integer	2000	—	Maximum historical rowless proc runtime directories removed in one owner pass.

service

Config key	Type	Default	Allowed values	Description
service	object	{procs} (values below)	—	Machine-level service procs the sase service host starts, restarts, and stops. Project-local sase.yml entries are ignored; the host resolves defaults, plugin, user, and machine-overlay layers only.
service.procs	object	{scheduler, gateway} (values below)	—	Named service proc definitions, keyed by service proc name.
service.procs.<key>	object	not set	—	One service.procs entry. Every layer that declares a field replaces the prior value whole, including lists; only env merges key by key. Plugin-declared and gateway entries default to enabled: false.
service.procs.<key>.description	string	not set	—	Summary line, then a blank line and an optional body. Shown in the Services tab description panel (d expands or collapses it) and sase service proc show.
service.procs.<key>.enabled	boolean	not set	—	Whether the service host starts this proc. Defaults to true, except plugin-declared entries (including the builtin gateway entry), which default to false.
service.procs.<key>.mode	string	"daemon"	"daemon"	Only daemon is configurable here; oneshot service procs are transient-only and created with sase service proc run.
service.procs.<key>.command	string | array	not set	—	Launch command: a non-empty string run through sh -c, or a non-empty list of non-empty strings run as argv directly. Exactly one of command or builtin is required.
service.procs.<key>.command[]	string	not set	—	—
service.procs.<key>.builtin	string	not set	"gateway", "scheduler"	A reserved builtin launcher; must equal the entry's own name. Exactly one of command or builtin is required.
service.procs.<key>.cwd	string	not set	—	Working directory the proc is launched from.
service.procs.<key>.env	object	not set	—	Extra environment variables. Values may reference other captured environment variables with ${NAME}; $$ is a literal $. Expansion happens at launch.
service.procs.<key>.env.<key>	string	not set	—	—
service.procs.<key>.restart	string	"on-failure"	"always", "on-failure", "never"	Restart policy, matching systemd's Restart= semantics.
service.procs.<key>.success_exit_codes	array	[]	—	Additional exit codes treated as a clean exit, like systemd's SuccessExitStatus=. Exit code 0 is always clean.
service.procs.<key>.success_exit_codes[]	integer	not set	—	—
service.procs.<key>.stop_signal	string	"SIGTERM"	—	Signal sent to request a clean stop, with or without the SIG prefix.
service.procs.<key>.stop_timeout	number	10	—	Seconds to wait after stop_signal before escalating to SIGKILL.
service.procs.<key>.after	array	[]	—	Names of other service procs this one starts after. Ordering only; an unknown name warns and is dropped, and a dependency cycle marks every entry on it unavailable.
service.procs.<key>.after[]	string	not set	—	—
service.procs.<key>.log_max_bytes	integer	2097152	—	Maximum bytes kept in this proc's rotated output log.

tasks

Config key	Type	Default	Allowed values	Description
tasks	object	not set	—	Deprecated alias for 'procs'. Still parsed during the compatibility window; prefer 'procs' in new config.
tasks.history_limit	integer	100	—	Deprecated alias for 'procs.history_limit'.

tool_runs

Config key	Type	Default	Allowed values	Description
tool_runs	object	{…} (7 keys; values below)	—	Operational ToolRun ledger retention policy. Uses ordinary config-layer precedence, independent of the project-owned tools catalog.
tool_runs.summary_days	integer	180	—	Days to retain run/attempt/lifecycle summaries after settlement.
tool_runs.detail_days	integer	60	—	Days to retain detailed stage/sample events and projections. Must be <= summary_days.
tool_runs.log_days	integer	14	—	Days to retain output and event files after settlement. Must be <= detail_days.
tool_runs.log_max_bytes	integer	2147483648	—	Aggregate retained log target in bytes (default 2 GiB).
tool_runs.run_log_max_bytes	integer	268435456	—	Per-run retained log cap in bytes (default 256 MiB).
tool_runs.event_max_bytes	integer	16777216	—	Per-run event file cap in bytes (default 16 MiB).
tool_runs.soft_ceiling	object	{default, providers} (values below)	—	The most time an agent should block on one sase tool run before escalating to a monitor; it kills nothing; the effective budget is the smaller of this and the hard ceiling's budget.
tool_runs.soft_ceiling.default	string	""	—	Default soft-ceiling duration (e.g. 90s, 20m, 1h); empty means none.
tool_runs.soft_ceiling.providers	object	{}	—	Per-provider soft-ceiling durations keyed by registered provider name; empty means none.
tool_runs.soft_ceiling.providers.<key>	string	not set	—	—

update

Config key	Type	Default	Allowed values	Description
update	object	{dev_root} (values below)	—	Configuration for SASE self-update and install-mode switching
update.dev_root	string	"~/projects/github"	—	Directory where sase update --to dev materializes editable checkouts.

Related

• Configuration reference — all key families.

_[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.