# What Is the openlogi-agent in OpenLogi? Core Background Service Explained

> Discover the openlogi-agent, OpenLogi's core background service. Learn how it handles HID++ device I/O, global input hooks, and exposes an IPC socket for hardware operations.

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

---

**The `openlogi-agent` is the core background service in OpenLogi that owns all low-level HID++ device I/O, manages the global input hook for event capture, and exposes a tarpc/bincode IPC socket that the GUI and CLI use to request hardware operations.**

The `openlogi-agent` binary serves as the foundational daemon in the OpenLogi ecosystem, handling direct hardware communication for Logitech HID++ devices. Unlike the graphical interface, this agent runs continuously as a background process, ensuring persistent device connectivity and input event capture. According to the OpenLogi source code, this separation allows the GUI to remain a lightweight IPC client that can be restarted independently of the hardware layer.

## Core Responsibilities of the openlogi-agent

The agent consolidates four critical functions that require persistent execution: hardware communication, input event interception, IPC serving, and lifecycle management.

### HID++ Communication and Device Management

At its core, the agent owns the **HID++ communication loop**. It talks directly to Logitech receivers (Unifying, Bolt, or Bluetooth) and wired devices, handling enumeration, pairing, DPI adjustments, SmartShift configuration, and button remapping. Because the agent maintains exclusive access to these resources, it prevents conflicts that would occur if multiple clients attempted simultaneous device I/O.

### Global Input Hook and Event Capture

The agent runs the **`openlogi-hook`** component, a global input hook that captures mouse and keyboard events at the system level. This enables per-application profiles and the Actions Ring functionality. By centralizing the hook in the agent rather than the GUI, OpenLogi ensures that input monitoring persists even when the graphical interface is closed or restarting.

### IPC Server for GUI and CLI Delegation

The agent exposes a **tarpc/bincode IPC socket** (`openlogi-agent.sock`) defined in the `crates/openlogi-ipc` contract. The GUI (`openlogi-desktop`), the overlay, and the CLI (`openlogi`) connect to this socket to request device operations. This architecture means the GUI **does not own any HID++ resources** itself; all hardware interaction is delegated to the agent, which processes requests and returns device state.

## Architecture: Hardware Isolation and Client Model

OpenLogi employs a strict separation between the hardware layer and presentation layer. The `openlogi-agent` acts as the sole owner of device resources, while the GUI and CLI function as stateless IPC clients. This design provides two key advantages:

- **Independent lifecycles**: The GUI can crash or be updated without disconnecting devices or stopping the input hook.
- **CLI fallback**: When the agent is unavailable, the CLI (`openlogi list`) can fall back to direct device enumeration, though with reduced functionality.

The documentation in [`docs/INSTALL-linux.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/INSTALL-linux.md) notes that the agent "must be running for the GUI and CLI to work" (line 159), and the Windows installer packages the agent alongside the GUI in every release.

## Lifecycle Management and Autostart Configuration

The agent manages its own startup, shutdown, and restart logic through dedicated modules that handle platform-specific requirements.

### Startup and Shutdown Sequences

The file [`crates/openlogi-agent/src/lifecycle.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/lifecycle.rs) implements graceful startup and shutdown transitions. When launched, the agent in [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs) creates the IPC server, initializes the HID++ loop, and ensures only one instance runs via process locking. Shutdown handlers ensure that device connections are cleanly terminated and the socket file is removed.

### Platform-Specific Autostart Implementation

Platform-specific autostart code lives in `crates/openlogi-agent/src/autostart/*.rs`:

- **Linux**: Installs a systemd user unit (`openlogi-agent.service`) that can be enabled with `systemctl --user enable`
- **macOS**: Registers a LoginItem for user session startup
- **Windows**: Writes to the registry Run key for automatic launch

## Working with the openlogi-agent

You can interact with the agent directly through the binary or control it via your platform's service manager.

Start the agent manually on Linux or macOS:

```bash
openlogi-agent

```

Enable automatic startup using systemd:

```bash
systemctl --user enable --now openlogi-agent.service

```

Run the mock agent for testing without physical devices:

```bash
cargo run -p openlogi-agent --bin openlogi-agent-mock

```

Query device status through the agent via the CLI:

```bash
openlogi list

```

Stop the agent when needed:

```bash
killall openlogi-agent

# Or via systemd:

systemctl --user stop openlogi-agent.service

```

## Key Source Files and Implementation Details

The agent's functionality is organized into specific modules within the `crates/openlogi-agent` directory:

- [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs) — Entry point; creates the IPC server, starts the HID++ loop, and enforces single-instance execution
- [`crates/openlogi-agent/src/server.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/server.rs) — Implements the tarpc IPC service that processes requests from GUI and overlay clients
- [`crates/openlogi-agent/src/lifecycle.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/lifecycle.rs) — Handles startup sequences, graceful shutdown, and restart transitions
- `crates/openlogi-agent/src/autostart/*.rs` — Platform-specific implementations for automatic startup (systemd, macOS LoginItem, Windows registry)
- `crates/openlogi-ipc` — Defines the IPC contract and socket protocol used by the agent

These components collectively define the `openlogi-agent` as a dedicated, always-running background process that isolates hardware complexity behind a stable IPC interface.

## Summary

- **Hardware Ownership**: The `openlogi-agent` exclusively manages all HID++ device I/O, preventing resource conflicts between clients.
- **Input Hook**: It runs the global `openlogi-hook` for event capture, enabling per-application profiles independent of GUI state.
- **IPC Architecture**: Exposes a tarpc/bincode socket (`openlogi-agent.sock`) that the GUI, overlay, and CLI use to request operations.
- **Lifecycle Control**: Manages startup, shutdown, and platform-specific autostart via [`lifecycle.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/lifecycle.rs) and `autostart/*.rs`.
- **Client Isolation**: The GUI and CLI are lightweight IPC clients that delegate all hardware operations to the agent, allowing independent restarts.

## Frequently Asked Questions

### What is the role of the openlogi-agent in OpenLogi?

The `openlogi-agent` functions as the background service that owns all low-level device communication for Logitech HID++ hardware. It handles device enumeration, pairing, configuration changes, and input event capture, exposing these capabilities to the GUI and CLI through an IPC socket.

### How does the openlogi-agent communicate with other OpenLogi components?

The agent exposes a **tarpc/bincode IPC socket** at `openlogi-agent.sock`. The GUI (`openlogi-desktop`), command-line interface (`openlogi`), and overlay connect to this socket to request device operations. The IPC contract is defined in `crates/openlogi-ipc`, ensuring type-safe communication between the agent and its clients.

### Can I use OpenLogi without the openlogi-agent running?

The GUI requires the agent to function, as documented in [`docs/INSTALL-linux.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/INSTALL-linux.md). However, the CLI (`openlogi list`) includes a fallback mechanism that performs direct device enumeration when the agent is unavailable, though this provides limited functionality compared to the full IPC-based workflow.

### How do I configure the openlogi-agent to start automatically?

Platform-specific autostart implementations are provided in `crates/openlogi-agent/src/autostart/*.rs`. On Linux, enable the systemd user service with `systemctl --user enable openlogi-agent.service`. On macOS, the agent registers as a LoginItem, and on Windows, it adds a registry entry to the Run key during installation.