1. Home
  2. Help Topics
  3. Agent activation via Command Line

Agent activation via Command Line

A new Domotz Agent can be activated and configured directly via command line (or API) by using an Agent Activation API Key.

Every Domotz Agent, starting from version 3.3.0, listen on port 3000 (http) with a new end-point which can be used to activate and configure it.

Use an Agent Activation API Key to perform API call against port 3000 of the Domotz Agent. If the Agent has not been previously configured, the following command will configure and activate a new agent: Use an Agent Activation API Key to perform API call against port 3000 of the Domotz Agent. If the Agent has not been previously configured, the following command will configure and activate a new agent:

curl -v  -XPOST -H "x-api-key: ${X_API_KEY}" -d "{\"name\": \"${AGENT_NAME}\", \"endpoint\": \"${DOMOTZ_PUBLIC_ENDPOINT}\"}" http://${DOMOTZ_AGENT_IP}:3000/api/v1/agent

Please, configure X_API_KEY, NAME, ENDPOINT and DOMOTZ_AGENT_IP address for your actual scenario. For instance, you can use something like:

X_API_KEY="your-agent-api-key"
AGENT_NAME="your-agent-name"
DOMOTZ_PUBLIC_ENDPOINT="https://api-testing-eu-central-1-cell-1.domotz.nl/public-api/v1/"
DOMOTZ_AGENT_IP="10.10.10.125"

Note: the minimum version of the Agent required is 3.3.0.
You can check the version of your agent with the following API call to the Agent itself:

curl -v -XGET http://${DOMOTZ_AGENT_IP}:3000/api/v1/status

Check for agent_version in the returned json. Also, you can check if the Agent is not yet configured it is mode=RESTRICTED.

Please, refer to section Windows OS with a practical example of how to install and configure a Domotz Agent silently and via script.

Activation with Network Scanning Disabled

Starting from version 3.9.3 the agent can be activated passing an additional optional boolean field “deny_all_interfaces” in the request body. If true, the agent will not scan any network unless a specific “allow” configuration is passed using the Set Network Interfaces Policy method of the Public-API:

curl -v  -XPOST -H "x-api-key: ${X_API_KEY}" -d "{\"name\": \"${AGENT_NAME}\", \"endpoint\": \"${DOMOTZ_PUBLIC_ENDPOINT}\", \"deny_all_interfaces\": true}" http://${DOMOTZ_AGENT_IP}:3000/api/v1/agent

Updated on October 20, 2021

Was this article helpful?