rye.ai
supervision docsTroubleshootingv

Rye supervision workbench

Troubleshooting

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

route
/docs/reference/troubleshooting
control point
external supervisor
signals
proxy / policy / audit
01Claude / Codex
02Rye local proxy
03policy + audit
04model API
Start free trialView pricing

Diagnostic order

Start with the runtime path. 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.

agent
Claude / Codex
supervisor
Rye local proxy
decision
policy + audit
egress
model API
Rye docs describe the runtime boundary: process, proxy, policy, provider, and audit trail.
command trace

Primary local health check

healthy
rye doctor

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

Recovery loop

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