OpenLogi Configuration File Location: Cross-Platform Path Guide

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 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 (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, the application uses the dirs::config_dir() function to determine the platform-specific base directory before appending the openlogi/config.toml suffix.

// 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) 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 that demonstrates the required sections and data types.

# 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 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, 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 using the dirs crate.
• Reference docs/config.example.toml for the complete schema and 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 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 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 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 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.

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