Integrate with HiveCatcher

This is a developer guide for product teams building HiveCatcher into their own product as a connectivity option. It is not an end-user install guide and it is not for every customer. It assumes the device is already set up using Connect, Cellular, or Roll your own.

HiveCatcher does not require a custom integration. The agent exposes a small, local identity surface, so your application can show the device code, send the customer to registration, or link to service activation. This page explains those surfaces and the permissions around them.

HiveCatcher is the service. Your application is a client. Nothing in this guide calls the carrier or changes a connection; the cloud handles activation after the customer subscribes.

What we mean by a connection

HiveCatcher Cellular Connection is the managed, multi-carrier SIM and cellular line supplied and billed by HiveCatcher. It is the connection included with HiveCatcher Cellular and Cellular Connect.

Connect is the same remote access over the internet the customer already has: Ethernet, or their own SIM and carrier plan. HiveCatcher does not supply or manage that connection. Cellular Service Only is a HiveCatcher Cellular Connection for the customer's own hardware.

1. Install HiveCatcher first

The agent must be installed and running before its identity is available. Use the install guide for the product on the box:

HiveCatcher Connect for Ethernet or a customer-provided SIM.
HiveCatcher Cellular for a HiveCatcher Cellular Connection: the managed SIM and cellular line supplied and billed by HiveCatcher.
Manual install if you already manage the Linux host.

2. Read the device identity

The same identity is available three ways. All three are supported. Choose the one that fits your application:

Surface	Best for	Availability
Command	Scripts, technicians, one-off reads	On demand; reads the agent config
File	A local app that can read a file	Refreshed while the agent runs
Loopback HTTP	A local app that polls or shows live state	While the agent service runs

Command

# human-readable
hivecatcher-agent identity --format plain

# JSON
hivecatcher-agent identity --format json

File

cat /run/hivecatcher/identity.json

The file is world-readable and refreshed by the running agent. It is the simplest surface for an application that does not run as root.

Loopback HTTP

curl -s http://127.0.0.1:8790/identity

The endpoint is live while the agent runs, is bound to loopback only, and returns JSON. It is the best default for a local application.

The identity command reads the agent configuration at /etc/hivecatcher/agent.json, which is root-only. An application running as an unprivileged user should use the file or loopback HTTP surface, or run the command as root. The file and HTTP surfaces do not require access to the configuration.

What the identity contains

uid, uidSource, serial, hostname: the stable hardware identity.
quickCode, registerUrl, registered, claimed, deviceId: the pairing code and account state.
agentVersion, generatedAt: the agent version and when the snapshot was produced.
modem: a summary of the modem and SIM, when one is present.

The identity does not contain the device token or any other secret. The quick code is a public pairing code; it is safe to display.

3. Use the quick code

The quickCode is the short code printed on the box or generated by the agent. The registerUrl is the registration page for an unclaimed box; once the box is claimed, send the user to the activation page instead.

Not claimed: show the code and open registerUrl, or send the user to /register with ?code=....
Claimed: show the code and send the user to /activate with ?code=... to choose a product and start service.
No plan yet: a box can still be linked and shown; it stays inert until the customer subscribes.

# registerUrl is supplied by the identity
# unclaimed -> https://hivecatcher.com/register?code=7QK4M2XP
# claimed   -> https://hivecatcher.com/activate?code=7QK4M2XP

Use registerUrl while the box is unclaimed. Once claimed is true, use the quickCode on the activation page. The code is the same value the device prints.

Recommended path

A local app on the box: poll the loopback HTTP endpoint, with the file as a fallback. This works without root.
Scripts and technicians: use the command with --format json.
A simple file reader: read /run/hivecatcher/identity.json.

All three surfaces are supported and return the same identity. The recommendation is about permissions and freshness, not about one surface being more official than another.

Security

The HTTP endpoint is bound to 127.0.0.1:8790. Never expose it on a network interface or through a proxy.
The identity file is world-readable because it contains no secrets. Keep the agent configuration and device token root-only.
Your application should not need root to read the identity. Use the file or loopback HTTP instead of reading the agent configuration.
Do not call the carrier or attempt to activate a HiveCatcher Cellular Connection from your application. HiveCatcher does that cloud-side after the customer subscribes.

Diagnostics

For on-box troubleshooting, see Agent diagnostics. It covers cell, status, heartbeat, modem, VPN, version, logs and the commands that need care.