# OpenLogi Configuration File Location on Linux: Complete Path Guide

> Find the OpenLogi configuration file location on Linux. Learn the complete path `~/.config/openlogi/config.toml` for easy access and customization.

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

---

**On Linux, OpenLogi stores its configuration file at `~/.config/openlogi/config.toml` by default, following the XDG Base Directory specification.**

OpenLogi, developed by AprilNEA as an open-source logistics management platform, uses a single TOML configuration file shared between its GUI and background agent. Understanding the exact OpenLogi configuration file location is critical for customizing device mappings, automating deployments, or troubleshooting connectivity issues across development environments.

## Default Configuration Path on Linux

OpenLogi adheres to the **XDG Base Directory specification** on Linux systems. The application resolves the configuration directory using the standard `dirs::config_dir()` Rust library function, which queries the `XDG_CONFIG_HOME` environment variable.

The configuration file resides at:

- **Primary location**: `$XDG_CONFIG_HOME/openlogi/config.toml`
- **Fallback location**: `~/.config/openlogi/config.toml` (when `XDG_CONFIG_HOME` is unset)

This convention ensures compatibility with modern Linux standards and allows administrators to redirect configuration storage by modifying environment variables.

## How OpenLogi Resolves the Config Path

The configuration resolution logic is implemented in [`openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/config.rs). The `config_path()` function constructs the full filesystem path by appending the application directory and filename to the platform-specific configuration base.

```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 application 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 shared logic, ensuring they read from and write to identical filesystem locations.

## Configuration File Structure and Examples

OpenLogi uses **TOML** (Tom's Obvious, Minimal Language) for its configuration format. The repository includes comprehensive documentation and a working template for reference:

- **[`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md)**: Official documentation describing all available configuration options and their default values
- **[`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml)**: A fully populated example file demonstrating proper syntax and structure

Users should copy relevant sections from [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) into their active configuration at `~/.config/openlogi/config.toml` and edit the physical-device keys after the first OpenLogi run.

## Backup Mechanisms and External Edits

The OpenLogi GUI implements **atomic file writes** to prevent configuration corruption during system crashes. When saving changes, the application:

1. Writes new content to a temporary file
2. Renames it to [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) atomically
3. Maintains up to five rolling backup copies: `config.toml.backup.1` through `config.toml.backup.5`

If you modify [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) using an external text editor while the GUI is running, the application detects this change on its next save attempt. To prevent data loss, the GUI rejects the save operation rather than overwriting your external modifications, ensuring the agent and GUI remain synchronized.

## Programmatically Accessing the Config File

For automation scripts or CI/CD pipelines, reference the configuration file using the `XDG_CONFIG_HOME` environment variable with a fallback to the home directory:

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

# Display the current OpenLogi configuration (Linux/macOS)

CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/openlogi/config.toml"

if [[ -f "$CONFIG" ]]; then
    echo "OpenLogi configuration found at: $CONFIG"
    cat "$CONFIG"
else
    echo "Configuration file not found at $CONFIG"
    exit 1
fi

```

This approach ensures your scripts remain portable across different Linux distributions and respect user-specific configuration overrides.

## Summary

- **OpenLogi configuration file location** on Linux follows the XDG specification at `~/.config/openlogi/config.toml` (or `$XDG_CONFIG_HOME/openlogi/config.toml`)
- The path resolution logic lives in [`openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/config.rs) and uses the `dirs::config_dir()` crate
- Configuration uses **TOML format** with documentation available in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) and examples in [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml)
- The GUI maintains **automatic backups** (up to five versions) and writes changes atomically to prevent corruption
- Both the GUI and background agent share the same configuration file path, ensuring consistent settings across components

## Frequently Asked Questions

### Where does OpenLogi store its config file on macOS?

On macOS, OpenLogi uses the same XDG Base Directory fallback, storing the file at `~/.config/openlogi/config.toml`. While macOS typically stores application data in `~/Library/Application Support/`, the project explicitly follows XDG conventions for consistency across Unix-like platforms.

### What happens if I delete the OpenLogi configuration file?

If you delete [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml), OpenLogi regenerates a default configuration upon the next application startup. However, you will lose any custom device mappings, API keys, or GUI preferences. The application maintains up to five rolling backups (`config.toml.backup.1` through `config.toml.backup.5`) in the same directory that you can restore if needed.

### Can I change the OpenLogi configuration directory location?

Yes. Since OpenLogi respects the `XDG_CONFIG_HOME` environment variable, you can relocate the configuration by setting this variable before launching the application. For example: `XDG_CONFIG_HOME=/opt/openlogi/config ./openlogi`. The application will then look for [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) at [`/opt/openlogi/config/openlogi/config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main//opt/openlogi/config/openlogi/config.toml).

### Is it safe to manually edit the configuration while the OpenLogi agent is running?

Manual editing is supported but requires caution. The GUI monitors the file for external changes and refuses to save its own changes if it detects external modifications, preventing accidental overwrites. The background agent typically loads configuration settings at startup, so changes made while the agent is running usually require a restart to take effect.