# OpenLogi Application Processes: A Complete Guide to the 4 Core Components

> Explore the OpenLogi application processes. Understand the 4 core components, how they communicate via tarpc and bincode serialization, and unlock efficient data handling.

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

---

**OpenLogi runs as four independent, long-running processes that communicate through a local-socket IPC layer using tarpc and bincode serialization.**

OpenLogi is a Rust-based input device management system for Logitech hardware. Rather than a single monolithic application, it adopts a **multi-process architecture** where each component handles a specialized responsibility and coordinates with others through inter-process communication (IPC). This design improves stability, security, and platform flexibility.

## The Four Core Processes in OpenLogi

OpenLogi decomposes functionality into four distinct executable processes. Each can run independently, though production deployments typically launch the three long-running processes together.

### 1. GUI (Desktop) — Settings and Controls

The **GUI process** provides the main user-facing window where you configure device settings, manage profiles, and control per-application behavior.

- **Location**: `crates/openlogi-desktop`
- **Entry point**: [`openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-desktop/src/main.rs)
- **Key characteristic**: Performs **no HID I/O directly** — all device operations are delegated to the agent via IPC

This separation keeps the GUI responsive and prevents UI freezes from blocking device communication. The GUI is a pure IPC client that sends commands and receives state updates from the agent.

```bash

# Launch the desktop GUI

cargo run -p openlogi-desktop

```

### 2. Agent — HID and Input Management

The **Agent process** is the runtime core of OpenLogi. It owns all privileged operations that require direct hardware access.

**Responsibilities**:

- Input hook registration and event handling
- HID++ protocol communication with Logitech devices
- DPI adjustments and SmartShift management
- Session state distribution to IPC clients

- **Location**: `crates/openlogi-agent`
- **Entry point**: [`openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-agent/src/main.rs)
- **Dependencies**: `openlogi-hid` (HID layer), `openlogi-device-registry` (device discovery)

The agent is the **only process** with direct hardware access. Both the GUI and Overlay communicate exclusively through the agent's IPC interface.

```bash

# Launch the agent (must run for GUI/Overlay to function)

cargo run -p openlogi-agent

```

### 3. Overlay — Actions Ring

The **Overlay process** renders a lightweight, cursor-centered "Actions Ring" interface that appears on top of other application windows.

- **Location**: `crates/openlogi-overlay`
- **Entry point**: [`openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-overlay/src/main.rs)
- **Design**: Pure IPC client with no direct device access

The overlay receives session state from the agent and renders visual feedback based on current context. This isolates graphics rendering into its own process for stability and compositor integration.

```bash

# Launch the overlay (requires running agent)

cargo run -p openlogi-overlay

```

### 4. CLI — Diagnostics and Utilities

The **CLI process** provides command-line access to OpenLogi functionality for troubleshooting and automation.

**Capabilities**:

- `openlogi list` — enumerate connected devices
- Hardware diagnostic subcommands
- Direct device enumeration fallback when no agent is running

- **Location**: `crates/openlogi-cli`
- **Binary name**: `openlogi` (thin wrapper)
- **Behavior**: Prefers a running agent for device inventory, but can enumerate devices directly when needed

```bash

# List devices (uses running agent if available)

openlogi list

```

## Process Relationships and IPC Architecture

The OpenLogi processes operate as **siblings**, not in a parent-child hierarchy. This flat structure provides several advantages:

| Aspect | Implementation |
|--------|---------------|
| **Transport** | Local sockets via `tarpc` + `bincode` |
| **Contract** | Defined in [`crates/openlogi-ipc/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/AGENTS.md)【AGENTS.md†L46-L52】 |
| **Shared UI** | GUI and Overlay both use `openlogi-ui` crate for rendering assets |

In production bundles, all three long-running processes (GUI, Agent, Overlay) launch together, but any can be restarted independently without affecting the others.

## Key Source Files for OpenLogi Processes

| File Path | Purpose |
|-----------|---------|
| [`crates/openlogi-desktop/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/main.rs) | GUI process entry point |
| [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs) | Agent process entry point |
| [`crates/openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/main.rs) | Overlay process entry point |
| [`crates/openlogi-cli/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/main.rs) | CLI implementation |
| [`crates/openlogi-ipc/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/AGENTS.md)【AGENTS.md†L15-L52】 | Architecture and IPC contract documentation |

## Summary

- **GUI process** (`openlogi-desktop`): User settings interface, IPC client only
- **Agent process** (`openlogi-agent`): Hardware owner, runs input hooks and HID++ protocol
- **Overlay process** (`openlogi-overlay`): Cursor-centered Actions Ring, pure renderer
- **CLI process** (`openlogi-cli`): Diagnostics and device enumeration with agent fallback

The multi-process design ensures that HID operations remain isolated in the agent while the UI layer can evolve independently.

## Frequently Asked Questions

### What happens if the OpenLogi agent is not running?

The GUI and Overlay processes will fail to connect via IPC and cannot function. The CLI falls back to direct device enumeration but loses stateful operations. Always ensure the agent is running for full functionality.

### Why does OpenLogi use multiple processes instead of threads?

Process isolation provides **security boundaries** (agent runs with elevated HID privileges), **crash containment** (UI failure doesn't disconnect devices), and **flexibility** (Overlay can use different graphics backends). The IPC overhead is negligible with local sockets and bincode.

### Can I run only specific OpenLogi processes?

Yes. Each process is independently executable via `cargo run -p <crate-name>`. Advanced users can run the agent on a headless system and connect remote clients, though this requires custom IPC configuration.

### Where is the IPC protocol defined?

The complete IPC contract is documented in **[`crates/openlogi-ipc/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/AGENTS.md)**【AGENTS.md†L15-L52】, including message types, service definitions, and version compatibility guarantees.