# OpenLogi Overlay Binary: A Separate GPUI Process from the Main Desktop Application

> Discover if the openlogi-overlay binary is a separate GPUI process from the main desktop application. Learn how OpenLogi's architecture enhances performance and stability.

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

---

**Yes, the `openlogi-overlay` binary runs as an independent GPUI-based process that operates as a sibling to the main desktop application rather than running inside it.**

The AprilNEA/OpenLogi repository implements a deliberate three-process architecture where the overlay component maintains its own process image separate from the main GUI. This design separates the **Actions Ring** cursor-centered interface from the primary desktop window, enabling independent lifecycle management and rendering contexts.

## The Three-Process Architecture Model

OpenLogi ships with three distinct executables that communicate via **tarpc-based IPC**:

- **`openlogi-desktop`**: The primary GPUI desktop interface (main GUI)
- **`openlogi-agent`**: Background server handling device I/O and input hooks
- **`openlogi-overlay`**: The cursor-centered Actions Ring helper using its own GPUI context

According to the architecture documentation in [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md), these three processes "ship in one install — GUI, agent, overlay — and the overlay is a sibling of the GUI, not a part of it." This separation ensures that overlay rendering failures or crashes do not destabilize the main desktop application.

## Evidence of Process Separation in the Source Code

### Crate Dependencies

The `openlogi-overlay` crate explicitly avoids linking against the desktop crate. In [`crates/openlogi-overlay/Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/Cargo.toml), the binary declares dependencies only on `openlogi-ui` and GPUI libraries, never on `openlogi-desktop`:

```toml

# crates/openlogi-overlay/Cargo.toml

[dependencies]
openlogi-ui = { path = "../openlogi-ui" }
gpui = { git = "https://github.com/zed-industries/zed" }

```

This dependency isolation confirms that the overlay builds as a **standalone executable** with its own [`main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/main.rs) entry point at [`crates/openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/main.rs).

### Process Spawning Implementation

The `openlogi-agent` crate manages the overlay lifecycle, not the desktop application. In [`crates/openlogi-agent/src/overlay.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/overlay.rs), the agent spawns the overlay as a child process using standard library commands:

```rust
// crates/openlogi-agent/src/overlay.rs
let overlay_path = find_on_path("openlogi-overlay");
std::process::Command::new(overlay_path)
    .arg("--socket")
    .arg(&ipc_path)           // path to the tarpc socket
    .spawn()
    .expect("Failed to start openlogi-overlay");

```

This implementation detail confirms that `openlogi-desktop` never directly executes the overlay binary; instead, the agent launches it as a **sibling process** with its own process ID and memory space.

## Inter-Process Communication Between Overlay and Desktop

Because the overlay runs separately from the main desktop application, state synchronization occurs through the `openlogi-ipc` crate. Both processes implement a shared tarpc service trait defined in [`crates/openlogi-ipc/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/lib.rs):

```rust
// crates/openlogi-ipc/src/lib.rs
#[tarpc::service]
pub trait Overlay {
    async fn update_ring(state: RingState) -> ();
}

```

The desktop pushes ring-state updates to the overlay process via this IPC channel, while the overlay renders its GPUI window independently. The default Unix socket path resides at `$TMPDIR/openlogi.sock`, though this is configurable via the `--socket` argument.

## Running and Debugging the Overlay Process

You can execute the overlay binary independently for testing purposes. From the repository root after building:

```bash

# Manual execution for debugging

target/debug/openlogi-overlay

```

When launched manually, the overlay spawns a small cursor-centered window displaying the Actions Ring and attempts to connect to the agent via IPC. This standalone execution capability further confirms its status as a **separate GPUI process** with autonomous window management.

The UI crate's public documentation in [`crates/openlogi-ui/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ui/src/lib.rs) explicitly describes the overlay as the "Actions Ring overlay helper," while [`docs/DEVELOPMENT.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/DEVELOPMENT.md) notes that this component runs "alongside the GUI" as a distinct entity.

## Summary

Key takeaways regarding the `openlogi-overlay` binary architecture:

- **Independent process**: The overlay runs as a separate OS process with its own GPUI context, not as a thread or window within `openlogi-desktop`
- **Sibling relationship**: It operates alongside the main GUI as a peer process, launched by the agent rather than the desktop
- **Isolated dependencies**: The overlay links only against `openlogi-ui` and GPUI libraries, avoiding direct coupling to the desktop crate
- **IPC-based communication**: State synchronization occurs through tarpc services over Unix sockets, not shared memory or function calls
- **Standalone execution**: The binary can run independently for debugging, rendering its own window without the desktop application present

## Frequently Asked Questions

### Is the openlogi-overlay embedded inside the main desktop window?

No. The overlay is **not embedded** inside the desktop window or process. According to the [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) architecture guide, it is explicitly a "sibling" process that renders its own separate GPUI window. The overlay crate at [`crates/openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/main.rs) contains its own application entry point and event loop independent of `openlogi-desktop`.

### How does the overlay communicate with the main application?

Communication happens through **tarpc IPC** via the `openlogi-ipc` crate. The desktop sends state updates using the `Overlay` service trait's `update_ring` method, transmitting data over a Unix domain socket. This inter-process approach allows the overlay to receive ring-state changes without sharing memory space with the desktop process.

### Can I run the overlay binary independently for testing?

Yes. You can execute `target/debug/openlogi-overlay` directly from the command line. When run manually, it spawns the cursor-centered Actions Ring window and attempts to connect to the agent socket at `$TMPDIR/openlogi.sock`. This standalone execution mode is useful for debugging overlay-specific rendering issues without launching the full desktop application.

### Why is the overlay a separate process instead of a thread?

The separation provides **fault isolation** and **independent rendering contexts**. Because GPUI manages its own windowing and event loops, running the overlay as a separate process prevents crashes in the Actions Ring from destabilizing the main desktop interface. This architecture also allows the agent to manage overlay lifecycle independently, restarting the helper without affecting the primary GUI session.