Troubleshooting a Disconnected Device
Phase 10 — Ongoing Operations · OpenFrame Onboarding
A device shows OFFLINE and you can't remote in. Before you assume the worst, OpenFrame gives you enough on the device's detail page to figure out why — and most causes are mundane. This guide is the systematic walk-through.
First, read the signals
Open the device from Devices. A disconnected machine shows:
- An OFFLINE badge at the top.
- Remote Control and Remote Shell buttons greyed out — they need a live connection, so this confirms the client isn't reachable.
- An Updated / last-contact timestamp telling you when it last checked in.
The gap between "last seen" and now is your first clue: minutes ago suggests a blip; days ago suggests the machine is off or the client is down.
Narrow it down with the Agents tab
Open the Agents tab. Each agent — Fleet, MeshCentral, Tactical — has its own Status and Last seen. Two patterns to read:
- All three offline, same last-seen time — the whole client lost contact at once. Usually the machine is powered off/asleep, off the network, or the OpenFrame service stopped.
- One agent offline, others online — a single component is stuck. The updater service usually repairs this on its next cycle; the others still work in the meantime.
Common causes & where to fix them
Recovery happens on the endpoint — the console shows you the problem, the machine is where you solve it:
- Machine is off or asleep — the simplest and most common. Confirm it's powered on and awake.
- OpenFrame service stopped — on Windows the service is set to auto-restart (SCM), but a disabled or crashed service won't reconnect. Restart it on the machine.
- Network / firewall — the client must reach the OpenFrame server outbound. A new firewall rule, proxy change, or DNS issue at the site will cut it off. Verify connectivity from the endpoint.
- Agent token / enrollment — if the device was re-imaged or its enrollment token rotated, it may need to re-enroll. Reinstall the agent to re-establish trust.
- Client badly out of date — a stalled updater can leave a device unable to reconnect; reinstalling pulls a clean, current client.
When it won't come back
If you've ruled out power, network, and service state and it still won't reconnect, reinstall the OpenFrame agent on the machine (Phase 2). That re-establishes enrollment and pulls current versions in one step.
For a device that's genuinely retired, use the device "…" menu → Archive Device (reversible record-keeping) or Delete Device to remove it. Don't delete a machine you're still troubleshooting — archive it if you want it out of your active list without losing history.
Quick checklist
- Confirmed OFFLINE badge and checked the last-seen timestamp
- Opened Agents tab to see which agents are down and when
- Verified the machine is on, awake, and on the network
- Checked the OpenFrame service is running (restart if needed)
- Ruled out firewall / proxy / DNS changes at the site
- Reinstalled the agent if enrollment or version was the issue
- Archived rather than deleted anything still under investigation
What's next
That's the technical side of keeping the fleet healthy. The last operational piece is the commercial one: Billing & Subscription Management.
Based on OpenFrame v0.9.19. Connection behavior depends partly on the endpoint OS, network, and agent state — what's on the machine and in your console wins. This expands on Deploy at Scale and the agent install guides in Phase 2.
