Rye supervision workbench

Troubleshooting

Diagnose missing traffic, CA trust failures, authentication issues, and policy behavior in Rye.

Diagnostic order

Start with Rye's local health checks. Every local failure usually lands in one of four places: the agent process was not launched through Rye, the proxy is not active, CA trust is missing, or policy rejected the request.

command trace

Primary local health check

healthy

rye doctor

auth signed in
daemon running
proxy listening
CA trust installed
traffic forwarding

rye doctor should be the first command for local issues. It checks auth, daemon state, proxy routing, CA trust, and connectivity before you chase tool-specific behavior.

Failure signatures

diagnostic runbook

Follow the first matching signal, then verify with `rye doctor`.

operator mode

inspect

No traffic appears

The usual cause is process timing. If Claude Code, Codex, Cursor, or another agent started before Rye, it may keep using its original environment.

check

rye status
rye history --last 15m

expected signal

proxy.status = active traffic.count > 0 agent.process = launched after rye up

fix

Restart the agent through Rye: rye wrap claude Most agents read proxy variables only during process startup.

blocked

TLS or certificate errors

TLS failures mean the model client does not trust Rye's local inspection certificate for the intercepted provider host.

check

rye up --install-ca --intercept-patterns openai.com,anthropic.com,claude.com,chatgpt.com,cursor.com,windsurf.com

expected signal

ca.trust = installed intercept.host = matched agent.restart = required

fix

Install the CA, then fully restart the supervised agent process so it reloads trust settings.

blocked

Requests are blocked

A block is a successful policy decision, not a proxy failure. Read the decision record before changing local configuration.

check

rye history --last 15m

expected signal

decision = blocked matched_rule = visible request.destination = provider host

fix

Inspect the matched policy in the audit trail. Blocks usually come from protected hosts, model rules, file-path rules, secret patterns, or request-size limits.

inspect

Device is rejected

Device rejection means Rye can see the local runtime, but the workspace does not trust this workstation for supervised traffic.

check

rye auth login

expected signal

user.identity = refreshed workspace = selected device.status = authorized

fix

If the device was revoked, a workspace administrator must authorize it again before supervised traffic is allowed.

Policy evidence

Command not found or shims bypassed

Open a new terminal after installation. For a user-local install, confirm both the binary directory and the shim directory are on PATH:

exec:bash

export PATH="$HOME/.rye/shims:$HOME/.local/bin:$PATH"
rye version
rye app doctor

Use your actual binary directory if you installed with a custom prefix or --system. If the agent was installed after Rye, create its shim with rye app wrap claude or rye app wrap codex.

Other shell tools fail when Rye is stopped

Older installations may have added HTTP_PROXY, HTTPS_PROXY, or NODE_EXTRA_CA_CERTS to shell startup files. Inspect those files and remove stale Rye-specific exports if you use wrapped sessions. Preserve settings required by another proxy or certificate setup. Open a new terminal afterward.

The installer and default rye doctor --fix no longer add global proxy exports. A missing global proxy is expected with app shims.

Wrapped agent will not exit

A single Ctrl+C can cancel an operation inside Claude Code or Codex without exiting the agent. In Rye 0.9.1 and later, three Ctrl+C presses within three seconds send SIGTERM to the child process group; five rapid presses escalate to SIGKILL. Forced termination can interrupt unfinished work.

Rye 0.9.2 fixes shims hanging after an agent exits successfully. If you still see that behavior, check rye version and update Rye. For supervisor diagnostics, run:

exec:bash

RUST_LOG=rye=debug rye wrap claude

Recovery loop

Run rye doctor.
Confirm the agent was launched after Rye.
Check rye history --last 15m.
Inspect the policy decision if the request was blocked.
Restart the supervised agent after any proxy, CA, or environment change.