# How to Configure the Actions Ring in OpenLogi: Slot Layout Guide

> Learn to configure the OpenLogi Actions Ring slot layout. This guide explains how to use action ring entries slot0 through slot7 in your TOML config for quick macro and command access.

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

---

**The Actions Ring is an eight-slot, cursor-centered overlay in OpenLogi that provides quick access to macros and system commands, configured via the `action_ring` table in your TOML config using `slot0` through `slot7` entries.**

The Actions Ring is a central feature of the OpenLogi input management system, providing immediate contextual access to application launches, DPI changes, and custom macros. This radial menu appears at your cursor position when triggered and can be fully customized through configuration files or programmatic APIs. Understanding how to configure the **Actions Ring slot layout** allows you to optimize your workflow with up to eight context-aware actions per device or application.

## Understanding the Actions Ring Architecture

The Actions Ring is invoked by the `ShowActionsRing` binding, defined in [`openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/binding/action.rs). When triggered, the system spawns a lightweight GPUI process (`openlogi-overlay`) that renders the ring around the current pointer location, communicating via the IPC layer (`openlogi-ipc`).

The implementation relies on several key components:

- **Eight fixed slots**: Arranged clockwise starting from the top (positions 0 through 7)
- **Overlay renderer**: [`openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-overlay/src/main.rs) handles the visual presentation
- **Haptic feedback**: Managed by a coalescing haptic worker in [`openlogi-agent/src/server.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-agent/src/server.rs)
- **Configuration storage**: Per-device settings in [`openlogi-core/src/config/device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/config/device.rs)

## Configuring the Actions Ring Slot Layout

OpenLogi stores ring configurations under the `action_ring` table within your device configuration file, typically located at `~/.config/openlogi/config.toml`. According to the source code in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md), you define layouts using a simple TOML structure.

### Default Layout Structure

Define your default ring layout using the `slot0` through `slot7` keys under the `[action_ring.default]` table:

```toml
[device."<device-id>"]
actions_ring.enabled = true

[action_ring.default]
slot0 = { action = "ShowDesktop", icon = "desktop", label = "Desktop" }
slot1 = { action = "LaunchChrome", icon = "chrome", label = "Chrome" }
slot2 = { action = "MuteMic", icon = "mic", label = "Mute" }
slot3 = { action = "DoNothing", icon = "", label = "" }
slot4 = { action = "BrightnessUp", icon = "bright+", label = "Bright+" }
slot5 = { action = "BrightnessDown", icon = "bright-", label = "Bright-" }
slot6 = { action = "ShowNotifications", icon = "bell", label = "Notify" }
slot7 = { action = "OpenSettings", icon = "gear", label = "Settings" }

```

### Per-Application Overrides

You can override the default **slot layout** for specific applications using the `[action_ring."<bundle-id>"]` syntax:

```toml
[action_ring."com.google.Chrome"]
slot0 = { action = "OpenNewTab", icon = "new-tab", label = "New Tab" }
slot1 = { action = "RefreshPage", icon = "refresh", label = "Refresh" }

```

### Managing Empty Slots

To leave a slot empty, use the special `DoNothing` action as shown in `slot3` above. This sentinel value is defined in [`openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/binding/action_ring.rs). The **icon** and **label** fields are optional but recommended for visual clarity; the set of available icons is defined in [`openlogi-core/src/binding/action_ring/icon.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/binding/action_ring/icon.rs).

## Practical Implementation Examples

### Binding the Trigger

Map the ring to a physical button in your TOML configuration as defined in [`openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/binding/action.rs):

```toml
[[bindings]]
action = "ShowActionsRing"
trigger = "Button3"

```

### Runtime Configuration with Rust

For dynamic updates, use the OpenLogi Rust API as implemented in [`openlogi-desktop/src/state/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-desktop/src/state/action_ring.rs):

```rust
use openlogi_core::config::DeviceConfig;
use openlogi_core::binding::action_ring::ActionRingSlot;

let mut cfg = DeviceConfig::load()?;

// Update slot 2 (third position clockwise from top)
cfg.action_ring.default[2] = ActionRingSlot::new(
    "RunMacro",
    Some("macro_icon".into()),
    Some("My Macro".into()),
);

cfg.save()?;

```

### Reading Active Layouts at Runtime

Access the current runtime state from the agent side to inspect the active **slot layout**:

```rust
let ring_state = agent.runtime.actions_ring_state();
println!("Current layout: {:?}", ring_state.current_layout());

```

## Summary

- The **Actions Ring** provides eight configurable slots (0-7) arranged clockwise from the top, rendered by the `openlogi-overlay` binary when triggered by the `ShowActionsRing` binding.
- Configure layouts in `~/.config/openlogi/config.toml` under the `[action_ring.default]` table using `slot0` through `slot7` entries with action, icon, and label fields.
- Use **per-application overrides** with `[action_ring."<bundle-id>"]` syntax to customize layouts for specific apps, falling back to defaults when no override exists.
- Empty slots require the `DoNothing` action, defined in [`openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/binding/action_ring.rs).
- Changes are persisted to TOML and can be manipulated programmatically via the Rust API in [`openlogi-core/src/config/device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/config/device.rs) and [`openlogi-desktop/src/state/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-desktop/src/state/action_ring.rs).

## Frequently Asked Questions

### How many slots does the OpenLogi Actions Ring support?

The Actions Ring supports exactly **eight slots**, indexed 0 through 7. Slot 0 appears at the top of the ring, with subsequent slots arranged clockwise around the cursor. This fixed layout is defined in the core configuration schema in [`openlogi-core/src/config/device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/config/device.rs) and cannot be changed, though any slot can be left empty using the `DoNothing` action.

### Can I have different Actions Ring layouts for different applications?

Yes. OpenLogi supports per-application overrides using the `[action_ring."<bundle-id>"]` syntax in your TOML configuration, as documented in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md). When the active application changes, the system automatically switches to the corresponding layout, falling back to `[action_ring.default]` if no override exists for the current application.

### What file handles the visual rendering of the Actions Ring?

The visual overlay is rendered by [`openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-overlay/src/main.rs), a separate GPUI process spawned by the agent. This process communicates with the main OpenLogi daemon via the IPC layer ([`openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-ipc/src/ipc.rs)), receiving layout data and cursor position information to draw the ring at the correct screen coordinates.

### How do I trigger the Actions Ring programmatically?

Invoke the ring by binding the `ShowActionsRing` action to a mouse button or key in your configuration file, or call it programmatically through the OpenLogi API. The binding definition resides in [`openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/binding/action.rs), and triggering it launches the overlay process managed by [`openlogi-agent/src/overlay.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-agent/src/overlay.rs) and activates the haptic feedback worker.