A hub is a small agent running on a computer inside your venue. It holds one outbound connection to Appmint and carries out commands against the hardware plugged into it.
The order matters: create the hub record first, then install the agent, because the installer asks for a key that only exists once the record does.
1. Pick a box
Anything from the last decade with USB and a network port. It is an idle background service — around 80 MB of memory, no disk hot path. 2 GB of memory and 8 GB free disk is plenty. Node 18 or later.
| Class | Notes |
|---|---|
| Mini PC | Recommended for a permanent install. Solid storage, real power supply, runs indefinitely |
| A computer you already own | Cheapest path. If node --version works, the agent works |
| Single-board computer | Inexpensive, but memory cards wear out under constant writes — boot from an SSD |
Put it where the hardware is. USB cable length is the real constraint, not CPU.
2. Create the hub
In BusinessMade, go to Operations → Hubs and choose Add hub.
| Field | Notes |
|---|---|
| Name (ID) | URL-safe identifier. This is the hub's auth handle — the agent authenticates with it |
| Display name | What you see in lists |
| Description | Worth filling in. "Mini PC under the bar — thermal printer + scanner + drawer" is the kind of note that saves someone a trip |
| Location | Which business location the hub belongs to |
Saving mints an API key. Copy it now — you paste it into the installer, and it cannot be read back afterwards.
3. Install the agent
One command. It works out which platform it is on and fetches the right installer, so there is a single URL to remember.
Linux and macOS — run as root:
curl -sSL https://web.appmint.space/hub-agent/install | sudo bashWindows — in PowerShell as Administrator:
irm https://web.appmint.space/hub-agent/install.ps1 | iexThe installer needs root to register a service. Running it unprivileged stops with a message telling you the same thing. Windows needs an elevated PowerShell for the same reason.
The installer bootstraps Node if it is missing, downloads the release, installs to a standard location, registers a service that starts on boot, runs the setup wizard, and starts the service.
Node 18 or later is required; the installer fetches it via the platform's package manager if it is absent — apt on Debian and Ubuntu, Homebrew on macOS, winget or Chocolatey on Windows. If Node is already present, none of those are needed.
The setup wizard
It asks for the hub name, the API key, your organization and the server URL, then writes the config.
To re-run it later — after regenerating a key, for instance:
sudo hub-agent setupWhere things land
| Linux | macOS | Windows | |
|---|---|---|---|
| Install | /opt/appmint-hub | /opt/appmint-hub | %ProgramFiles%\AppmintHub |
| Config | /etc/appmint-hub/config.json | /etc/appmint-hub/config.json | %ProgramData%\AppmintHub\config.json |
| Service | appmint-hub.service | io.appmint.hub | AppmintHub |
| Logs | journalctl -u appmint-hub -f | tail -f /var/log/appmint-hub.out.log | Event Viewer → AppmintHub |
Verifying the download
Each release publishes its metadata alongside the tarball:
https://web.appmint.space/hub-agent/<version>/release.jsonIt carries the version, tarball name, size, SHA-256 and publish time. At 1.0.3 the tarball is 73 KB with checksum:
a650fa337d0918c5d99f9b63edc6b3ad00a9aa3afcafd4e20515df123eb04b5cThe bootstrap is pinned to a release, so the script and the agent it installs always come from the same build.
4. Confirm it connected
Back on the Hubs tab, the hub shows three badges once it is working:
| Badge | Meaning |
|---|---|
| API key · minted | A key exists for this hub |
| Online · connected | The agent is connected and heartbeating |
| Peripherals · N reported | The agent found N devices on the box |
The card also shows the agent version and when it was last seen.
If Peripherals reads 0 but the hub is online, the agent connected but found no hardware — check cables and power before anything else.
How it connects
The agent opens an outbound WebSocket and keeps it open, authenticating with its hub name, key and organization on the handshake.
Because the connection is made outward from your venue, nothing needs exposing to the internet and no firewall rules are required. The one thing to allow is outbound WebSocket on 443 — guest and captive-portal networks commonly block it.