XDG_* variables are set.
Quick Start
1
Inspect resolved paths
Read the resolved directories from Python:
2
Route a class with an XDG variable
Set an
XDG_*_HOME variable to move that class to a mounted volume:How It Works
Each path class shares one precedence chain: an explicit single root wins, then legacy detection, then the XDG variable, then the XDG default.PRAISONAI_HOME set, or ~/.praisonai/ present) keeps every class together for full backward compatibility. XDG behaviour only applies to fresh installs.
Path Classes
Each class has its own helper, single-root path, XDG variable, and default.The data class is the exception: it stays at the branded
~/.praisonai default unless XDG_DATA_HOME is explicitly set. This prevents branded installs from silently moving. Config, state, and cache follow their XDG defaults on fresh installs.get_config_dir() and get_state_dir(). Session spill routes to the state home via get_session_spill_dir(), and get_config_path() resolves <config>/config.yaml.
Common Patterns
Server with volume mounts
Point each class at a persistent volume:Ephemeral state on tmpfs
Keep state fast and disposable while config persists:Read-only config, scratch cache
Serve config from a read-only mount and cache on scratch disk:Migration
Existing installs are unchanged. If
~/.praisonai/ is present or PRAISONAI_HOME is set, every class stays under that single root. XDG behaviour only activates for fresh installs with XDG_* variables set.Best Practices
Set PRAISONAI_HOME for a single-root layout
Set PRAISONAI_HOME for a single-root layout
When you want everything in one place,
PRAISONAI_HOME overrides all XDG resolution and keeps classes together.Use XDG_STATE_HOME for disposable state
Use XDG_STATE_HOME for disposable state
State is machine-local (MRU model, logs, spill). Routing it to tmpfs keeps ephemeral runs clean.
Set XDG_DATA_HOME explicitly on servers
Set XDG_DATA_HOME explicitly on servers
Data keeps the branded default unless
XDG_DATA_HOME is set — point it at a persistent volume in containers.Keep cache on scratch disk
Keep cache on scratch disk
Cache is disposable;
XDG_CACHE_HOME on a scratch volume avoids filling persistent storage.Related
Storage Paths
Core storage-path concepts and PRAISONAI_HOME
Config from Env
Inject the full CLI config from an environment variable