# OpenHuman Tauri Shell Modules Explained: core_process, core_rpc, cdp, and cef_profile

> Explore OpenHuman's Tauri shell modules: core_process, core_rpc, cdp, and cef_profile. Understand how they manage core processes, RPC, CEF webviews, and Chromium profiles.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: internals
- Published: 2026-06-16

---

**The OpenHuman desktop application uses four specialized Tauri shell modules—`core_process`, `core_rpc`, `cdp`, and `cef_profile`—to manage the embedded core lifecycle, authenticate RPC calls, control CEF webviews via Chrome DevTools Protocol, and handle Chromium profile data securely.**

The OpenHuman project is a Rust-based Tauri application that embeds a local core service directly within the desktop UI process. These Tauri shell modules form the critical glue layer between the JavaScript frontend and the embedded backend, handling process lifecycle, secure communication, webview introspection, and profile management according to the tinyhumansai/openhuman source code.

## Core Process Lifecycle with core_process

The **`core_process`** module in [`app/src-tauri/src/core_process.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/core_process.rs) manages the OpenHuman core as a Tokio task inside the Tauri host. This tight coupling ensures the core's HTTP/JSON-RPC server starts and stops with the desktop application.

### Token Generation and Port Handling

Security begins with **token generation**. The `generate_rpc_token()` function creates a 256-bit random hex token stored in `CURRENT_RPC_TOKEN`, passed in-memory to the embedded core via `run_server_embedded_with_ready`. This eliminates the risk of token exposure through command-line arguments.

Port management uses `default_core_port()` to detect stale listeners and perform safe takeovers. If the preferred port is busy, the system falls back to an alternate port and records this via `PortFallbackNotice`. The `identify_listener` and `takeover_stale_listener` functions handle the detection and recovery logic.

### Idempotent Start and Graceful Shutdown

The `ensure_running()` method provides **idempotent startup**. It checks if a task is already running on the expected port using `self.is_rpc_port_open()` and returns early to prevent self-termination. For shutdown and restart operations, `restart_lock()` serializes concurrent requests while `shutdown_token` provides cancellation tokens for the Tokio task.

The module exposes the RPC endpoint via `rpc_url()` and `rpc_token()`, supplying the URL (`http://127.0.0.1:<port>/rpc`) and bearer token to the frontend through the `core_rpc_token` command.

## Authenticated RPC Communication with core_rpc

The **`core_rpc`** module in [`app/src-tauri/src/core_rpc.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/core_rpc.rs) provides utilities for secure communication with the embedded core.

The `core_rpc_url_value()` function returns the RPC endpoint, defaulting to `127.0.0.1:<port>/rpc` when `OPENHUMAN_CORE_RPC_URL` is not set. For authentication, `apply_auth(builder)` inserts the `Authorization: Bearer <token>` header by retrieving the current token from `crate::core_process::current_rpc_token()` and adding it to a `reqwest::RequestBuilder`.

## Chrome DevTools Protocol Integration with cdp

The **`cdp`** package in `app/src-tauri/src/cdp/` wraps the Chrome DevTools Protocol to introspect and control CEF webviews rendering external providers like Gmail or Slack.

### Session and Target Management

The [`session.rs`](https://github.com/tinyhumansai/openhuman/blob/main/session.rs) file manages CDP sessions through `SessionId`, handling open, close, and command operations. The [`target.rs`](https://github.com/tinyhumansai/openhuman/blob/main/target.rs) module enumerates available targets (pages, workers) and handles attachment. The [`conn.rs`](https://github.com/tinyhumansai/openhuman/blob/main/conn.rs) and [`in_process.rs`](https://github.com/tinyhumansai/openhuman/blob/main/in_process.rs) files manage WebSocket-based connections and provide in-process mocks for testing.

### DOM Snapshots and Input Simulation

For screen intelligence and OCR pipelines, [`snapshot.rs`](https://github.com/tinyhumansai/openhuman/blob/main/snapshot.rs) captures `DOMSnapshot` objects representing the full DOM state. The [`input.rs`](https://github.com/tinyhumansai/openhuman/blob/main/input.rs) module sends mouse and keyboard events into specific targets, enabling automated interaction with provider pages.

## CEF Profile Management with cef_profile

The **`cef_profile`** module in [`app/src-tauri/src/cef_profile.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/cef_profile.rs) manages the Chromium Embedded Framework cache directory and user profiles.

### Profile Directory Structure

The `default_root_openhuman_dir()` function selects between `.openhuman` (production) and `.openhuman-staging` based on the `OPENHUMAN_APP_ENV` environment variable. User-specific paths are constructed via `user_openhuman_dir()` and `cache_dir_for_user()`, creating `…/users/<id>/cef` directories with strict validation of the `user_id` string.

The `read_active_user_id()` function reads [`active_user.toml`](https://github.com/tinyhumansai/openhuman/blob/main/active_user.toml) to determine the currently logged-in user, while `configured_cache_path_from_env()` respects the `OPENHUMAN_CEF_CACHE_PATH` override.

### Secure Cache Purging

The `PendingCefPurgeState` struct queues directories for removal on the next launch, typically after a `reset_local_data` command. The `is_trusted_queued_purge_path` validation prevents path-traversal attacks by ensuring only legitimate cache directories are targeted for deletion.

## Practical Implementation Examples

### Starting the Embedded Core

```rust
use app::src_tauri::core_process::CoreProcessHandle;

// Create a handle for the default port (7788)
let core = CoreProcessHandle::new(7788);

// Ensure the core is running (idempotent)
core.ensure_running().await.map_err(|e| anyhow::anyhow!(e))?;

```

### Making Authenticated RPC Calls

```rust
use reqwest::Client;
use app::src_tauri::core_rpc::{core_rpc_url_value, apply_auth};

async fn list_threads() -> Result<String, String> {
    let client = Client::new();
    let url = core_rpc_url_value() + "/openhuman.threads_list";
    let builder = client.post(&url);
    let builder = apply_auth(builder)?;
    let resp = builder.send().await.map_err(|e| e.to_string())?;
    resp.text().await.map_err(|e| e.to_string())
}

```

### Capturing DOM Snapshots

```rust
use app::src_tauri::cdp::{target, session::Session, snapshot::DOMSnapshot};

async fn capture_snapshot() -> Result<DOMSnapshot, anyhow::Error> {
    // Attach to the first page target
    let target = target::list().await?.into_iter()
        .find(|t| t.r#type == "page")
        .ok_or_else(|| anyhow::anyhow!("no page target"))?;

    // Open a session
    let sess = Session::new(target.target_id).await?;

    // Request a snapshot
    let snap = DOMSnapshot::capture(&sess).await?;
    Ok(snap)
}

```

### Scheduling CEF Cache Purges

```rust
use app::src_tauri::cef_profile::{
    default_root_openhuman_dir, read_active_user_id, PendingCefPurgeState,
};

fn schedule_purge() -> Result<(), String> {
    let root = default_root_openhuman_dir()?;
    let user_id = read_active_user_id(&root).ok_or("no active user")?;
    let purge_path = root.join("users").join(user_id).join("cef");

    // Load existing pending state (or start fresh)
    let mut state = PendingCefPurgeState::default();
    state.paths.push(purge_path.to_string_lossy().into());

    // Write back to the pending-purge marker file
    let marker = root.parent()
        .ok_or("cannot locate parent of root")?
        .join("openhuman_pending_cef_purge.toml");
    std::fs::write(marker, toml::to_string(&state).unwrap())
        .map_err(|e| e.to_string())
}

```

## Summary

- The **`core_process`** module in [`app/src-tauri/src/core_process.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/core_process.rs) handles the OpenHuman core lifecycle, including token generation, port management, and graceful shutdown.
- **`core_rpc`** utilities in [`app/src-tauri/src/core_rpc.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/core_rpc.rs) provide secure RPC URL resolution and bearer token authentication via `apply_auth()`.
- The **`cdp`** package enables Chrome DevTools Protocol integration for controlling CEF webviews, capturing DOM snapshots, and simulating input events.
- **`cef_profile`** manages Chromium cache directories and user profiles with security validations to prevent path-traversal attacks during cache purges.

## Frequently Asked Questions

### What is the purpose of the core_process module in OpenHuman?

The `core_process` module manages the OpenHuman core as an embedded Tokio task within the Tauri application. It handles the entire lifecycle including generating secure RPC tokens with `generate_rpc_token()`, managing port allocation with `default_core_port()`, and ensuring idempotent startup through `ensure_running()`.

### How does the cdp module interact with Chromium Embedded Framework webviews?

The `cdp` module implements a Chrome DevTools Protocol client that connects to CEF webviews via WebSocket connections defined in [`conn.rs`](https://github.com/tinyhumansai/openhuman/blob/main/conn.rs). It enables the Tauri host to enumerate targets, create sessions through `Session::new()`, capture DOM snapshots using `DOMSnapshot::capture()`, and inject input events for automating interactions with external providers.

### Why does OpenHuman use bearer tokens for RPC authentication instead of other methods?

OpenHuman uses in-memory bearer tokens generated by `core_process` and applied via `core_rpc::apply_auth()` to eliminate command-line exposure and prevent unauthorized access to the embedded core's JSON-RPC endpoint. The 256-bit random tokens are passed directly to the core during `run_server_embedded_with_ready`, ensuring only the owning Tauri process can authenticate requests.

### How does cef_profile prevent security issues during cache deletion?

The `cef_profile` module implements strict path validation through `is_trusted_queued_purge_path` before executing any cache deletion. The `PendingCefPurgeState` queue ensures deletions occur only on application restart, and all paths are validated against the expected `…/users/<id>/cef` structure to prevent path-traversal attacks that could target arbitrary filesystem locations.