Admiral Support Team: Device Troubleshooting
This page describes tools available only to Admiral support staff (accounts with the support role). Customers cannot open these pages or call these endpoints; API tokens and CLI sign-ins are refused on the support surface by policy, whatever their permissions. It is published so customers can see exactly what support can do on their devices and how it is recorded.
Every action described here is written to the audit log with the support user, the device, and the device's organisation. Customers see the same entries in their own audit log.
Opening the Troubleshooting Page
- Go to Support > Devices and find the device (search by name or ID, or use Locate).
- Choose the Diagnose action on the row. This opens
/support/devices/<device-id>.
The header shows the device name and ID, online state (with last seen), organisation, fleet, the device's protocol (0 for earlier Admiral OS releases, 1 for current), and its observed generation. Refresh reloads every section.
The device detail returned to support never contains pairing keys, recovery material, or device credentials.
Sections
| Section | What it shows |
|---|---|
| Verdict | The same diagnosis customers see on Observe > Diagnostics, plus the evidence lines under each issue and an expandable Signals list (the raw inputs behind the verdict). |
| Connectivity | Transport, endpoint, latency, role, reconnects and instability, mesh stream status, connected since, last contact, break-glass and proxy when set, a 24-hour round-trip latency sparkline, and Run probe. A local-override chip appears here when the device has settings changed on site. |
| Boot and update | Installed versus recommended manager and system versions (amber when they differ), kernel, uptime, any pending action, boot slots and trial state, failed updates, and the boot-reason journal with the actor for remote actions. |
| Workload | Runtime state, whether the assigned configuration is the one running, and the last 100 lines of workload output from the past 24 hours. |
| Storage and time | Filesystems, clock, and the full condition list. |
| Timeline | One time-ordered list of device events, boot reasons, configuration pushes, rollout steps, and audit actions with who did them. Filter with the Events, Boot reasons, Config pushes, Rollouts, and Audit chips. |
| Logs | The log explorer scoped to this device, with a source picker. |
Run probe on this page returns the probe unredacted (proxy URL, Wi-Fi network name, device mesh key, kernel command line, endpoint). Wi-Fi passwords are never returned to anyone, support included. Support probes are limited to one per second per device.
Admin Actions
Support bundle
Request bundle asks an online device to collect a compressed archive and upload it to Admiral Cloud. Choose sections: Agent logs, Kernel log, Supervisor, Container runtime, Applied config, Boot env, Network, Mounts, Processes, Modules, State + probe.
- One bundle at a time per device (The device is already building a bundle).
- Secret file contents, device keys and credentials, pairing tokens, proxy credentials, and registry credentials are removed on the device before upload.
- Bundles are listed with status (requested, uploading, stored, failed), size, and checksum, and can be downloaded. They are deleted automatically after 30 days. An upload that stalls for over an hour is marked failed.
Agent log tail
Reads the device's own log files directly, for devices whose logs are not reaching telemetry. Pick the Log file (agent log, previous agent log, crash log, boot reasons, runtime stack, last workload log), Lines (default 200, maximum 2000), Minimum level, and an optional Contains filter. Read-only; secrets are scrubbed before the filter is applied, so a search cannot match a hidden value.
Diagnostics mode
Puts the device into diagnostics mode, the same mode a technician can enable over Bluetooth. Turning it on stops the customer's workload until it is turned off. A reason is required; it is recorded on the device and in the audit log. The device's DiagnosticsMode condition becomes True and is visible to the customer.
SSH sessions
Lists open remote shell sessions on the device and lets support Terminate one (with confirmation). Support can only open its own SSH sessions while the customer has Support access enabled; see Admiral support access.
Virtual console
Capture virtual console takes a screenshot of the device's status console, independent of what the workload shows on the physical display.
Fleet-Wide Views
Support > Devices also shows fleet analytics across every organisation:
- Health summary tiles, from the devices' reported state: last boot reason, Crash looping, Stuck updates (workload transition over 10 minutes), Pending OS trial, Failed updates, On WebSocket fallback, Disk warning (above 85 %), Clock drift, Below version floor, and Offline longer than 1 hour / 24 hours / 7 days. Select a tile to list up to 50 devices.
- Audit view: requests across organisations, including support device actions. Filter by organisation, actor, action (for example
admin.device.probe), and time.
Migration census
Before older device behaviour is retired, support checks how many devices still run earlier Admiral OS releases: counts by protocol (0 / 1), by agent version, and how many devices still hold earlier device credentials. This is available from the support API (GET /admin/devices/metrics/protocols) and, per organisation, from the MCP list_fleet_protocols tool. There is no dashboard panel for it yet.
Audit Actions
| Action | Recorded when support |
|---|---|
admin.device.read | Opens a device, its state, diagnosis, timeline, or the health summary. |
admin.device.probe | Runs a probe. |
admin.device.logs | Tails a log file. |
admin.device.bundle | Requests, lists, or downloads a bundle. |
admin.device.mode | Turns diagnostics mode on or off. |
admin.device.screenshot | Captures the virtual console. |
admin.device.ssh.list, admin.device.ssh.close | Lists or terminates SSH sessions. |
admin.audit.read | Reads the cross-organisation audit view. |
Support API Reference
All routes are under /v1/admin, require a support account signed in to the dashboard, and are audited as above.
| Method and path | Purpose |
|---|---|
GET /admin/devices/{id} | Device, organisation, fleet, and document status. |
GET /admin/devices/{id}/state, .../diagnose | State and diagnosis (unredacted, except Wi-Fi passwords). |
GET /admin/devices/{id}/timeline?from=&to=&source= | Unified timeline. |
POST /admin/devices/{id}/diagnostics/probe | Unredacted live probe. |
GET /admin/devices/{id}/logs/tail?file=&lines=&minLevel=&grep= | Log tail. |
POST /admin/devices/{id}/bundles, GET .../bundles | Request or list bundles. |
GET /admin/bundles/{bundleId}, GET /admin/bundles/{bundleId}/download | Bundle details and download. |
POST /admin/devices/{id}/diagnostics/mode | {"enabled": true, "reason": "..."} |
GET /admin/devices/{id}/ssh-sessions, DELETE .../ssh-sessions/{sessionId} | List or terminate SSH sessions. |
GET /admin/devices/{id}/screenshot?source=virtual | Virtual console capture. |
GET /admin/devices/metrics/health-summary | Fleet health tiles. |
GET /admin/devices/metrics/protocols | Migration census. |
GET /admin/audit?orgId=&actor=&action=&from=&to= | Cross-organisation audit. |
MCP Tools for Support
The MCP server has matching tools: admin_device_detail, admin_device_timeline, admin_tail_device_logs, admin_request_bundle, admin_list_bundles, admin_get_bundle, admin_download_bundle, admin_set_diagnostics_mode, admin_list_ssh_sessions, admin_close_ssh_session, admin_health_summary, admin_audit, and the read-only list_fleet_protocols census. The MCP server authenticates with an API token, and API tokens are refused on the support surface, so the admin_ tools only return an access error today; run those actions from the troubleshooting page instead. list_fleet_protocols uses customer endpoints and works with an ordinary token.