Agent diagnostics

Commands for checking a HiveCatcher box on site or over SSH. Run them as root or with sudo when the command needs the agent configuration or the modem.

First look

cell is the quickest check. It reports the modem, SIM, line source, signal, APN, whether data passes, and whether the device is registered and claimed.

hivecatcher-agent cell
hivecatcher-agent cell --json

HiveCatcher cellular status
  Modem:      EM7411 (connected)
  SIM:        ICCID 8935..., IMSI 23410...
  Line:       HiveCatcher-managed (home 23410)
  Network:    Verizon (311480), LTE, roaming
  Signal:     70/100 (good)
  APN:        cbc135 (no credentials)
  Data:       working
  Device:     registered, claimed
  Code:       9AE2T8WH

Run without root, cell still reports the modem and network, and reads the running agent's loopback identity for the claimed state. If the agent is down, it says the configuration is unreadable rather than claiming the box is unregistered.

Command reference

Command	Use
`hivecatcher-agent cell`	Human-readable cellular status. Add `--json` for scripts.
`hivecatcher-agent status`	Full JSON sample: hardware, network, system and agent state.
`hivecatcher-agent identity`	Hardware ID, quick code, register URL and claimed state. Use `--format plain` or `--format json`.
`hivecatcher-agent heartbeat`	Last and next heartbeat, and the interval.
`hivecatcher-agent modem show`	The APN the box dials with.
`hivecatcher-agent modem set`	Set the APN, with optional username and password. `--reset` returns to the HiveCatcher APN.
`hivecatcher-agent vpn status`	Whether the on-demand WireGuard tunnel is up.
`hivecatcher-agent version`	Agent version, protocol and features. Add `--json` for scripts.
`systemctl status hivecatcher-agent`	Service state.
`journalctl -u hivecatcher-agent -f`	Follow agent logs. Use `-u hivecatcher-cellular` for the cellular bring-up.

Identity for an application

The three identity surfaces are documented in Integrate with HiveCatcher. The short version:

# command (may need root for the agent config)
hivecatcher-agent identity --format plain

# world-readable file, refreshed by the agent
cat /run/hivecatcher/identity.json

# loopback HTTP while the agent runs
curl -s http://127.0.0.1:8790/identity

The loopback endpoint and the file are the friendly surfaces for an application that does not run as root. Never expose port 8790 on the network.

Commands that need care

modem set restarts the cellular connection. A wrong APN can drop the box off the network, so have LAN or SSH access before you change it.
hivecatcher-agent deregister tells HiveCatcher the box is being removed. It stops the cloud relationship and should only be used when decommissioning a device.
systemctl stop hivecatcher-agent stops heartbeats and remote access. Use it only for a deliberate maintenance window.

What to capture for support

hivecatcher-agent version
hivecatcher-agent cell --json
hivecatcher-agent status
journalctl -u hivecatcher-agent -n 100 --no-pager

Include the box name or quick code with the output. Do not include the agent configuration or device token.