@nightlybuildgroup/sms-otp-agent

A small, self-contained agent that drains SMS inboxes from a USB modem and pushes each message to your sms-otp-service server over HTTPS. It supports Huawei E3372 (HiLink) and ZTE goform modems, runs as a background service (launchd on macOS, systemd on Linux), and deletes messages from the modem only after the server confirms storage (for sources that support deletion).

One agent owns one phone number. Run as many agents as you have modems; each authenticates with its own revocable token.

Requirements

• Node.js 24+
• A supported modem reachable on the same machine (default HiLink address http://192.168.8.1).
• Your server's URL and an agent token (created by an admin on the server's Agents page).

Install

npm install -g @nightlybuildgroup/sms-otp-agent

This installs the sms-agent command.

Usage

Provision the agent (writes ~/.config/sms-agent/config.json, mode 0600):

sms-agent provision \
  --server https://your-server.example.com \
  --token  <token from the server's Agents page> \
  --number +15551234567 \
  --source e3372            # or: zte
# ZTE devices: --source zte --modem http://192.168.0.1 [--password <admin pw>]

Run it as a background service:

sms-agent install      # install + start (launchd/systemd user service)
sms-agent status       # check it's running
sms-agent uninstall    # stop + remove the service

Or run in the foreground (useful for debugging):

sms-agent run

Configuration

provision flags map to a config file; environment variables override the file:

| Env | Flag | Description | |---|---|---| | VPS_URL | --server | Base URL of the server | | AGENT_TOKEN | --token | Per-agent token from the server's Agents page (AGENT_SECRET accepted as a legacy alias) | | NUMBER | --number | This agent's phone number (E.164) | | SOURCE_TYPE | --source | e3372 (default) or zte | | POLL_INTERVAL | --interval | Milliseconds between polls (default 15000) | | MODEM_BASE_URL | --modem | Modem base URL (default http://192.168.8.1) | | MODEM_PASSWORD | --password | ZTE admin password, if set | | MODEM_LOCAL_ADDR | --local | Bind a source IP on multi-route hosts |

Notes

• The agent never stores secrets in logs; the config file is created 0600.
• If /ingest returns 401, the token is wrong, revoked, or missing — create a fresh one on the server's Agents page and re-provision with --token.