Runtime 0.8.12
Troubleshoot a first session
Start with the symptom, check the evidence and apply the smallest fix. These checks describe released runtime 0.8.7, including the capture limits that remain.
No captured session
Check: rh status, rh doctor, rh harness status, the tool’s capture log and rh capture spool. The quickstart shows how to query /api/sessions with the owner token. The /healthz sessions field still reports 0; use the sessions API as your capture counter.
Fix: If the node is down, start it on demand with rh local --ensure, or use your configured service. Connect the intended tool and run a new session. The next hook delivers saved spool entries; fix disk space or permissions if a batch could not be saved. Requeue dead letters only after addressing authentication. Capture details.
Node disappears after reboot or service loops
Check: rh service status and rh service logs. The current Linux installer sets up an enabled service when a systemd user session is usable; its output says whether startup is at login or at boot. Older installs, macOS, no-systemd environments and --no-service installs may still use a detached node. An owner-lock error usually means a second node is still running. If the journal says Unable to locate executable … rh (deleted), an update run by 0.8.4 rewrote the unit (fixed in 0.8.5); rh service restart repairs it.
Fix: For an older Linux install or a looping unit beside a detached node, rerun the installer to hand over to the service. In 0.8.4, service start hands over a running detached node without the old restart loop. The service guide also gives an explicit initialize, stop, wait and start sequence for manual recovery. If an existing service stopped unexpectedly, inspect journalctl --user -u rivethub -n 50. For missing env settings, rh service restart repairs an older generated unit’s EnvironmentFile directive in 0.8.4; review any unit edited by hand yourself. Follow keeping the node running for the sequence and lingering.
Browser page or account sign-in
A site-installed 0.8.4 node has no browser UI. rh open says so, and GET / answers 200 with an explanation. Use the authenticated sessions API and MCP to verify capture. Desktop remains a preview with no release.
Node account sign-in now uses the cloud’s device-code flow. Approve the code in your browser. Sharing uses rh share login; app account sign-in is not a prerequisite.
No model or no capture history
No model is needed for capture and keyword recall. In 0.8.4, ordinary commands no longer print memory.models is not set; rh doctor explains the missing model once. Configure model endpoints only for the extra memory features you want.
Without an embedding endpoint, memory_search begins “Keyword search. Meaning-based search needs an embedding endpoint.” with no warning mark. rh harness status shows “nothing captured yet” or the last capture time. rh memory queue-status is for a Postgres datahub. On standalone SQLite, it now says This command needs a datahub (Postgres). instead of asking you to set a database variable. Do not add a Postgres URL to work around it.
Codex or OpenCode does not capture
Codex: Open Codex in a terminal after connecting. When it says “Hooks need review”, choose “Trust all and continue”. Until you trust the hooks, codex exec silently skips them. Connecting again can require another review. From rh 0.8.6, rh harness status says whether Codex trusts the hooks and rh harness connect codex says what to answer.
OpenCode: OpenCode 2 (@opencode/cli) is the supported OpenCode. OpenCode 1.x is captured from rh 0.8.6: update rh, then run rh harness connect opencode again; rh harness status says when the installed plug-in is out of date. On older rh, 1.x refused the plug-in (opencode run --print-logs shows failed to load plugin). OpenCode 1.x gets no further work.
From 0.8.4, rh harness connect dsh sets up DeepSeek Harness capture and recall. See capture for the per-tool details.
Receive imports nothing, or update says already newer
Check: Exit 3 with a held report means receive’s safety checks found something; review decisions in receiving. A stable update resolving an older version is safely skipped; choose the beta channel deliberately in upgrading.
For unresolved problems, ask for help or report an issue. Include version, platform, backend, exact symptom, redacted doctor output and relevant log lines. Read every line before posting; remove tokens, connection strings and session content.
Need a hand?
Check the troubleshooting guide or ask with a redacted report.