Skip to content
NovaVMS Manual

Wipe a gateway to factory state

Use this procedure to scrub pairing credentials, cached ONVIF passwords, and local recording buffers from a gateway before it leaves your control. After the wipe the gateway is no different from a freshly-imaged unit and can be paired into any org.

When to wipe

  • A gateway is being returned from a decommissioned site and redeployed elsewhere.
  • A customer is handing the hardware back and you will re-sell or re-provision it.
  • A unit is going out for RMA and must not ship with customer data.

Before you wipe

If the site is fully closing, run Decommission a site first — that procedure exports clips and audit logs, deletes cameras in order, and only then asks you to wipe the hardware. This page is for the wipe step itself, or for the case where the gateway is coming back but the site stays open.

Step 1 — Disable the gateway in the cloud

Disabling (not deleting) the gateway stops the cloud from treating any future connection from the old API key as legitimate. US-GW-12 defines this state.

  1. In the NovaVMS UI open Gateways.
  2. Click the gateway row to open its detail page.
  3. Click Disable. The status badge changes to gray Disabled and any attached cameras cascade to offline per D51.

Step 2 — Run the wipe on the gateway host

SSH to the gateway host. Stop the service, delete the config, and clear the local data directory.

Terminal window
sudo systemctl stop novavms-gateway
sudo rm -f /etc/novavms/gateway.yaml
sudo rm -rf /var/lib/novavms-gateway/*

Do not uninstall the novavms-gateway binary.

These paths are the canonical install-script defaults (scripts/deploy-gateway.sh:29-31 defines INSTALL_DIR=/opt/novavms-gateway, CONFIG_DIR=/etc/novavms, DATA_DIR=/var/lib/novavms-gateway). The gateway binary at gateway/cmd/agent/main.go:44-48 exposes only --config, --pair, --name, and --validate — there is no wipe or reset sub-command, so the file-system delete is the only path. On macOS the launchd plist + binary live in the same /opt/novavms-gateway/ tree, but the systemctl line becomes sudo launchctl bootout system/com.novavms.gateway (per scripts/deploy-gateway.sh:399).

Step 3 — Verify the wipe succeeded

Confirm the service is stopped, the config is gone, and the data directory is empty.

Terminal window
systemctl status novavms-gateway
# expected: "inactive (dead)" or "failed" — either is fine; the service
# has no config to start from.


ls -la /etc/novavms/
# expected: no gateway.yaml entry.


ls -la /var/lib/novavms-gateway/
# expected: empty, or only the empty subdirectories the OS image ships.

In the cloud UI, the gateway row still shows Disabled — the cloud record itself has not changed. If you plan to delete that record as well, see Decommission a site.

Step 4 — Re-pair or ship out

Pick one:

If this didn’t work

  • If a re-pair attempt returns 409 "pairing code already used", the new code was consumed by a previous attempt. Generate a fresh pairing code and retry. See Gateway won’t pair.
  • If the gateway host will not boot after the wipe (for example after a full re-image rather than a config wipe), see Gateway shows Offline for the nearest boot-path diagnostics.