How to Configure the OpenLogi Actions Ring: A Complete TOML and GUI Guide

You configure the OpenLogi Actions Ring by editing the actions_ring section within your device block in config.toml, where you enable the feature and define eight slots with specific actions, icons, and labels, or by using the built-in GUI editor in openlogi-desktop.

The Actions Ring in OpenLogi is an eight-slot radial menu that provides quick access to commands and application launches. According to the AprilNEA/OpenLogi source code, this feature is configured per device through either direct TOML editing or the graphical interface. Each device is identified by its unique device_key, allowing distinct ring layouts for different input hardware.

Understanding the Actions Ring Structure

The Actions Ring is implemented as a circular interface with exactly eight positions, defined in crates/openlogi-core/src/binding/action_ring.rs. The configuration resides in the user-level config.toml file under a device-specific section.

Each ring configuration contains three primary components:

• enabled: A boolean flag that activates or deactivates the ring for the specific device.
• slots: An array of exactly eight entries representing the radial positions, configured clockwise from the top.
• icon or label: Optional visual overrides for individual slots using built-in icon names or custom text labels.

Configuring the Actions Ring in config.toml

Direct editing of the TOML file provides the most flexible configuration method for the Actions Ring.

Device Identification

Begin by locating or creating the device block in config.toml. Each device uses its hardware identifier as the section key:

[device."Logitech G502"]
actions_ring.enabled = true

Customizing Individual Slots

Within the device block, define the eight slots using TOML array-of-tables syntax. Each slot requires an action field and supports optional display modifiers:

[[device."Logitech G502".actions_ring.slots]]
action = "ShowActionsRing"
icon   = "grid"

[[device."Logitech G502".actions_ring.slots]]
action = "OpenApplication"
label  = "Chrome"

[[device."Logitech G502".actions_ring.slots]]
action = "DoNothing"

Available actions are validated against the definitions in crates/openlogi-core/src/binding/action_ring.rs and include Show Actions Ring, Open Application, and Do Nothing for empty slots.

Visual Customization Options

Override default glyphs by specifying either an icon name from the built-in set or a text label for literal display:

[[device."Logitech G502".actions_ring.slots]]
action = "OpenApplication"
icon   = "browser"

Using the GUI Configuration Editor

For users preferring graphical management, the openlogi-desktop application provides an Actions Ring editor under the Actions Ring tab. This interface allows live editing of slot assignments without manually editing TOML.

Changes made through the GUI are automatically persisted back to the same config.toml file. This ensures consistency between manual and visual configuration methods while providing immediate visual feedback during customization.

Configuration Processing Pipeline

Understanding how OpenLogi processes your configuration helps troubleshoot invalid setups.

Parsing and Validation

1. Parsing: The Config::load function in crates/openlogi-core/src/config.rs reads the TOML file and deserializes it into a DeviceConfig structure.
2. Validation: crates/openlogi-core/src/binding/action_ring.rs validates each slot assignment, rejecting illegal configurations such as binding Show Actions Ring recursively within the ring itself.

Runtime Implementation

The session state is maintained in crates/openlogi-agent-core/src/action_ring.rs, which exposes the current configuration via RPC through the IPC layer (crates/openlogi-ipc/src/ipc.rs). The overlay renderer (openlogi-overlay) queries this state to display the ring on-screen.

Programmatic Configuration Examples

Reading Device Configuration

To access the Actions Ring settings programmatically, use the configuration API:

use openlogi_core::config::Config;
use std::path::Path;

fn load_device_config(path: &Path, device_key: &str) {
    let cfg = Config::load(path).expect("could not load config");
    let dev_cfg = cfg.device(device_key).expect("device not found");
    println!("Actions Ring enabled: {}", dev_cfg.actions_ring.enabled);
    for (i, slot) in dev_cfg.actions_ring.slots.iter().enumerate() {
        println!("Slot {} → {:?}", i + 1, slot);
    }
}

Triggering the Ring via IPC

Custom actions can invoke the ring using the IPC client:

use openlogi_agent_core::action_ring::ActionRingClient;
use openlogi_ipc::ipc::ShowActionsRingRequest;

async fn show_ring(client: ActionRingClient) -> anyhow::Result<()> {
    client.show_ring(ShowActionsRingRequest {}).await?;
    Ok(())
}

Summary

• Configure the Actions Ring per device in config.toml using the device_key identifier (e.g., [device."Logitech G502"]).
• Each device supports exactly eight slots arranged clockwise from the top position.
• Set actions_ring.enabled = true to activate the feature for a specific device.
• Define slot behavior with the action field and customize appearance using optional icon or label fields.
• Use openlogi-desktop for graphical configuration or edit the TOML directly.
• Reload the OpenLogi agent after modifying config.toml to apply changes.
• Key source files include crates/openlogi-core/src/config.rs for parsing and crates/openlogi-core/src/binding/action_ring.rs for validation logic.

Frequently Asked Questions

Where is the OpenLogi configuration file located?

The configuration file is named config.toml and resides in the OpenLogi configuration directory alongside the application data. After editing this file, you must reload the configuration or restart the OpenLogi agent to apply the new Actions Ring layout.

Can I configure different Actions Ring layouts for different devices?

Yes. The TOML structure uses device-specific sections identified by device_key, allowing you to define unique actions_ring configurations for each input device. This enables distinct radial menus for a mouse versus a trackpad, for example.

What actions can I assign to Actions Ring slots?

Available actions are defined in crates/openlogi-core/src/binding/action_ring.rs and include Show Actions Ring, Open Application, Do Nothing for empty slots, and any other actions supported by the OpenLogi core system. Each slot must specify a valid action string from this defined set.

How do I apply configuration changes without restarting my computer?

After editing config.toml, reload the configuration through the OpenLogi agent interface or restart the agent process. Changes made through the openlogi-desktop GUI apply immediately and persist to the configuration file without requiring a manual reload.

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