# How to Debug the Rust Core When OPENHUMAN_CORE_REUSE_EXISTING Is Set

> Debug Rust core with OPENHUMAN_CORE_REUSE_EXISTING enabled. Learn to manually verify external listeners when bypassing embedded core spawn for efficient troubleshooting.

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

---

**Setting `OPENHUMAN_CORE_REUSE_EXISTING=1` bypasses the embedded core spawn and attaches to whatever service is already listening on the RPC port, requiring you to verify the external listener manually instead of relying on the automatic lifecycle management.**

The `OPENHUMAN_CORE_REUSE_EXISTING` environment variable toggles a legacy fast-path in the **tinyhumansai/openhuman** repository that alters how the Tauri application manages the Rust core lifecycle. When this flag is enabled, the application skips its normal port-identification routine and assumes an external process is already handling the RPC server. Understanding this behavior is essential when debugging connectivity issues or attaching a standalone debugger to the core binary.

## Understanding the OPENHUMAN_CORE_REUSE_EXISTING Flag

### What the Flag Does

In [`app/src-tauri/src/core_process.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/core_process.rs), lines 18–20 document the purpose of this variable: it restores the old "attach-to-whatever-is-listening" behavior specifically for external debugging scenarios. When `reuse_existing_listener_enabled()` returns `true` (lines 84–90), the code skips the stale-listener detection and returns early with a warning log. This means the embedded core **does not** spawn, and the `run_server_embedded_with_ready` call is bypassed entirely.

### How It Differs from the Default Flow

The normal startup path, implemented in `ensure_running()` (lines 37–84), actively probes the configured RPC port, identifies the listening process, and optionally terminates stale OpenHuman processes to prevent version drift. When `OPENHUMAN_CORE_REUSE_EXISTING=1` is set, the code jumps to the early `return Ok(())` branch at line 86, emitting the warning: `"[core] OPENHUMAN_CORE_REUSE_EXISTING=1 — attaching to whatever is listening…"`. The UI continues assuming a core is present, but the in-process server never starts.

## Debugging Steps When the Flag Is Enabled

Follow this structured approach to diagnose issues when the reuse flag is active:

- **Confirm the flag is read**: Verify that `reuse_existing_listener_enabled()` returns `true`. This function simply reads the environment variable and is located in [`core_process.rs`](https://github.com/tinyhumansai/openhuman/blob/main/core_process.rs).

- **Inspect the log output**: Look for the specific warning at line 86 in [`core_process.rs`](https://github.com/tinyhumansai/openhuman/blob/main/core_process.rs). If you see `"[core] OPENHUMAN_CORE_REUSE_EXISTING=1 — attaching to whatever is listening…"`, the early-exit path is active.

- **Validate the listener**: Use OS tools to identify what binary is bound to the RPC port (default `127.0.0.1:8000`):

```bash

# macOS/Linux

lsof -iTCP:8000 -sTCP:LISTEN

# Linux alternative

ss -ltnp | grep 8000

```

- **Force a fresh core spawn**: Unset the variable or set it to `0` and restart the Tauri app. The normal identification and takeover logic (lines 92–115) will run, spawning the embedded server.

- **Run the core in isolation**: Start the core binary directly with the variable set to observe the same early-exit behavior:

```bash
OPENHUMAN_CORE_REUSE_EXISTING=1 cargo run --bin openhuman-core -- serve

```

- **Unit-test verification**: Execute the Rust test suite to validate the early-exit path. The tests in [`app/src-tauri/src/core_process_tests.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/core_process_tests.rs) use `EnvGuard::set("OPENHUMAN_CORE_REUSE_EXISTING", "1")` to confirm the logic:

```bash
pnpm test:rust

```

## Typical Debugging Workflow

### 1. Configure the Environment

Set the flag in your development environment. The Tauri layer typically reads from `.env` or `.env.local`:

```bash

# .env.local

OPENHUMAN_CORE_REUSE_EXISTING=1

```

### 2. Launch the Application

Start the desktop app with `pnpm dev:app`. The Tauri console will emit the warning mentioned above, confirming the early-exit path is active.

### 3. Verify the Port Ownership

Check which process actually owns the port. If a stale `openhuman-core` binary from a previous run is listening, you may need to terminate it before attaching the UI:

```bash
$ lsof -iTCP:8000 -sTCP:LISTEN
COMMAND         PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
openhuman-core 1234 user    7u  IPv4  12345      0t0  TCP localhost:8000 (LISTEN)

```

### 4. Handle Connection Errors

If the attached process is **not** the OpenHuman core, the UI will encounter connection errors. The frontend expects a JSON-RPC endpoint implementing the OpenHuman schema; a non-core service will cause 401/404 errors visible in the browser dev console. Always verify the attached process implements the current schema by checking the `/schema` endpoint.

### 5. Toggle the Flag Off

Unset the variable to force the normal startup path. You should now see logs indicating `"[core] ensure_running: embedded task already running…"` followed by the "spawning embedded in-process core server" message.

### 6. Run Targeted Unit Tests

Validate the behavior programmatically using the test suite:

```rust
#[tokio::test]
async fn reuse_existing_early_exit() {
    let _override = EnvGuard::set("OPENHUMAN_CORE_REUSE_EXISTING", "1");
    let core = CoreProcessHandle::new(8000);
    // `ensure_running` should return Ok without spawning a task.
    core.ensure_running().await.unwrap();
}

```

## Why This Mode Matters

**Stale listener recovery**: When the flag is unset, the core actively kills stale OpenHuman listeners to avoid version drift. Enable the flag only when you intend to manage the core process manually.

**External debugging**: This mode lets developers attach a separate `openhuman-core` process (e.g., running under `gdb` or `lldb`) to the UI without the embedded core interfering. This is the primary use case for the legacy fast-path.

**Potential pitfalls**: Because the UI still believes a core is present, any mismatch in the RPC schema version will surface as obscure frontend errors. Always verify that the manually started core matches the UI's expected API contract.

## Summary

- **`OPENHUMAN_CORE_REUSE_EXISTING=1`** enables a legacy fast-path in [`app/src-tauri/src/core_process.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/core_process.rs) that skips the embedded core spawn.
- When enabled, the code exits early from `ensure_running()` at line 86 without starting the in-process server.
- **Debugging requires manual verification** of the RPC port listener using tools like `lsof` or `ss` to ensure the correct binary is attached.
- **Run the core in isolation** using `cargo run --bin openhuman-core` with the flag set to debug the standalone binary separately from the Tauri host.
- **Unit tests** in [`core_process_tests.rs`](https://github.com/tinyhumansai/openhuman/blob/main/core_process_tests.rs) validate the early-exit behavior and confirm that `CURRENT_RPC_TOKEN` is not set in this mode.
- To return to normal behavior, unset the variable and restart the application to trigger the standard identification and takeover logic.

## Frequently Asked Questions

### What happens if I set OPENHUMAN_CORE_REUSE_EXISTING=1 but nothing is listening on the port?

The Tauri application will attempt to connect to the configured RPC port regardless. If no process is listening, the UI will encounter connection refused errors. The application does not validate the listener's existence when the flag is set; it simply skips the spawn logic and assumes an external service is available.

### How do I switch back to the embedded core after using this flag?

Unset the environment variable or set it to `0`, then fully restart the Tauri application. The normal startup sequence in `ensure_running()` will execute, performing stale-listener detection and spawning the embedded core via `run_server_embedded_with_ready`.

### Can I use this flag in production builds?

While technically possible, this flag is intended for development and debugging workflows. Using it in production bypasses the built-in process management and version drift protection, potentially leaving the UI connected to an incompatible or stale core process.

### Where is the warning message logged when the flag is active?

The warning `"[core] OPENHUMAN_CORE_REUSE_EXISTING=1 — attaching to whatever is listening…"` appears in the Tauri console output (lines 86 in [`app/src-tauri/src/core_process.rs`](https://github.com/tinyhumansai/openhuman/blob/main/app/src-tauri/src/core_process.rs)). If you do not see this message, the flag is not being read correctly or the code is hitting a different execution path.