Skip to content

Workspace configuration behavior

Configuration for workspace directory layout and lifecycle.

workspace

Controls how SASE chooses the physical location of managed workspace checkouts. See docs/reference/agents/workspaces.md for the directory-layout reference and CLI workflows.

workspace:
  root: xdg-state # "xdg-state", "adjacent", or an absolute path
  project_key: "" # explicit project-key override; empty = derive from git remote / primary path
  share_git_objects: true # borrow primary Git objects for numbered managed checkouts
  cleanup_ttl_days: 14 # age threshold for `sase workspace cleanup --stale`
  held_claim_ttl_days: 14 # age threshold for releasing pinned dead workspace claims

Generated reference for workspace

Platform defaults for the xdg-state policy:

Platform Managed root
Linux $XDG_STATE_HOME/sase/workspaces (falls back to ~/.local/state/sase/workspaces)
macOS ~/Library/Application Support/sase/workspaces
Windows %LOCALAPPDATA%\sase\workspaces

Numeric identity is the same on every root policy: #0 is the primary checkout, #1–#9 are reserved, and managed claim workspaces start at #10. See docs/reference/agents/workspaces.md for the full identity model and backup/container/NFS caveats.

For non-adjacent policies, physical checkouts live under <managed-root>/<project_key>/<project>_<num>/. For example, workspace.root: /mnt/sase-workspaces with project key github.com_org_repo places workspace #10 at /mnt/sase-workspaces/github.com_org_repo/<project>_10/. When SASE_WORKSPACE_ROOT is set, it supplies the same <managed-root> base for the process.

Existing adjacent checkouts are not moved automatically by the default. Run sase workspace migrate --to xdg-state to carry existing flat <primary>_<num>/ directories into the managed root, or set workspace.root: adjacent explicitly to keep the old sibling layout.

sase repo open <primary-repo> -w NUM -r "<reason>" is an explicit preparation command for a checkout you plan to use outside a normal sase run launch. It uses the same root policy when it materializes the checkout, backs up uncommitted local changes through the active VCS provider, cleans the checkout, checks out and syncs the provider default parent revision, and prints the resulting path. For manual scratch work, choose a claim-range number such as 10; #0 is the primary checkout and #1 through #9 are reserved compatibility numbers.

Source: src/sase/default_config.yml, src/sase/workspace_provider/store.py

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