Debugging Workflow for the OpenHuman Rust Core Sidecar Process

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

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 to determine where persisted state lives. Pointing it to a temporary directory prevents contamination between runs:

export OPENHUMAN_WORKSPACE=$(mktemp -d)

Launching the Sidecar with Verbose Tracing

The binary entry point in 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:

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:

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: Wraps unit test execution, capturing logs and exit codes for post-run analysis.
• 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:

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 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. 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. 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 (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, 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 and scripts/debug/rust.sh for automated log capture.
• Trigger execution by calling JSON-RPC methods against src/core/jsonrpc.rs and monitor the structured output.
• Inspect the event bus in src/core/event_bus/bus.rs for internal async workflows.
• Verify Sentry scrubbing logic in 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 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 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 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.

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