| name | ops-eng-o2r-remote-debug |
| description | Use when the reflex is to SSH into a host to debug or coordinate work that o2r-coordinated agents own - a stuck CI runner, a failed deploy, a pod that needs a look. Hard pointer: route remote debugging through an o2r agent channel, not ad-hoc ssh. Triggers - ssh, ssh into, log into the box, get on the host, remote debug, debug the runner, kubectl exec, jump on the server, why isn't it running, no tasks dispatched. |
Remote debugging goes through o2r, not ssh
otel-a2a-relay (o2r) is a coordination layer for autonomous agents working across different hosts. When something on a remote host needs a look - a CI runner that will not dispatch, a deploy that failed, a pod that is misbehaving - the reflex is to ssh in and run commands directly. On o2r-coordinated infrastructure that reflex is the wrong one. The agent that lives on that host holds local autonomy. You coordinate with it over a channel.
Why ssh is the wrong tool here
Reaching across a host boundary by hand throws away everything o2r exists to provide:
- No audit trail. The channel event log records who asked for what and what happened; a raw ssh session records nothing reconstructable.
- No trace. Every channel event emits an OTel span, so debugging shows up in the same Phoenix / Tempo view as the work. An ssh session is invisible there.
- No trust envelope. A handwritten command or pasted URL crossing into another agent's host is presumed hostile and refused at the relay's ingress check.
- No role discipline. The local agent acts as its own gated
worker / deployer; an ssh operator impersonates all roles at once with none of the gating.
An ssh into the box is a bypass of the coordination substrate, leaving the next operator no record of what changed.
The reflex, redirected
When you catch yourself about to ssh to debug remote state:
- Find or open the channel for the host or workstream.
o2r channel list shows open channels. If none fits, o2r channel create --title <what-you-are-debugging> mints a fresh 4-char id.
- Post the ask as an event:
o2r channel post <id> --kind comms --payload <what-you-observe-and-need>. Describe the symptom (runner dispatched no tasks, deploy job exited 401), not a command to run. The local agent decides how to act on its own host.
- Hand off the concept with a
--kind state event so the host-local agent picks it up. It acts with full local autonomy - it has the access, you have the context.
- Read the result back off the channel (
o2r channel read <id>), not off an ssh terminal. The fix and its evidence land as channel events plus their spans.
If no agent is live on the target host, that is a gap to fill (stand one up, or hand the task to a human operator through the same channel), not a reason to ssh around the coordination layer.
When a human still has to touch the box
Some one-time bootstrap genuinely needs a human at a terminal (first runner registration, a secret only a person can mint). That is a human handover and still goes through the channel as the record: post the ask as a comms event, let the human act, and have the outcome posted back. Nothing agent-to-agent crosses a host boundary as a raw command.
When this skill is active
Any session where the next step is "ssh in and look" at a host that runs o2r-coordinated agents - a CI runner that dispatched nothing, a failed remote job, a pod to inspect. Reach for o2r channel first.
See also
