This guide explains how to install and configure the Kudzu Agent to connect your LoRaWAN gateways to Canopy NOC. The agent acts as a local proxy between your gateways and your LoRaWAN Network Server (LNS), capturing packet metadata and forwarding it to the analytics platform without disrupting your existing data path.

Before you begin#

• Confirm you have an active Canopy NOC account and an API key or token from the platform.
• Have access to your LoRaWAN gateway configuration.
• Have a machine (server, VM, or edge device) where you can run the agent. It must be reachable by your gateways and able to reach your LNS.
• Have basic familiarity with the command line.

Step 1 – Download the Kudzu Agent#

1. Go to the Kudzu Agent releases page on GitHub.
2. Download the package that matches your operating system:
   • kudzu-agent-linux-amd64.tar.gz for 64-bit Linux
   • kudzu-agent-windows-amd64.zip for 64-bit Windows
   • kudzu-agent-macos-amd64.tar.gz for macOS

Step 2 – Install the agent#

Linux / macOS#

tar -xzvf kudzu-agent-<platform>.tar.gz
cd kudzu-agent
chmod +x kudzu-agent

Windows#

1. Extract the .zip archive using the built-in extractor or a tool like 7-Zip.
2. Open a Command Prompt and navigate to the extracted directory.

Step 3 – Configure your gateways#

Redirect each gateway’s packet forwarder to send traffic to the Kudzu Agent instead of directly to the LNS.

1. Open your gateway’s packet forwarder configuration (web interface, SSH, or local config file).
2. Change the server_address to the IP address of the machine running the agent:

"server_address": "<kudzu-agent-ip>",
"serv_port_up": 1700,
"serv_port_down": 1700

3. Save the configuration and restart the packet forwarder service.

Step 4 – Configure the Kudzu Agent#

Edit the config.yaml file in the agent directory.

kudzu:
  api_key: "<your-canopy-noc-api-key>"

lns:
  server_address: "<your-lns-address>"
  serv_port_up: 1700
  serv_port_down: 1700

agent:
  listen_port_up: 1700
  listen_port_down: 1700

• kudzu.api_key – the API key from your Canopy NOC account.
• lns.server_address – the address of your existing LNS where the agent will forward traffic.
• agent.listen_port_up / listen_port_down – the ports the agent listens on for gateway traffic.

Step 5 – Start the agent#

Linux / macOS#

./kudzu-agent

To run in the background:

nohup ./kudzu-agent &

Windows#

kudzu-agent.exe

Step 6 – Verify the integration#

1. Check the agent’s console output or log file for incoming gateway packets and successful forwarding to both the LNS and Canopy NOC.
2. Log in to your LNS and confirm that device data still arrives as expected.
3. In Canopy NOC, navigate to Configuration > LNS Integrations and verify that the Kudzu Agent integration shows recent activity.

Step 7 – Register the integration in Canopy NOC#

1. Open the sidebar and navigate to Configuration > LNS Integrations.
2. Click Add Integration and select Kudzu Agent.
3. Provide a name and any required identifiers (agent ID or API key).
4. Click Save and confirm the integration status shows as active.

What to do next#

• Manage Investigation Dashboards to import diagnostic views for your network.
• Review the Metrics Dashboard for computed KPI summaries.
• Investigate an Alarm when the platform detects threshold violations.