# Where Is the OpenLogi Configuration File Located on macOS?

> Find the OpenLogi configuration file on macOS at ~/.config/openlogi/config.toml. Learn where OpenLogi stores its settings on your Mac.

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

---

**On macOS, OpenLogi stores its settings in `~/.config/openlogi/config.toml`, following the XDG Base Directory Specification.**

OpenLogi uses a plain TOML file to persist settings that are shared between the graphical interface and the background agent. Understanding the exact **OpenLogi configuration file location on macOS** is essential for manual edits, backups, or troubleshooting sync issues between the GUI and the agent.

## Default Configuration Path on macOS

The application adheres to the **XDG Base Directory Specification** on macOS and Linux systems. By default, the configuration file resides at:

```text
~/.config/openlogi/config.toml

```

If you have set a custom `XDG_CONFIG_HOME` environment variable, OpenLogi will resolve the path as `$XDG_CONFIG_HOME/openlogi/config.toml` instead. This behavior is documented in the project's configuration guide at [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md)【/cache/repos/github.com/AprilNEA/OpenLogi/master/docs/CONFIGURATION.md#L5-L8】.

Both the GUI and the background agent read from this single source of truth, ensuring that device keys and preferences remain synchronized across the application.

## How OpenLogi Resolves the Config Path

Under the hood, the path resolution logic lives in the core library. In [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs), the `config_path()` function determines the platform-specific location using the `dirs` crate:

```rust
// openlogi-core/src/config.rs (simplified)
use std::path::PathBuf;
use dirs::config_dir;

/// Returns the full path to OpenLogi's config file for the current platform.
fn config_path() -> PathBuf {
    let mut base = config_dir().expect("Unable to locate config directory");
    base.push("openlogi");
    base.push("config.toml");
    base
}

```

This implementation guarantees that the agent and GUI load the identical file regardless of how the application is launched.

## Working with the Configuration File

### Reading the Config via Terminal

You can inspect your current settings without opening the GUI by running:

```bash
#!/usr/bin/env bash

# Show the current OpenLogi config (macOS/Linux)

CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/openlogi/config.toml"
if [[ -f "$CONFIG" ]]; then
    cat "$CONFIG"
else
    echo "Config file not found at $CONFIG"
fi

```

### Editing and Backup Behavior

When the GUI saves changes, it performs **atomic writes** to prevent corruption and maintains up to five rolling backups named `config.toml.backup.1` through `config.toml.backup.5`. If you edit the file externally while the GUI is running, the application detects the modification and rejects the next GUI save to prevent overwriting your manual changes.

### Starting from a Template

New users should reference the example configuration shipped with the repository at [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml)【/cache/repos/github.com/AprilNEA/OpenLogi/master/docs/config.example.toml】. Copy relevant sections from this template into your active `~/.config/openlogi/config.toml` and edit the physical-device keys after your first run.

## Cross-Platform Path Differences

While macOS uses the XDG-compliant path, OpenLogi adapts to each platform's conventions:

- **macOS/Linux**: `~/.config/openlogi/config.toml` (or `$XDG_CONFIG_HOME/openlogi/config.toml`)
- **Windows**: `%USERPROFILE%\.config\openlogi\config.toml`

## Summary

- OpenLogi stores macOS settings in **`~/.config/openlogi/config.toml`** by default.
- The path resolution is handled by the **`config_path()`** function in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs).
- Both the GUI and agent share this single TOML file to stay synchronized.
- The GUI creates up to five backup copies automatically and writes changes atomically.
- Use **[`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml)** as a starting template for new configurations.

## Frequently Asked Questions

### What if the `~/.config/openlogi/` directory does not exist?

OpenLogi creates the directory structure automatically on first launch. If you are manually creating the file, ensure the parent directories exist using `mkdir -p ~/.config/openlogi/` before placing your [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) inside.

### Can I change the configuration file location on macOS?

Yes, by setting the `XDG_CONFIG_HOME` environment variable to a custom directory before launching OpenLogi. The application will resolve the config path to `$XDG_CONFIG_HOME/openlogi/config.toml` instead of the default.

### Why did my manual edits disappear after using the GUI?

The GUI detects external file modifications and will refuse to save if the file changed on disk since it was last loaded. To avoid conflicts, close the GUI before editing [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) with a text editor, or reload the GUI after saving your manual changes.

### Where can I find an example configuration file to customize?

The repository includes a fully documented example at [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml). According to the AprilNEA/OpenLogi source code, you should copy sections from this file into your active config located at `~/.config/openlogi/config.toml` and customize the device keys for your specific hardware setup.