Manual install

Install the HiveCatcher agent yourself

The agent is a single static binary — no runtime, no dependencies. If you'd rather not use the one-line installer, these are the exact steps it performs. Target: Linux (x86_64, arm64, arm) with systemd.

Prefer the script? It does all of this for you: see the installer.

Before you start — bootstrap

A minimal install may not include curl or sudo, so the one-line install can't run yet. Run the line for your distro once as root (use su - if you can't sudo):

# Debian / Ubuntu
su -
apt update && apt install -y curl sudo
usermod -aG sudo YOUR_USER
exit
# log out and back in (or run: newgrp sudo) so the group applies

# Fedora / RHEL / Rocky / Alma
su -
dnf install -y curl sudo
usermod -aG wheel YOUR_USER
exit

Then confirm sudo whoami prints root and continue below. You do not need to enable the root account or root SSH — this runs via sudo, and the cloud reaches the box as a dedicated hivecatcher account.

Also required

  • SSH server installed and running — the openssh-server package (on most distros it's an option in the OS installer). The cloud reaches the device over SSH for remote access and the browser terminal.
  • A sudo-capable user (or root). If your account can't run sudo, enable it first — log in as root and add your user to the sudo / wheel group.
  • systemd — standard on Debian/Ubuntu, Fedora/RHEL, Arch, and openSUSE.
  • No root account or root SSH needed. This runs via sudo; the cloud uses the dedicated hivecatcher account.

1.Get a Device Code

Sign in and open Device Onboarding (or your organization's page). Generate a code — it looks like 7QK4-M2XP. A single-use code pairs one device; a reusable install key can pair many (handy for many devices or a per-organization script).

2.Download the agent

ARCH=amd64   # amd64 | arm64 | arm
sudo install -m 0755 \
  "https://hivecatcher.com/downloads/hivecatcher-agent-linux-$ARCH" \
  /usr/local/bin/hivecatcher-agent
hivecatcher-agent version

3.Pair with your code

sudo hivecatcher-agent register \
  --server https://hivecatcher.com \
  --code 7QK4-M2XP

Already installed? Enter the code later with sudo hivecatcher-agent provision --code 7QK4-M2XP. It writes the code to /etc/hivecatcher/agent.json and pairs. No interactive prompts.

4.Run it as a service

sudo install -d -m 0750 /etc/hivecatcher
sudo curl -fsSL https://hivecatcher.com/downloads/hivecatcher-agent.service \
  -o /etc/systemd/system/hivecatcher-agent.service
sudo systemctl daemon-reload
sudo systemctl enable --now hivecatcher-agent
systemctl status hivecatcher-agent

The device will appear in your account once it checks in. The first check-in is what makes it billable.

5.Remote access (WireGuard)

The on-demand VPN and browser terminal need WireGuard and a firewall allowance so the cloud can reach the device over the tunnel:

# Debian / Ubuntu
sudo apt-get install -y wireguard wireguard-tools
sudo ufw allow in on wg0

# Fedora / RHEL
sudo dnf install -y wireguard-tools
sudo firewall-cmd --permanent --direct --add-rule ipv4 filter INPUT 0 -i wg0 -j ACCEPT
sudo firewall-cmd --reload

(Other distros: install wireguard-tools and allow inbound on wg0. Wi-Fi is not supported — wired Ethernet and cellular only.)

To also enable the in-browser terminal, create the dedicated account the cloud gateway logs in as:

sudo useradd --create-home --shell /bin/bash hivecatcher
sudo install -d -m 0700 -o hivecatcher -g hivecatcher /home/hivecatcher/.ssh
sudo curl -fsSL https://hivecatcher.com/downloads/hivecatcher-cloud.pub \
  | sudo tee -a /home/hivecatcher/.ssh/authorized_keys >/dev/null
sudo chown -R hivecatcher:hivecatcher /home/hivecatcher/.ssh
sudo chmod 0600 /home/hivecatcher/.ssh/authorized_keys
echo "hivecatcher ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/hivecatcher
sudo chmod 0440 /etc/sudoers.d/hivecatcher

6.Cellular (only for the Cellular product)

If the device has a supported modem, install ModemManager + libqmi and run the bring-up helper. The installer script does this automatically:

sudo apt-get install -y modemmanager libqmi-utils libmbim-utils
# then use the installer's cellular step, or the downloaded helpers

Files & reference

  • Agent binary: https://hivecatcher.com/downloads/hivecatcher-agent-linux-<arch>
  • systemd unit: https://hivecatcher.com/downloads/hivecatcher-agent.service
  • Installer script: https://hivecatcher.com/install.sh
  • Config: /etc/hivecatcher/agent.json (device token + provisioning code)
Install guide | HiveCatcher