# How to Configure the Actions Ring in OpenLogi: TOML and GUI Setup

> Configure the Actions Ring in OpenLogi using TOML edits or the GUI editor. Define eight radial slots with custom actions, icons, and labels for efficient device control. Reload or edit live.

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

---

**To configure the Actions Ring in OpenLogi, edit the device-specific `actions_ring` section in [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) to define eight radial slots with specific actions, icons, and labels, then reload the configuration or use the `openlogi-desktop` GUI editor for live changes.**

OpenLogi implements the **Actions Ring** as a customizable eight-slot radial menu that provides quick access to system commands and applications. The configuration resides in the TOML-based user configuration file and supports per-device customization using unique `device_key` identifiers. Whether you prefer editing configuration files directly or using the graphical interface, OpenLogi offers flexible methods to tailor the ring to your workflow.

## Understanding the Actions Ring Structure

The Actions Ring is defined within device-specific blocks in the OpenLogi configuration. Each device entry identified by its `device_key` (such as `"Logitech G502"`) contains an `actions_ring` table that controls visibility and slot assignments.

### Configuration File Location

User settings are stored in [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) at the root of the OpenLogi configuration directory. The parser in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) handles deserialization into the `DeviceConfig` structure, which contains the `ActionsRing` struct defining the eight-slot layout.

### The Eight-Slot Layout

Each device supports exactly eight slots arranged clockwise from the top position. The `slots` array must contain eight entries, where each entry specifies an action binding and optional visual customization through `icon` or `label` fields.

## TOML Configuration Syntax

Configuring the ring requires editing the TOML file under the `[device."<device_key>"]` section. Three primary settings control the ring behavior.

### Enabling the Ring

Set `actions_ring.enabled` to `true` or `false` to toggle visibility for the specific device. The default value is `true`.

### Defining Slot Actions

Each slot entry requires an `action` field referencing predefined constants from [`crates/openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action_ring.rs). Valid options include `ShowActionsRing`, `OpenApplication`, and `DoNothing`. Optional fields `icon` and `label` override default glyphs with custom graphics or text labels.

```toml
[device."Logitech G502"]

# Enable the Actions Ring for this device

actions_ring.enabled = true

# Customize the eight slots (clockwise from the top)

[[device."Logitech G502".actions_ring.slots]]
action = "ShowActionsRing"      # Slot 1 – the default “show ring” action

icon   = "grid"                # Use the grid icon for this slot

[[device."Logitech G502".actions_ring.slots]]
action = "OpenApplication"
label  = "Chrome"              # Show a literal label instead of an icon

[[device."Logitech G502".actions_ring.slots]]
action = "DoNothing"           # Empty slot – nothing happens

# … repeat for the remaining five slots …

```

## Available Actions and Validation

The permissible action set is 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). This module validates slot assignments during configuration loading, rejecting illegal combinations such as nesting `ShowActionsRing` inside the ring itself.

Common actions include:

- **ShowActionsRing**: Recursively opens the ring menu (typically reserved for the top slot)
- **OpenApplication**: Launches a specified program when combined with metadata
- **DoNothing**: Creates an empty slot that performs no action

## Runtime Architecture

After configuration parsing, three core components handle the Actions Ring lifecycle.

### Configuration Parsing

The `Config::load` method in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) deserializes the TOML file and instantiates `DeviceConfig` structures containing the `ActionsRing` data.

### State Management

[`crates/openlogi-agent-core/src/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent-core/src/action_ring.rs) maintains the current session state and exposes RPC endpoints for showing or hiding the ring. The `ActionRingClient` provides async methods to trigger these state changes via the IPC layer in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs).

### Overlay Rendering

The GPUI-based overlay in [`crates/openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/main.rs) queries the agent's state to render the radial menu on screen.

## GUI Configuration Method

The `openlogi-desktop` application provides an **Actions Ring editor** accessible under the *Actions Ring* tab. This interface allows live editing without manually modifying [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml). Changes made through the GUI persist automatically to the configuration file and apply immediately to the running agent.

## Code Examples

Reading the configuration programmatically:

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

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

- The **Actions Ring** is an eight-slot radial menu configured per device in [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml)
- Each device block uses a `device_key` identifier and contains `actions_ring.enabled` and `actions_ring.slots` settings
- Slots accept actions 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) with optional `icon` or `label` overrides
- Configuration changes require reloading the agent or using the `openlogi-desktop` GUI editor
- Runtime components in `openlogi-agent-core` and `openlogi-overlay` handle state management and rendering

## Frequently Asked Questions

### Can I have different Actions Ring configurations for different mice?

Yes. OpenLogi supports per-device configuration using unique `device_key` identifiers in the TOML file. Each `[device."<device_key>"]` block can contain independent `actions_ring` settings, allowing distinct layouts for different hardware models.

### What happens if I assign ShowActionsRing to a slot inside the ring?

The configuration validator in [`crates/openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action_ring.rs) rejects this assignment during parsing. This prevents infinite recursion where triggering the ring would attempt to reopen itself.

### Do I need to restart OpenLogi after editing config.toml?

Yes, you must reload the configuration or restart the OpenLogi agent to apply TOML changes. Alternatively, use the `openlogi-desktop` GUI editor, which applies changes immediately and persists them to the configuration file.

### How do I create an empty slot in the Actions Ring?

Set the slot's `action` field to `"DoNothing"`. This creates a placeholder that renders no functionality when selected, effectively creating a gap in the radial menu.