# Debugging Workflow for the OpenHuman Rust Core Sidecar Process

> Debug the OpenHuman Rust core sidecar process effectively. Use RUST_LOG, RUST_BACKTRACE, scripts, or LLDB/GDB to trace JSON-RPC requests with structured logs.

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

---

**Set `RUST_LOG=debug` and `RUST_BACKTRACE=1`, then use the convenience scripts in `scripts/debug/` or attach LLDB/GDB to the `openhuman-core` binary to trace JSON-RPC requests through the structured `tracing` logs.**

The OpenHuman project (`tinyhumansai/openhuman`) relies on a pure-Rust sidecar binary (`openhuman-core`) that executes as a background service outside the browser sandbox, exposing JSON-RPC endpoints to the desktop UI. Because this core sidecar process operates as a standard native binary rather than a web-based component, debugging it follows established Rust tooling conventions augmented by OpenHuman-specific observability hooks. This guide details the recommended debugging workflow, referencing exact source files where each behavior is implemented.

## Environment Configuration for Tracing

Before launching the sidecar, configure the environment variables that control log verbosity and error reporting.

### Setting Log Levels with RUST_LOG

The sidecar uses the `tracing` crate for structured logging. To capture detailed execution flow, export `RUST_LOG=debug` (or `trace` for maximum granularity) and `RUST_BACKTRACE=1` to capture full stack traces on panics. These variables activate the subscriber initialization logic found in [`src/core/observability.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/observability.rs), which configures the formatting and filtering of log output.

For machine-readable logs suitable for automated analysis, the sidecar emits JSON-structured output to STDOUT when logging is enabled, prefixed with `[core]` as defined in [`src/core/logging.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/logging.rs).

### Isolating Workspace State

To ensure deterministic, repeatable debugging sessions, override the default workspace directory using `OPENHUMAN_WORKSPACE`. The sidecar reads this environment variable in [`src/openhuman/workspace/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/workspace/ops.rs) to determine where persisted state lives. Pointing it to a temporary directory prevents contamination between runs:

```bash
export OPENHUMAN_WORKSPACE=$(mktemp -d)

```

## Launching the Sidecar with Verbose Tracing

The binary entry point in [`src/main.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/main.rs) performs three critical setup operations before handing control to the core logic: initializing Sentry for error reporting, loading environment variables, and dispatching CLI arguments to `openhuman_core::run_core_from_args`.

Start the sidecar with verbose logging enabled:

```bash
RUST_LOG=debug RUST_BACKTRACE=1 cargo run --bin openhuman-core -- serve

```

When running at the `debug` level, internal events emit spans via `tracing::instrument` macros located throughout `src/openhuman/*`, allowing you to correlate log entries with specific function entry and exit points in the source.

## Interactive Debugging with Native Tools

Because `openhuman-core` compiles to a standard ELF binary, you can attach conventional native debuggers. The most common pattern uses LLDB (or GDB) while preserving the environment variables required for trace output:

```bash
RUST_LOG=debug RUST_BACKTRACE=1 lldb -- target -- ./target/debug/openhuman-core serve

```

Set breakpoints on public functions decorated with `#[instrument]` attributes; the debugger will halt at the corresponding source lines while the `tracing` subscriber continues emitting contextual span information to the terminal.

## Using the Debug Scripts for Rapid Iteration

The repository ships convenience wrappers that automate environment setup, log capture, and timestamping. These scripts represent the recommended path for iterative debugging without manually configuring `RUST_LOG` for each invocation.

- **[`scripts/debug/unit.sh`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/debug/unit.sh)**: Wraps unit test execution, capturing logs and exit codes for post-run analysis.
- **[`scripts/debug/rust.sh`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/debug/rust.sh)**: Provides a pre-configured environment for running the sidecar binary with full tracing enabled and output tee'd to log files.

Both scripts handle the boilerplate of setting `RUST_LOG=debug` and `RUST_BACKTRACE=1`, ensuring consistent observability across debugging sessions.

## Testing the JSON-RPC Interface

The sidecar only executes domain logic when receiving JSON-RPC requests. To trigger code paths and observe the resulting traces, exercise the RPC surface using `curl` or the `coreRpcClient` helper from the UI.

### Manual RPC Invocation

Fire a request to the local endpoint and watch the logs for the corresponding `rpc` span:

```bash
curl -s http://127.0.0.1:7788/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"core.ping","params":{},"id":1}'

```

The request handler in [`src/core/jsonrpc.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/jsonrpc.rs) logs entry into the `core.ping` method, emitting a structured trace that includes the method name and request ID.

### Automated End-to-End Testing

For regression testing and systematic debugging, use the harness in [`tests/json_rpc_e2e.rs`](https://github.com/tinyhumansai/openhuman/blob/main/tests/json_rpc_e2e.rs). This test spins up a mock backend, starts the sidecar process, asserts JSON-RPC responses, and captures the sidecar’s log output for failing assertions. When a test fails, the harness provides both a Rust backtrace and the complete sidecar log stream for the failing case.

## Inspecting Internal Event Flows

Many core operations communicate via the typed `event_bus` defined in [`src/core/event_bus/bus.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/event_bus/bus.rs). To observe asynchronous domain events such as `DomainEvent::CronDeliveryRequested` during debugging, either:

- Add temporary `event_bus::subscribe_global` listeners in your local checkout, or
- Set `RUST_LOG=trace` to see event emissions in the log stream.

This approach is particularly useful when tracing multi-step workflows that span multiple async tasks within the sidecar.

## Verifying Error Reporting and Scrubbing

The sidecar integrates Sentry for error reporting, configured in [`src/main.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/main.rs) (lines 48–70). Before sending crash reports, it executes a `before_send` closure that redacts secrets and sensitive data.

To verify that scrubbing behaves correctly during debugging:

1. Set `RUST_LOG=trace` to capture Sentry SDK internals.
2. Trigger an error condition or panic.
3. Inspect the logs to confirm the `before_send` closure executed and removed sensitive fields from the payload.

## Summary

- **Configure the environment** with `RUST_LOG=debug`, `RUST_BACKTRACE=1`, and `OPENHUMAN_WORKSPACE=$(mktemp -d)` to enable tracing and isolate state.
- **Launch via [`src/main.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/main.rs)**, which initializes Sentry and dispatches to `run_core_from_args`.
- **Attach native debuggers** (LLDB/GDB) directly to the binary; the `tracing::instrument` macros provide source correlation.
- **Use the helper scripts** [`scripts/debug/unit.sh`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/debug/unit.sh) and [`scripts/debug/rust.sh`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/debug/rust.sh) for automated log capture.
- **Trigger execution** by calling JSON-RPC methods against [`src/core/jsonrpc.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/jsonrpc.rs) and monitor the structured output.
- **Inspect the event bus** in [`src/core/event_bus/bus.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/event_bus/bus.rs) for internal async workflows.
- **Verify Sentry scrubbing** logic in [`src/main.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/main.rs) when testing error reporting.

## Frequently Asked Questions

### How do I enable verbose logging for the OpenHuman sidecar?

Export `RUST_LOG=debug` (or `trace` for more detail) and `RUST_BACKTRACE=1` before starting the process. The `tracing` subscriber configured in [`src/core/observability.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/observability.rs) will emit structured logs to STDOUT, including function spans from `#[instrument]` macros throughout the codebase.

### Can I use a native debugger like GDB with the Rust core?

Yes. Because `openhuman-core` is a standard Rust ELF binary, you can start it under LLDB or GDB while keeping the `RUST_LOG` and `RUST_BACKTRACE` environment variables set. The debugger will recognize source locations from the `tracing::instrument` annotations, allowing you to step through code while log spans provide context.

### How do I reset the sidecar state between debugging sessions?

Set the `OPENHUMAN_WORKSPACE` environment variable to a temporary directory (e.g., `export OPENHUMAN_WORKSPACE=$(mktemp -d)`). The workspace module in [`src/openhuman/workspace/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/workspace/ops.rs) reads this variable to determine persistence paths, ensuring each run starts with a clean state.

### Where can I find automated tests for the JSON-RPC interface?

The end-to-end test suite in [`tests/json_rpc_e2e.rs`](https://github.com/tinyhumansai/openhuman/blob/main/tests/json_rpc_e2e.rs) spins up the sidecar against a mock backend, executes JSON-RPC calls, and validates responses. When tests fail, the harness outputs the sidecar’s complete log stream and a Rust backtrace, making it ideal for debugging RPC handler logic in [`src/core/jsonrpc.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/jsonrpc.rs).