Where OpenLogi Stores Its TOML Configuration on macOS, Linux, and Windows

OpenLogi stores its TOML configuration at ~/.config/openlogi/config.toml on all platforms, using XDG Base Directory semantics even on macOS and Windows.

The OpenLogi project follows a cross-platform approach to configuration management that prioritizes consistency over native OS conventions. Rather than using macOS's ~/Library/Application Support or Windows's %APPDATA%, it enforces XDG Base Directory specification everywhere. This design choice simplifies documentation and troubleshooting across environments.

How OpenLogi Resolves the Configuration Path

The configuration location is determined by the openlogi_core::paths module, specifically the config_path() function. This helper encapsulates all platform-specific logic and returns the absolute path to config.toml.

The resolution follows this hierarchy:

1. Check $XDG_CONFIG_HOME environment variable
2. Fall back to $HOME/.config (Linux, macOS)
3. Fall back to %USERPROFILE%\.config (Windows)

On macOS, notably, OpenLogi does not use the conventional ~/Library/Application Support directory. This is an intentional departure from Apple's guidelines to maintain parity with Linux deployments.

Development builds receive special treatment: when compiled with the dev profile on macOS, the directory suffix changes from openlogi to openlogi-dev. This prevents accidental configuration contamination between production and development environments.

Platform-Specific Configuration Paths

Linux

Variable	Default	Full path
$XDG_CONFIG_HOME	~/.config	~/.config/openlogi/config.toml

Linux behaves as expected per XDG standards. Most distributions already set XDG_CONFIG_HOME, but OpenLogi handles its absence gracefully.

macOS

Variable	Default	Full path
$XDG_CONFIG_HOME	~/.config	~/.config/openlogi/config.toml

Important: macOS users accustomed to ~/Library/Application Support will find OpenLogi's configuration in the hidden ~/.config directory instead. The same path applies regardless of Intel or Apple Silicon architecture.

For local development builds:

# Development configuration location

~/.config/openlogi-dev/config.toml

Windows

Variable	Resolution	Full path
%USERPROFILE% → $HOME	C:\Users\<username>	%USERPROFILE%\.config\openlogi\config.toml

Windows uses the user's home directory as the base, appending .config to match XDG conventions. The result is a Unix-style path within the Windows filesystem hierarchy.

Accessing Configuration Paths Programmatically

The [crates/openlogi-core/src/paths.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/paths.rs) file implements the directory resolution logic. Use these utilities in your own OpenLogi-based code:

use openlogi_core::paths;

/// Returns the full path to config.toml
fn get_config_path() -> std::path::PathBuf {
    paths::config_path().expect("Failed to resolve config directory")
}

/// Read the configuration file contents
fn load_config_string() -> std::io::Result<String> {
    std::fs::read_to_string(get_config_path())
}

For debugging or logging purposes, inspect the directory structure:

fn inspect_paths() {
    let config_dir = paths::config_dir()
        .expect("Failed to get config directory");
    let config_file = paths::config_path()
        .expect("Failed to get config path");
    
    println!("Config directory: {}", config_dir.display());
    println!("Config file: {}", config_file.display());
    
    // Also available: runtime directory for agent.sock
    let runtime = paths::runtime_dir()
        .expect("Failed to get runtime directory");
    println!("Runtime socket: {}/agent.sock", runtime.display());
}

The paths module also provides data_dir() and state_dir() for persistent storage needs, following identical XDG-based resolution rules.

Configuration File Structure

The TOML file at the resolved path must conform to the schema defined in [crates/openlogi-core/src/config.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config.rs). Reference [docs/config.example.toml](https://github.com/AprilNEA/OpenLogi/blob/master/docs/config.example.toml) for the complete structure and available options.

OpenLogi automatically creates the directory structure on first run if it does not exist, but will not generate a default configuration file—you must supply the initial config.toml.

Summary

• OpenLogi configuration location is ~/.config/openlogi/config.toml on all platforms
• XDG Base Directory specification applies universally, including macOS and Windows
• Path resolution is handled by openlogi_core::paths::config_path() in crates/openlogi-core/src/paths.rs
• macOS development builds use openlogi-dev instead of openlogi as the directory name
• Windows paths resolve to %USERPROFILE%\.config\openlogi\config.toml

Frequently Asked Questions

Does OpenLogi follow macOS conventions and use ~/Library/Application Support?

No. According to the OpenLogi source code in crates/openlogi-core/src/paths.rs, macOS uses ~/.config/openlogi/config.toml just like Linux. This XDG-first approach ensures configuration files remain portable and discoverable across all supported platforms.

How do I find where my OpenLogi configuration is stored without checking manually?

Import openlogi_core::paths and call paths::config_path(), which returns a PathBuf to the resolved location. This handles environment variable detection and platform-specific fallback logic automatically.

What happens if XDG_CONFIG_HOME is not set?

OpenLogi falls back to $HOME/.config on Unix-like systems and %USERPROFILE%\.config on Windows. The paths.rs implementation guarantees a valid directory through the dirs crate's cross-platform abstractions.

Can I change the configuration directory at runtime?

No. The path is resolved at compile time through the config_path() helper and cannot be overridden via command-line flags or runtime environment changes after initialization. Set XDG_CONFIG_HOME before launching OpenLogi to affect its behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}