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

> Learn to configure the OpenLogi Actions Ring using the TOML file or the desktop GUI. Customize actions, icons, and labels for your device with this comprehensive guide.

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

---

**You configure the OpenLogi Actions Ring by editing the `actions_ring` section within your device block in [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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](https://github.com/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action_ring.rs). The configuration resides in the user-level [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml). Each device uses its hardware identifier as the section key:

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

```toml
[[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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```toml
[[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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```rust
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:

```rust
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) to apply changes.
- Key source files include [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) for parsing and [`crates/openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.