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

> Find where OpenLogi stores its TOML configuration on macOS, Linux, and Windows. Discover the `~/.config/openlogi/config.toml` location and understand XDG Base Directory usage.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```bash

# 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/main/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:

```rust
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:

```rust
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/main/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/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.