How to Debug the Rust Core When OPENHUMAN_CORE_REUSE_EXISTING Is Set

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, 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.

• Inspect the log output: Look for the specific warning at line 86 in 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):

# 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:

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 use EnvGuard::set("OPENHUMAN_CORE_REUSE_EXISTING", "1") to confirm the logic:

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:

# .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:

$ 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:

#[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 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 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). If you do not see this message, the flag is not being read correctly or the code is hitting a different execution path.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}