# OpenLogi Configuration File Structure: A Complete Guide to TOML Settings

> Understand the OpenLogi configuration file structure using TOML settings. Learn about global app settings, device configs, and button bindings in this comprehensive guide.

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

---

**OpenLogi stores all user settings in a plain TOML file located at `~/.config/openlogi/config.toml` on Unix systems or `%USERPROFILE%\.config\openlogi\config.toml` on Windows, using a strict `schema_version` 7 format that supports global app settings, per-device configurations, and button bindings.**

The AprilNEA/OpenLogi repository uses a single configuration file as the source of truth for both the graphical interface and the background agent. This TOML-based approach ensures consistent behavior across platforms while allowing deep customization of input devices through human-readable syntax.

## Configuration File Location and Format

OpenLogi follows the XDG Base Directory Specification on Unix-like systems while providing an equivalent path on Windows.

### Cross-Platform Paths

According to [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md), the configuration file resides in:
- **macOS / Linux**: `$XDG_CONFIG_HOME/openlogi/config.toml` (typically `~/.config/openlogi/config.toml`)
- **Windows**: `%USERPROFILE%\.config\openlogi\config.toml`

The same file is read by the GUI and the background agent, ensuring synchronized settings across both components.

### Atomic Writes and Recovery Behavior

The application writes configuration changes atomically and maintains up to five rolling backups named `config.toml.backup.1` through `config.toml.backup.5`. If the TOML contains misspelled keys or out-of-range values, the parser in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) aborts loading and places the GUI into read-only mode until the user fixes the error.

## Top-Level Structure and Required Keys

Every valid OpenLogi configuration file must declare a `schema_version` and typically includes a `selected_device` identifier.

The mandatory top-level structure includes:

```toml
schema_version = 7
selected_device = "receiver:1234abcd:slot:1"

[app_settings]

# global application settings

[devices."receiver:1234abcd:slot:1"]

# per-device configuration

[keyboard.bindings]

# global hotkeys

```

The `schema_version` must be set to `7` in current releases. The `selected_device` string references a physical device key used elsewhere in the file.

## Global Application Settings

The `[app_settings]` table contains UI preferences and runtime behavior toggles that apply across all devices.

### UI and Runtime Toggles

Key boolean and string options include:
- `launch_at_login`, `check_for_updates`, `auto_install_updates` — system integration
- `language`, `appearance`, `ui_scale`, `device_view_mode` — interface customization
- `smooth_scroll`, `vertical_scroll_sensitivity`, `thumbwheel_sensitivity` — input handling defaults

### Asset Management

Background asset retrieval is controlled via:
- `auto_download_assets` — boolean toggle for automatic downloads
- `asset_source` — repository or mirror URL

These settings are documented in [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) and parsed by the core configuration loader in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs).

## Device-Specific Configuration

Each physical device receives a dedicated `[devices."<physical-key>"]` table, where the physical key follows the format `receiver:<id>:slot:<n>` or similar device identifiers.

### Device Identification and DPI Settings

Required identity fields include `custom_name` and `enabled`. Pointer sensitivity is configured through:
- `dpi` — current active DPI value
- `dpi_presets` — array of available presets (e.g., `[800, 1600, 3200]`)

Scroll behavior modifiers include `invert_scroll`, `scroll_resolution`, and device-specific `thumbwheel_sensitivity`.

### Button Bindings and Actions

The `[devices."<key>".bindings]` table maps physical button names to actions. Actions accept two forms:

1.  **Simple string**: Direct command reference
2.  **Inline table**: Complex behaviors with modifiers

```toml
[devices."receiver:1234abcd:slot:1".bindings]
Back = "BrowserBack"
MiddleClick = { HoldShortcut = "Ctrl+Space" }
DpiToggle = { short = "ShowDesktop", long = "MissionControl" }

```

The `short` and `long` keys enable time-based differentiation, while `CustomShortcut` and `HoldShortcut` trigger specific key combinations.

### Per-Application Overrides

The `[devices."<key>".per_app_bindings."<app-id>"]` namespace provides sparse overlays keyed by application identifiers. Valid keys include macOS bundle IDs, Linux application IDs, or Windows executable names.

Only explicitly listed buttons override the defaults; unlisted buttons fall back to the device-wide mappings defined in the parent `bindings` table.

### Action Ring Configuration

Devices supporting the Action Ring feature use an eight-slot UI configured via `[devices."<key>".action_ring]`. Each cardinal direction accepts an action plus optional metadata:

```toml
[devices."receiver:1234abcd:slot:1".action_ring]
Top = { action = { CustomShortcut = "Cmd+Shift+P" }, icon = "Keyboard", label = "Command Palette" }

```

## Global Keyboard Shortcuts

Independent of device-specific mappings, the `[keyboard.bindings]` table defines system-wide hotkeys. Modifier keys accept standard names (`shift`, `control`, `option`, `command`) and common aliases (`ctrl`, `alt`, `cmd`).

```toml
[keyboard.bindings]
f1 = "MissionControl"
f2 = "ShowDesktop"

```

These bindings are processed by the agent entry point in [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs) alongside device inputs.

## Summary

- OpenLogi uses a **strictly validated TOML file** located at `~/.config/openlogi/config.toml` (Unix) or `%USERPROFILE%\.config\openlogi\config.toml` (Windows).
- The **required `schema_version = 7`** must be declared at the top level to ensure compatibility with the parser in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs).
- **Global settings** reside under `[app_settings]`, covering launch behavior, UI appearance, and default input sensitivity.
- **Per-device configuration** uses `[devices."<physical-key>"]` tables containing DPI presets, scroll settings, and button bindings.
- **Button actions** support both simple strings and inline tables for complex behaviors like short/long press differentiation.
- **Per-application overrides** are keyed by OS-specific application identifiers under `[devices."<key>".per_app_bindings."<app-id>"]`.
- The system maintains **five rolling backups** and enters read-only mode if schema validation fails.

## Frequently Asked Questions

### Where is the OpenLogi configuration file stored on Linux and macOS?

On Linux and macOS, OpenLogi stores its configuration at `$XDG_CONFIG_HOME/openlogi/config.toml`, which typically resolves to `~/.config/openlogi/config.toml`. This path follows the XDG Base Directory Specification and is shared between the GUI and background agent.

### What is the current schema_version for OpenLogi configuration files?

Current releases require `schema_version = 7` declared at the top of the file. This version number is strictly enforced; if omitted or mismatched, the configuration parser in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) will reject the file and prevent the application from loading the settings.

### How do I configure different button mappings for specific applications?

Create a table at `[devices."<physical-key>".per_app_bindings."<app-id>"]` where `<app-id>` is the macOS bundle identifier, Linux app ID, or Windows executable name. List only the buttons you wish to override in this table; all other buttons will continue using the device-wide defaults from the parent `bindings` table.

### What happens if I make a syntax error in the config.toml file?

OpenLogi implements strict schema validation. If the TOML parser encounters invalid syntax, misspelled keys, or out-of-range values, the application aborts loading the file and places the GUI into read-only mode. The system preserves up to five backup versions (`config.toml.backup.1` through `backup.5`) to facilitate recovery without data loss.