OpenLogi Configuration File Structure: A Complete Guide to TOML Settings

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, 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 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:

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 and parsed by the core configuration loader in 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

[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:

[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).

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

These bindings are processed by the agent entry point in 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.
• 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 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.

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