Troubleshooting

What to check when remote debugging does not come up cleanly

RoboTunnel should give you a failure path as clear as its golden path. Start with the quick checks below, then use the agent-side WebRTC preflight script when you need to verify control-plane readiness.

What failed?

Most first-session failures fall into one of two buckets:

  • Control-plane failure: the agent cannot fetch auth state, TURN credentials, or signaling connectivity.
  • Endpoint/runtime failure: the transport comes up, but the robot-local debug endpoint is not usable yet.
webrtc-preflight.sh is for the first bucket. It checks whether the control plane is ready; it does not guarantee that Foxglove, RViz, or other robot-local bridges are healthy.

Quick checks

1. Confirm the robot is online

Run robotunnel list first. If the robot is offline, do not start with WebRTC tuning.

2. Confirm the session exists

Use robotunnel debug status <robot> after debug start so you know whether the failure happened before or after session creation.

3. Separate bridge issues from transport issues

If robotunnel debug open warns that the Foxglove bridge is unreachable, that points to a robot-local endpoint problem rather than TURN or signaling setup.

4. Escalate only when needed

If you need lower-level transport control or manual route inspection, use the expert robotunnel connect path after the checks above.

Agent-side WebRTC preflight

The recommended low-level self-check is the script shipped in the agent repository:

./scripts/webrtc-preflight.sh \
  --api-url https://api.robotunnel.io \
  --api-key <robot_api_key> \
  --robot-id <robot_uuid>

This script currently checks the same control-plane paths used by the live implementation:

  • GET /api/agent/authorized-keys
  • GET /api/turn-credentials?robot_id=...
  • WebSocket upgrade for /api/signal/<robot_id>?role=agent
Treat this as a control-plane preflight. Passing it means auth, TURN issuance, and signaling upgrade look healthy. It does not prove end-to-end attach or robot-local bridge readiness.

What each failure usually means

  • authorized-keys fails: check registration state, robot_api_key, and the platform base URL configured on the agent.
  • turn-credentials fails: check TURN configuration, agent auth, and whether the request is using the correct robot_id.
  • signal upgrade fails: check WebSocket reverse proxying, TLS termination, header forwarding, and the robot API key used for role=agent.

When to switch to CLI or the next check

If WebRTC preflight passes but robotunnel debug open still fails, move up a layer:

  • Read the warning from debug open about Foxglove bridge or endpoint health.
  • Use robotunnel debug status <robot> to confirm the session payload and endpoint type.
  • Use the expert robotunnel connect path when you need route-level troubleshooting or manual inspection.

These checks are complementary: agent-side preflight validates the control plane, while debug open warnings help validate the robot-local endpoint.