# OpenLogi Configuration File Location: Cross-Platform Path Guide

> Find the OpenLogi configuration file easily. Learn the cross-platform path for macOS, Linux, and Windows to manage your settings efficiently.

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

---

**OpenLogi stores its settings in a TOML file located at `$XDG_CONFIG_HOME/openlogi/config.toml` on macOS and Linux (defaulting to `~/.config/openlogi/config.toml`) and `%USERPROFILE%\.config\openlogi\config.toml` on Windows, following the XDG Base Directory specification.**

OpenLogi is an open-source logistics management tool written in Rust. Both its graphical interface and background agent read from the same configuration file, ensuring consistent settings across the application stack. Locating this file is essential for manual troubleshooting, automated deployments, or backing up physical device keys.

## Default OpenLogi Configuration File Paths by Platform

OpenLogi follows the XDG Base Directory specification on Unix-like systems and mirrors that structure on Windows. The configuration is stored in a plain-text **TOML** file named [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) inside an `openlogi` subdirectory of the user's configuration folder.

### macOS and Linux (XDG Base Directory)

On macOS and Linux, OpenLogi respects the `XDG_CONFIG_HOME` environment variable. If unset, it defaults to the standard `~/.config` directory.

- **Full path:** `$XDG_CONFIG_HOME/openlogi/config.toml`
- **Default fallback:** `~/.config/openlogi/config.toml`

This location is explicitly documented in the project's configuration guide at [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) (lines 5-8).

### Windows (User Profile Directory)

On Windows, OpenLogi places the configuration folder within the user's profile directory to maintain consistency with the XDG structure.

- **Full path:** `%USERPROFILE%\.config\openlogi\config.toml`

This typically resolves to a path like `C:\Users\Username\.config\openlogi\config.toml`.

## How OpenLogi Locates the Config File at Runtime

The configuration path resolution is implemented 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 application uses the `dirs::config_dir()` function to determine the platform-specific base directory before appending the [`openlogi/config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi/config.toml) suffix.

```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
}

```

Both the GUI and the background agent ([`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs)) invoke this same logic during startup, ensuring they reference identical settings.

## Configuration File Format and Example

OpenLogi uses the **TOML** format for human-readable key-value configuration. The repository includes a fully documented example file at [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) that demonstrates the required sections and data types.

```toml

# Example structure from docs/config.example.toml

[general]
log_level = "info"

[device]

# Physical device keys are populated after first run

id = "your-device-id"
key = "your-secure-key"

```

After the first run, physical device keys are automatically appended to the file. The official documentation in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) details every supported option and its validation rules.

## File Safety and Backup Behavior

The OpenLogi GUI implements **atomic write operations** to prevent configuration corruption. When saving changes, the application writes to a temporary file before renaming it to [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml), ensuring that the existing configuration is never in a partially written state.

The system maintains **up to five automatic backups** in the same directory:
- `config.toml.backup.1`
- `config.toml.backup.2`
- `config.toml.backup.3`
- `config.toml.backup.4`
- `config.toml.backup.5`

If you edit the file externally while the GUI is running, the application detects the modification timestamp change and rejects the next save attempt from the GUI. This prevents the GUI from overwriting external changes and ensures the background agent remains synchronized with the latest configuration.

## Summary

- OpenLogi uses a single **TOML** configuration file shared between the GUI and the agent.
- On **macOS/Linux**, the file is at `$XDG_CONFIG_HOME/openlogi/config.toml` (defaulting to `~/.config/openlogi/config.toml`).
- On **Windows**, the file is at `%USERPROFILE%\.config\openlogi\config.toml`.
- The path resolution logic resides in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) using the `dirs` crate.
- Reference [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) for the complete schema and [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) for usage instructions.
- The GUI maintains **five rolling backups** and uses atomic writes to protect data integrity.

## Frequently Asked Questions

### What format does the OpenLogi configuration file use?

OpenLogi uses **TOML** (Tom's Obvious, Minimal Language) for its configuration files. This format was chosen for its human-readable syntax and robust support in the Rust ecosystem. The example at [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) demonstrates the proper structure for device authentication keys, logging levels, and connection parameters.

### How do I reset OpenLogi to default settings?

To reset OpenLogi, delete or rename the [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) file in your platform-specific configuration directory. The application will generate a fresh configuration with default values on the next startup. Alternatively, restore one of the automatic backups (`config.toml.backup.1` through `config.toml.backup.5`) if you need to revert to a previous working state.

### Can I move the OpenLogi configuration file to a different location?

No, OpenLogi does not currently support custom configuration paths through environment variables or command-line flags. The path is hardcoded in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) to strictly follow the XDG specification (or the Windows equivalent). To use a custom location, you must create a symbolic link from the expected path to your preferred storage location.

### Why does the GUI refuse to save after I edited the file manually?

OpenLogi tracks the file modification time to prevent synchronization conflicts between the GUI and external editors. If [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) is modified externally while the GUI is running, the application detects the timestamp change and rejects subsequent save operations from the interface. This safety mechanism prevents the background agent from receiving stale configuration data. To resolve this, restart the GUI after making external edits.