Using Fieldhand
Device page
Health, connection history, network and the shell audit log for one device.
Health
CPU, memory, root disk and the hottest thermal zone, with a 24-hour sparkline each, plus GPU busy time on devices that expose it (NVIDIA Jetson, AMD, and NVIDIA cards with nvidia-smi, but not Intel integrated graphics or the Raspberry Pi). The agent sends a sample with every heartbeat (every 30 seconds to 10 minutes, see how it works). Samples are kept for 7 days.
Connection history
A 7-day bar of online and offline periods, the share of time online, the number of drops, and the latest events: when the device connected, from which public IP, and why it disconnected.
| Reason | What usually causes it |
|---|---|
| closed by the device | The agent restarted, updated, or the device shut down cleanly. |
| heartbeats stopped | Coverage loss, power loss, or a NAT that dropped the link without telling anyone. |
| network error | The connection broke mid-stream (Wi-Fi roam, modem reset). |
| link reset by the relay | Fieldhand restarted its relay; the agent reconnects within seconds. |
| device removed | Someone removed the device in the dashboard. |
Connection events are kept for 30 days.
Network
The public address Fieldhand sees, plus each interface the device reports: Ethernet, Wi-Fi (with signal strength in dBm) or cellular, its addresses, which one carries the default route and its gateway. The round trip between the device and the Fieldhand relay is measured when it connects and every hour, which tells a slow cellular link from a slow device.
Screen
Screen shows what the device's display shows right now: is the kiosk on the right page, is the sign showing an error? It works with Wayland compositors through grim (Cage, Sway, Weston and other wlroots ones), X11 through ImageMagick's import, and the Linux framebuffer (/dev/fb0) with nothing installed. Wider screens are scaled to 1600 pixels and sent as JPEG, a few hundred KB. Run fieldhand screenshot > screen.jpg on a device to test it. Each capture is in the activity log; Fieldhand doesn't keep the images.
Live view and control
Live view in the Screen panel shows the display as it changes, in the browser. When you open it, the agent starts a VNC server for your session alone (x11vnc on X11, talking to the agent over a private socket pair; wayvnc on Wayland, on a socket only the display's user can open) and stops it when you close the panel. Nothing listens on the device's network and other users on the device can't reach it. It runs as the display's user; if the display belongs to root and the device was installed with --shell-user, Screen and Live view are refused, so they never reach further than a shell would. It starts view only. Tick Control to use the mouse and keyboard; anyone in front of the device sees you do it. Install the server once with your image, for example apt install x11vnc or apk add wayvnc. Each session is in the activity log. On Wayland the server shows one monitor at a time: with two or more connected, buttons at the top of the live view (HDMI-A-1, eDP-1…) switch between them. On X11 every monitor is part of one screen and shows side by side.
Inventory
Vendor, model, serial number, board, CPU, firmware and operating system, the USB devices plugged in (with the serial port each provides, such as /dev/ttyACM0), and every installed package with its version (dpkg, rpm, apk, pacman or opkg). The device sends it when it changes, not on every connection. Run fieldhand inventory on a device to see exactly what it reports.
Search installed packages on the fleet page finds which devices have a package and in which version, for example after a security advisory.
Security
Known vulnerabilities in the device's installed packages, matched against OSV.dev, the open advisory database that collects the Debian, Ubuntu and Alpine security trackers. Each finding shows its severity (CVSS), the package and version, and whether the distribution has a fixed version. Fixable ones go first: the Upgrade packages command takes care of most of them. Devices are rechecked when their packages change and once a day, since new advisories appear all the time. Security report on the fleet page ranks advisories by severity and the number of devices they affect.
Covered: Debian, Raspberry Pi OS, Ubuntu and Alpine. Other systems (Arch, Fedora, Yocto images) show as not covered rather than as clean. Only package names and versions are sent to OSV.dev.
Activity
Files uploaded or downloaded and web pages opened on the device, with who, when, from which IP, the path or port, and the size.
Terminal sessions
Every shell opened on the device: who opened it, from which IP, when, for how long, how many bytes went each way and how it ended. Keystrokes and output are not recorded.
Something wrong or missing on this page? Tell us.