Registration and controller communication

The agent communicates with the controller over a WebSocket connection (WSS) on controller port 44443. The connection is always initiated by the agent, which allows communication when the agent is behind NAT.

Agent registration

During registration the agent sends identification data to the controller, at minimum the agent instance identifier generated on first startup, agent name, version and IP address. To register the agent, sign in to its web interface at https://<agent_ip_address>/.

Registration requires filling in the following two registration form fields:

Field	Required value	Validation	Purpose
Controller Address	Controller hostname or IP address, for example 192.168.1.100 or controller.example.com	Hostname or IP only. If a protocol, port or path is entered, the agent removes it.	Defines which controller the agent registers to and maintains a connection with.
Agent Name	A descriptive name for the agent, for example DC1, Branch Krakow or DMZ-Probe	3 to 50 characters.	Shown on the agent list in the controller and in measurement reports.

Communication with the controller after registration

After successful registration the agent maintains a persistent WebSocket connection to the controller. The controller checks whether tasks should be started on that agent — this applies to tasks in pending, sent or running status.

If a task should run on that agent the controller sends a create_job message. The agent starts the corresponding task type, for example ICMP, HTTP Timing, UDP Trace, Speedtest or TCP Port Monitor, then confirms task start with a job_started message. On the controller side the task then moves to running status.

The agent periodically sends a heartbeat to the controller, a short message confirming that it is still running and has an active connection. By default a heartbeat is sent every 30 seconds.

After receiving a heartbeat the controller updates the last contact time (last_heartbeat) and replies with heartbeat_ack. The controller marks the agent as offline if it receives no heartbeat for 60 seconds. Because the check runs periodically, offline status may appear after about 60-70 seconds from connection loss.

Connection loss

If the agent loses connection to the controller, running tasks are stopped locally on the agent side. The agent also clears temporary measurement buffers so data is not accumulated indefinitely during a long outage. The agent then attempts to reconnect automatically. The delay between attempts starts at 1 second and doubles after each failed connection (1 s → 2 s → 4 s → 8 s → …), up to a maximum of 60 seconds. After a successful connection the delay resets to 1 second.

On the controller side missing heartbeats mark the agent as offline. Active tasks for that agent in running, sent or pending status are automatically moved to auto_paused with reason agent_offline. This lets the controller know that tasks were not stopped manually by a user, but because communication with the agent was lost. Auto-resume can be enabled in controller settings to automatically resume tasks in auto_paused status when the agent returns online.

Agent back online

When the agent regains connection it registers again with the controller using its AIID.

The controller updates its status back to registered. If automatic task resume after agent return is enabled in settings, tasks in auto_paused status are moved back to pending.

The controller then sends them to the agent again. The agent starts the tasks and sends job_started, after which tasks return to running status.

Agent unregistration

An agent can be unregistered in two ways: from the controller or from the agent panel.

Unregistering from the agent sends an unregister message to the controller. The agent keeps its AIID in local storage, which allows registering the same agent instance again.

Unregistering from the controller rejects any new registration attempt with the same AIID (unregistered_by_controller). To register again from the same machine hosting the agent container, delete the container and deploy it again so the agent generates a new instance identifier.

Controller settings (Settings → Tasks, Agent Automation section) allow related automation: Archive on agent unregister archives tasks assigned to the agent (enabled by default), and Delete on agent delete permanently removes tasks when the agent is deleted from the controller (disabled by default).

Error messages

Message	Meaning	Action
Please enter controller address	The Controller Address field is empty.	Enter the controller hostname or IP address.
Please enter an agent name	The Agent Name field is empty.	Enter the name that should be visible in the controller.
Agent name must be at least 3 characters	The agent name is too short.	Use a name with at least 3 characters.
Agent name must be less than 50 characters	The agent name is too long.	Shorten the name to 50 characters or fewer.
Controller address must be a valid hostname or IP address	The address contains unsupported characters after normalization.	Use only a hostname or IP address. Remove paths, spaces and unsupported characters.
Cannot connect to controller: ...	The agent cannot open a WebSocket connection to the controller.	Check DNS, routing, firewall rules and whether TCP 44443 is reachable on the controller.
Controller rejected: license_not_activated	The controller has no active license.	Activate the controller license.
Controller rejected: license_locked	The controller license is locked.	Check controller license status and connectivity to the license service.
Controller rejected: license_expired	The controller license has expired.	Renew or replace the license.
Controller rejected: unregistered_by_controller	An agent with this AIID was previously unregistered by the controller.	Delete the agent container and deploy it again to generate a new instance identifier, then register the agent again.
Failed to save registration: ...	The agent could not write registration data to local storage.	Check the agent data volume and container permissions.