The sensor Raspberry Pi in the lab has stopped reporting. Nobody is near it, and the dashboard has been flat for an hour.
Troubleshooting a remote machine usually means getting a session on it, working out which logs matter, and piecing together what went wrong. With noBGP connected to Claude, you can describe the symptom and work through the problem in the conversation.
Claude can check the machine, read the relevant logs, find the likely cause, apply a fix, and verify that it worked. This walkthrough follows that sequence, using the lab Pi as the example.
Before you start
The machine needs the noBGP agent installed, and your assistant needs noBGP MCP connected. If you have not set that up, start with how to run commands on your machines from Claude.
Step 1: Describe the symptom
Start with what you observed, not a guess at the cause:
The sensor Pi in the lab stopped reporting about an hour ago. Find out what's wrong with it.
Including when it started and what "working" normally looks like helps Claude narrow the search.
Step 2: Confirm the machine is reachable
Claude first checks whether the node is online, using network_directory.
If the machine is offline, remote troubleshooting stops here. The cause may be power, the network, or the machine itself, and someone may need to check it in person. You can ask Claude to watch for the machine to come back, since presence_subscribe reports nodes going online and offline.
If the machine is online, the operating system and the noBGP agent are running, which already rules out several causes.
Step 3: Read the logs
Next, Claude looks at what the failing software recorded. It runs commands to read the service's status and recent log lines, for example:
systemctl status sensor-agent
journalctl -u sensor-agent -n 50 --no-pager
In our example, the logs show two important lines:
ERR serial /dev/ttyUSB0: no such device
sensor-agent exited (1)
If the problem looks like connectivity to noBGP itself, the node_logs tool reads the noBGP agent's own log on that machine.
Step 4: Find the cause
Claude interprets what it found. Here, the service lost its USB serial connection to the sensor, and the agent crashed when the device disappeared.
A good diagnosis separates evidence from inference. The log shows the device was missing. A loose cable is a likely explanation, but nothing on the machine can prove it. Ask Claude to be explicit about which is which.
Step 5: Apply the fix
With a cause identified, Claude can propose a fix. Restarting the service is a reasonable first step:
sudo systemctl restart sensor-agent
Restarting a system service requires elevated access. noBGP only allows it when two gates agree:
- Your organization role is Owner or Admin. Members cannot request elevated execution.
- The machine's
allow-adminpolicy permits work to run as root.
If either gate says no, the command is refused rather than run as a different user. Read the node access control guide.
For anything more disruptive, such as rebooting, changing configuration, or deleting data, ask Claude to explain the change and wait for your approval first.
Step 6: Verify the fix
A restart that succeeds is not the same as a fixed problem. Ask Claude to confirm with evidence:
- The service reports
active (running). - New log lines show the device connected and readings flowing.
- The symptom you started with, the missing reports, has resolved.
In our example, the service is running and readings are flowing again. Claude's summary should include the cause, what it changed, and what to follow up on. Here, that means checking the USB cable next time someone is in the lab, because a restart does not fix a loose connection.
A troubleshooting brief you can reuse
For repeat problems, give Claude the whole process in one request:
The [service] on [machine] has stopped working since [time]. Check the machine is online, read the service status and its recent logs, and tell me the likely cause with the log lines that support it. Propose a fix and wait for my approval before changing anything. After the fix, verify the service is healthy and show me the evidence.
When remote troubleshooting is not enough
Some problems need hands on the hardware: a failed disk, a disconnected cable, or a machine that will not power on. Remote troubleshooting still helps in those cases, because it narrows down what the person on site needs to check.
Frequently asked questions
Can Claude troubleshoot a machine that is offline?
No. Commands need the machine and its noBGP agent to be running. Claude can confirm the machine is offline and notify you when it reconnects.
What is the difference between node_logs and the service's logs?
node_logs reads the noBGP agent's own log. For your application or system services, Claude reads their logs by running commands such as journalctl on Linux.
Will Claude change things without asking?
That depends on your client's tool-approval settings and how you phrase the request. Asking Claude to propose changes and wait for approval keeps you in control of every change.
Can I stop Claude from running commands as root on a machine?
Yes. Set the node's allow-admin policy to false, and commands will run as an unprivileged account instead.
Next time something breaks
Connect the machines you would otherwise have to travel to, and try the brief above the next time one of them misbehaves.
Set up noBGP with Claude to get started.
