Where Are OpenLogi Configuration Files Stored on macOS, Linux, and Windows?

OpenLogi stores its configuration files in XDG-compliant directories under ~/.config/openlogi on Linux, macOS, and Windows, explicitly ignoring native platform conventions like macOS ~/Library/Application Support or Windows %APPDATA%.

The AprilNEA/OpenLogi repository implements a strict cross-platform path resolution system that adheres to the XDG Base Directory specification across all operating systems. Whether you are troubleshooting settings, backing up configurations, or developing plugins, understanding the exact file locations requires examining the openlogi_core::paths module.

XDG Base Directory Specification on Every Platform

Unlike typical desktop applications that use platform-native directories, OpenLogi enforces XDG compliance universally. The path resolution logic lives in crates/openlogi-core/src/paths.rs, which implements helper functions that check for standard XDG environment variables before falling back to hardcoded defaults. This approach ensures consistent behavior whether you are running the application on Linux, macOS, or Windows.

The system distinguishes three primary directory types:

• Config: Resolved via XDG_CONFIG_HOME, defaulting to ~/.config/openlogi
• Data: Resolved via XDG_DATA_HOME, defaulting to ~/.local/share/openlogi
• State: Resolved via XDG_STATE_HOME, defaulting to ~/.local/state/openlogi

Platform-Specific File Locations

Linux and Unix Systems

On Linux and other Unix-like operating systems, OpenLogi uses the XDG defaults directly. The main configuration file config.toml resides at ~/.config/openlogi/config.toml. Runtime state files, including the Unix domain socket for IPC, are stored according to the standard without modification.

macOS

On macOS, OpenLogi does not store files in ~/Library/Application Support. Instead, it maintains the same XDG layout used on Linux, placing configuration files at ~/.config/openlogi. When running a local development build with OPENLOGI_PROFILE=dev set, the directory shifts to ~/.config/openlogi-dev to prevent conflicts with the installed application.

Windows

On Windows, the openlogi_core::paths module resolves the home directory from %USERPROFILE%, resulting in paths such as %USERPROFILE%\.config\openlogi. OpenLogi does not consult the Windows-specific %APPDATA% directory. This XDG-centric approach applies to all three directory types (config, data, and state).

The Dev Profile Override

OpenLogi supports a development profile that appends a -dev suffix to directory names. This profile activates when the environment variable OPENLOGI_PROFILE=dev is present or when the running bundle identifier matches a development build. This mechanism, implemented in crates/openlogi-core/src/paths.rs, allows developers to test configurations without corrupting their production settings.

Accessing Paths Programmatically

You can resolve these directories programmatically using the openlogi_core::paths module. The following examples demonstrate how to locate the configuration, data, and state directories in Rust:

use openlogi_core::paths;

/// Resolve the directory that stores the main `config.toml`.
let config_path = paths::config_dir()
    .expect("could not resolve config directory")
    .join("config.toml");

// Example: read the configuration file
let toml = std::fs::read_to_string(&config_path)
    .expect("failed to read OpenLogi configuration");
println!("OpenLogi config at {}:\n{}", config_path.display(), toml);

use openlogi_core::paths;

/// Resolve the data directory (e.g., for cached assets)
let data_dir = paths::data_dir()
    .expect("could not resolve data directory");
println!("OpenLogi data dir: {}", data_dir.display());

use openlogi_core::paths;

/// Resolve the state directory (e.g., for runtime lock files)
let state_dir = paths::state_dir()
    .expect("could not resolve state directory");
println!("OpenLogi state dir: {}", state_dir.display());

The configuration file loader in crates/openlogi-core/src/config/file.rs utilizes these helpers to locate and parse config.toml, while crates/openlogi-ipc/src/transport.rs establishes the Unix domain socket at ~/.config/openlogi/agent.sock.

Summary

• Cross-platform XDG compliance: OpenLogi uses ~/.config/openlogi on Linux, macOS, and Windows, as implemented in crates/openlogi-core/src/paths.rs.
• No native directories: The application ignores macOS ~/Library and Windows %APPDATA% in favor of XDG paths.
• Environment overrides: Set XDG_CONFIG_HOME, XDG_DATA_HOME, or XDG_STATE_HOME to relocate directories.
• Dev profile: Use OPENLOGI_PROFILE=dev to switch to openlogi-dev prefixed directories during development.
• Programmatic access: Use paths::config_dir(), paths::data_dir(), and paths::state_dir() to resolve locations at runtime.

Frequently Asked Questions

Does OpenLogi use native macOS directory conventions?

No. According to the source code in crates/openlogi-core/src/paths.rs, OpenLogi explicitly uses XDG-compliant paths under ~/.config/openlogi rather than the standard macOS ~/Library/Application Support location. This applies to both release and development builds.

How can I change where OpenLogi stores its configuration files?

Set the XDG_CONFIG_HOME environment variable to your desired base directory. OpenLogi will resolve the configuration path relative to this variable, defaulting to ~/.config if unspecified. The same applies to XDG_DATA_HOME and XDG_STATE_HOME for data and state files respectively.

What is the purpose of the -dev suffix in some directory paths?

The dev profile (openlogi-dev) prevents local development builds from interfering with your production configuration. When OPENLOGI_PROFILE=dev is set or the bundle identifier indicates a development build, OpenLogi appends -dev to the application name in all path resolutions, isolating settings and cached data.

Where does OpenLogi create its IPC socket for agent communication?

The Unix domain socket is created at ~/.config/openlogi/agent.sock (or ~/.config/openlogi-dev/agent.sock when using the dev profile). This location is hardcoded relative to the configuration directory in crates/openlogi-ipc/src/transport.rs.

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