# Where OpenLogi Settings Are Stored: XDG Config Path and TOML Format Explained

> Discover where OpenLogi settings are stored at the XDG config path in a TOML format. Learn about Serde serialization and Rust structs for OpenLogi configuration.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: deep-dive
- Published: 2026-09-01

---

**OpenLogi stores all user settings in a single TOML file at `$XDG_CONFIG_HOME/openlogi/config.toml`, using Serde for serialization and strongly-typed Rust structs defined in the core crate.**

Understanding where OpenLogi persists its configuration helps you back up preferences, automate deployments, or debug issues. The application follows the XDG Base Directory specification for cross-platform consistency, with all settings contained in a human-readable TOML file that can be edited directly or manipulated programmatically.

## OpenLogi Configuration File Location

The configuration path is resolved at runtime by `openlogi_core::paths::config_path()` in [`crates/openlogi-core/src/paths.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/paths.rs). This function expands to:

```bash
$XDG_CONFIG_HOME/openlogi/config.toml

```

With platform-specific defaults:

- **Linux/macOS/Windows**: Defaults to `~/.config/openlogi/config.toml`
- **macOS development builds**: Uses `openlogi-dev` subdirectory to isolate test configurations

The `config_dir()` helper (lines 37-47 of [`paths.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/paths.rs)) determines the base XDG directory and appends the application-specific folder. This implementation ensures OpenLogi configuration location behaves predictably across operating systems without hardcoded paths.

## TOML Format and Data Structures

OpenLogi uses **TOML** as its configuration format, parsed with Serde's TOML deserializer. All settings structs are defined in [`crates/openlogi-core/src/config/settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/settings.rs) and implement both `Serialize` and `Deserialize`.

Key configuration structs include:

- **`AppSettings`** — Root struct containing all persisted preferences
- **`Appearance`** — Theme and visual customization options
- **`UiScale`** — Display scaling factor

Every field uses `#[serde(default)]`, allowing the application to add new options without breaking existing configuration files. Omitted keys automatically receive their default values on deserialization.

## Loading and Modifying Configuration Programmatically

You can read and write OpenLogi settings using the core crate's public API:

```rust
use openlogi_core::paths;
use openlogi_core::config::AppSettings;
use std::fs;

// Load the configuration file
let cfg_path = paths::config_path().expect("cannot locate config file");
let toml_str = fs::read_to_string(cfg_path).expect("cannot read config.toml");

// Deserialize into the strongly-typed struct
let settings: AppSettings = toml::from_str(&toml_str).expect("invalid TOML");

// Inspect a value
println!("Launch at login? {}", settings.launch_at_login);

// Modify and write back
let mut new = settings.clone();
new.launch_at_login = false;
let new_toml = toml::to_string_pretty(&new).unwrap();
fs::write(paths::config_path().unwrap(), new_toml).unwrap();

```

The `toml::to_string_pretty()` call preserves comments and formatting conventions, making the output suitable for direct user editing.

## Configuration Reload Behavior

Both the agent and GUI components reload settings through `reload_config` calls found in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs). This uses the same `paths::config_path()` resolution, ensuring consistent behavior whether configuration changes originate from file edits or in-application preference dialogs.

When the user clicks "Apply" in the UI, the application:

1. Serializes current in-memory state to TOML
2. Writes to the resolved config path
3. Notifies other components to reload

Unknown fields in the TOML file are rejected during deserialization, catching typos and preventing silent misconfiguration.

## Summary

- **Location**: `$XDG_CONFIG_HOME/openlogi/config.toml` (default `~/.config/openlogi/config.toml`)
- **Format**: Plain TOML, human-readable and editable
- **Implementation**: `config_path()` in [`crates/openlogi-core/src/paths.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/paths.rs), structs in [`crates/openlogi-core/src/config/settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/settings.rs)
- **Serialization**: Serde with `#[serde(default)]` for backward compatibility
- **Reload**: Triggered on startup or UI apply via [`ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/ipc.rs)

## Frequently Asked Questions

### Can I edit OpenLogi settings without using the GUI?

Yes. Because OpenLogi uses plain TOML, you can edit [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) directly with any text editor. Changes take effect on the next application start or when you trigger a configuration reload through the UI.

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

OpenLogi recreates the file with default values on next startup. All `#[serde(default)]` fields ensure the application functions normally even with missing or empty configuration.

### Does OpenLogi support environment variable overrides for settings?

No. The current implementation reads exclusively from the TOML file at the XDG path. Environment-based configuration would require modification to the loading logic in [`settings.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/settings.rs) or [`ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/ipc.rs).

### How do I migrate settings between machines?

Copy [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) from the source machine's `~/.config/openlogi/` directory to the same location on the destination. The format is portable across all platforms OpenLogi supports.