llama-stack-mirror/docs/source/getting_started/xdg_compliance.md

XDG Base Directory Specification Compliance

Starting with version 0.2.14, Llama Stack follows the XDG Base Directory Specification for organizing configuration and data files. This provides better integration with modern desktop environments and allows for more flexible customization of where files are stored.

Overview

The XDG Base Directory Specification defines standard locations for different types of application data:

• Configuration files (XDG_CONFIG_HOME): User-specific configuration files
• Data files (XDG_DATA_HOME): User-specific data files that should persist
• Cache files (XDG_CACHE_HOME): User-specific cache files
• State files (XDG_STATE_HOME): User-specific state files

Directory Mapping

Llama Stack now uses the following XDG-compliant directory structure:

Data Type	XDG Directory	Default Location	Description
Configuration	XDG_CONFIG_HOME	~/.config/llama-stack	Distribution configs, provider configs
Data	XDG_DATA_HOME	~/.local/share/llama-stack	Model checkpoints, persistent files
Cache	XDG_CACHE_HOME	~/.cache/llama-stack	Temporary cache files
State	XDG_STATE_HOME	~/.local/state/llama-stack	Runtime state, databases

Environment Variables

You can customize the locations by setting these environment variables:

# Override the base directories
export XDG_CONFIG_HOME="/custom/config/path"
export XDG_DATA_HOME="/custom/data/path"
export XDG_CACHE_HOME="/custom/cache/path"
export XDG_STATE_HOME="/custom/state/path"

# Or override specific Llama Stack directories
export SQLITE_STORE_DIR="/custom/database/path"
export FILES_STORAGE_DIR="/custom/files/path"

Backwards Compatibility

Llama Stack maintains full backwards compatibility with existing installations:

1. Legacy Environment Variable: If LLAMA_STACK_CONFIG_DIR is set, it will be used for all directories
2. Legacy Directory Detection: If ~/.llama exists and contains data, it will continue to be used
3. Gradual Migration: New installations use XDG paths, existing installations continue to work

Migration Guide

Automatic Migration

Use the built-in migration command to move from legacy ~/.llama to XDG-compliant directories:

# Preview what would be migrated
llama migrate-xdg --dry-run

# Perform the migration
llama migrate-xdg

Manual Migration

If you prefer to migrate manually, here's the mapping:

# Create XDG directories
mkdir -p ~/.config/llama-stack
mkdir -p ~/.local/share/llama-stack
mkdir -p ~/.local/state/llama-stack

# Move configuration files
mv ~/.llama/distributions ~/.config/llama-stack/
mv ~/.llama/providers.d ~/.config/llama-stack/

# Move data files
mv ~/.llama/checkpoints ~/.local/share/llama-stack/

# Move state files
mv ~/.llama/runtime ~/.local/state/llama-stack/

# Clean up empty legacy directory
rmdir ~/.llama

Environment Variables in Configurations

Template configurations now use XDG-compliant environment variables:

# Old format
db_path: ${env.SQLITE_STORE_DIR:=~/.llama/distributions/ollama}/registry.db

# New format
db_path: ${env.SQLITE_STORE_DIR:=${env.XDG_STATE_HOME:-~/.local/state}/llama-stack/distributions/ollama}/registry.db

Configuration Examples

Using Custom XDG Directories

# Set custom XDG directories
export XDG_CONFIG_HOME="/opt/llama-stack/config"
export XDG_DATA_HOME="/opt/llama-stack/data"
export XDG_STATE_HOME="/opt/llama-stack/state"

# Start Llama Stack
llama stack run my-distribution.yaml

Using Legacy Directory

# Continue using legacy directory
export LLAMA_STACK_CONFIG_DIR="/home/user/.llama"

# Start Llama Stack
llama stack run my-distribution.yaml

Custom Database and File Locations

# Override specific directories
export SQLITE_STORE_DIR="/fast/ssd/llama-stack/databases"
export FILES_STORAGE_DIR="/large/disk/llama-stack/files"

# Start Llama Stack
llama stack run my-distribution.yaml

Benefits of XDG Compliance

1. Standards Compliance: Follows established Linux/Unix conventions
2. Better Organization: Separates configuration, data, cache, and state files
3. Flexibility: Easy to customize storage locations
4. Backup-Friendly: Easier to backup just data files or just configuration
5. Multi-User Support: Better support for shared systems
6. Cross-Platform: Works consistently across different environments

Template Updates

All distribution templates have been updated to use XDG-compliant paths:

• Database files use XDG_STATE_HOME
• Model checkpoints use XDG_DATA_HOME
• Configuration files use XDG_CONFIG_HOME
• Cache files use XDG_CACHE_HOME

Troubleshooting

Migration Issues

If you encounter issues during migration:

1. Check Permissions: Ensure you have write permissions to target directories
2. Disk Space: Verify sufficient disk space in target locations
3. Existing Files: Handle conflicts with existing files in target locations

Environment Variable Conflicts

If you have multiple environment variables set:

1. LLAMA_STACK_CONFIG_DIR takes highest precedence
2. Individual XDG_* variables override defaults
3. Fallback to legacy ~/.llama if it exists
4. Default to XDG standard paths for new installations

Debugging Path Resolution

To see which paths Llama Stack is using:

from llama_stack.distribution.utils.xdg_utils import (
    get_llama_stack_config_dir,
    get_llama_stack_data_dir,
    get_llama_stack_state_dir,
)

print(f"Config: {get_llama_stack_config_dir()}")
print(f"Data: {get_llama_stack_data_dir()}")
print(f"State: {get_llama_stack_state_dir()}")

Future Considerations

• Container deployments will continue to use /app or similar paths
• Cloud deployments may use provider-specific storage systems
• The XDG specification primarily applies to local development and single-user systems