> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# XDG Base Directory Paths

> Honour XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, and XDG_CACHE_HOME on fresh installs

Fresh installs place config, data, state, and cache under the standard XDG Base Directories when the matching `XDG_*` variables are set.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start[📁 Resolve path class] --> Home{PRAISONAI_HOME set?}
    Home -->|Yes| Root[🏠 Single root]
    Home -->|No| Legacy{~/.praisonai or ~/.praison exists?}
    Legacy -->|Yes| Root
    Legacy -->|No| Xdg{XDG_*_HOME set?}
    Xdg -->|Yes| XdgApp[📂 $XDG_*_HOME/praisonai]
    Xdg -->|No| Default[⚙️ XDG default dir]

    classDef start fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef check fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef root fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Start start
    class Home,Legacy,Xdg check
    class Root root
    class XdgApp,Default result
```

## Quick Start

<Steps>
  <Step title="Inspect resolved paths">
    Read the resolved directories from Python:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents.paths import get_config_dir, get_data_dir, get_state_dir, get_cache_dir

    print(get_config_dir())  # ~/.config/praisonai on a fresh XDG install
    print(get_data_dir())    # ~/.praisonai (branded default)
    print(get_state_dir())   # ~/.local/state/praisonai
    print(get_cache_dir())   # ~/.cache/praisonai
    ```
  </Step>

  <Step title="Route a class with an XDG variable">
    Set an `XDG_*_HOME` variable to move that class to a mounted volume:

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export XDG_STATE_HOME=/mnt/state
    export XDG_CACHE_HOME=/scratch/cache
    praisonai "Run once"
    # state -> /mnt/state/praisonai, cache -> /scratch/cache/praisonai
    ```
  </Step>
</Steps>

***

## 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  >  existing ~/.praisonai or ~/.praison  >  $XDG_*_HOME/praisonai  >  XDG default
```

An existing single-root install (`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.

| Class  | Helper             | Single-root path | XDG variable      | XDG default                | Notes                                                              |
| ------ | ------------------ | ---------------- | ----------------- | -------------------------- | ------------------------------------------------------------------ |
| Config | `get_config_dir()` | `<root>/`        | `XDG_CONFIG_HOME` | `~/.config/praisonai`      | Editable config, credentials, rules                                |
| Data   | `get_data_dir()`   | `<root>/`        | `XDG_DATA_HOME`   | `~/.praisonai`             | Keeps the branded default unless `XDG_DATA_HOME` is explicitly set |
| State  | `get_state_dir()`  | `<root>/`        | `XDG_STATE_HOME`  | `~/.local/state/praisonai` | MRU model, logs, session spill                                     |
| Cache  | `get_cache_dir()`  | `<root>/cache`   | `XDG_CACHE_HOME`  | `~/.cache/praisonai`       | Disposable data                                                    |

<Note>
  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.
</Note>

Two helpers are new public functions: `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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export XDG_CONFIG_HOME=/data/config
export XDG_DATA_HOME=/data/data
export XDG_STATE_HOME=/data/state
export XDG_CACHE_HOME=/data/cache
```

### Ephemeral state on tmpfs

Keep state fast and disposable while config persists:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export XDG_STATE_HOME=/dev/shm
export XDG_CONFIG_HOME=/etc/praisonai
```

### Read-only config, scratch cache

Serve config from a read-only mount and cache on scratch disk:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export XDG_CONFIG_HOME=/ro/config   # read-only mount
export XDG_CACHE_HOME=/scratch      # writable scratch
```

***

## Migration

<Note>
  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.
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Use XDG_STATE_HOME for disposable state">
    State is machine-local (MRU model, logs, spill). Routing it to tmpfs keeps ephemeral runs clean.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Keep cache on scratch disk">
    Cache is disposable; `XDG_CACHE_HOME` on a scratch volume avoids filling persistent storage.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Storage Paths" icon="folder" href="/docs/concepts/storage-paths">
    Core storage-path concepts and PRAISONAI\_HOME
  </Card>

  <Card title="Config from Env" icon="gear" href="/docs/features/env-config">
    Inject the full CLI config from an environment variable
  </Card>
</CardGroup>