OpenLogi Configuration File Location on Linux: Complete Path Guide

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. The config_path() function constructs the full filesystem path by appending the application directory and filename to the platform-specific configuration base.

// 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) 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: Official documentation describing all available configuration options and their default values
• docs/config.example.toml: A fully populated example file demonstrating proper syntax and structure

Users should copy relevant sections from 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 atomically
3. Maintains up to five rolling backup copies: config.toml.backup.1 through config.toml.backup.5

If you modify 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:

#!/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 and uses the dirs::config_dir() crate
• Configuration uses TOML format with documentation available in docs/CONFIGURATION.md and examples in 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, 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 at /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.

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