Install monit-agent

This guide explains how to prepare onboarding information, install monit-agent, and start the Agent as a system service.

Before you begin

Prepare the following information before installation:

Item	Description
Agent package download URL	`https://static.flashcat.cloud/monitagent/monitagent-v0.1.6-linux-amd64.tar.gz`. For ARM CPUs, replace `amd64` with `arm64`.
Edge address	For example, `ws://edge.example.com:6868` or `wss://edge.example.com:6868`. Edge version must be `>= v0.47.0`. View the Edge list and installation method here.
Local host object address	Use the current host’s fixed private IP or DNS name, such as `10.0.1.12`. If omitted, the Agent uses the IP address associated with the local default route.
Read-only accounts for databases and middleware	To diagnose MySQL, Redis, PostgreSQL, MongoDB, Kafka, Elasticsearch, and other services, prepare read-only accounts and credentials in advance.

The Edge address must include a protocol prefix. Supported protocols are ws://, wss://, http://, and https://. Use wss:// in production. ws:// and http:// can be used in internal networks.

The following steps use Linux as an example.

sudo mkdir -p /opt/monit-agent
cd /opt/monit-agent

sudo curl -sfLO "https://static.flashcat.cloud/monitagent/monitagent-v0.1.6-linux-amd64.tar.gz"
sudo tar -xzf monitagent-v0.1.6-linux-amd64.tar.gz --strip-components=1
sudo chmod +x ./monitagent

After extraction, the directory should contain:

/opt/monit-agent/monitagent
/opt/monit-agent/agent.yaml

Confirm that the binary is executable:

/opt/monit-agent/monitagent --version

Start in the foreground

The minimum startup command is:

sudo /opt/monit-agent/monitagent \
  --agent.edgeAddresses="ws://<EDGE_HOST>:<EDGE_PORT>" \
  --agent.configFile="/opt/monit-agent/agent.yaml" \
  --agent.hostLocator="<THIS_HOST_LOCATOR>"

Parameter	Required	Description
`--agent.edgeAddresses`	Yes	The Edge address that the Agent connects to.
`--agent.configFile`	Recommended	Path to the Agent configuration file.
`--agent.hostLocator`	No	The current host object address displayed in the console.

If --agent.hostLocator is omitted, the Agent automatically selects the local default egress IP as the host object address. It is recommended to keep this value consistent with the machine identifier used by your monitoring system.

Configure multiple Edge addresses

If there are multiple Edge addresses, separate them with commas:

sudo /opt/monit-agent/monitagent \
  --agent.edgeAddresses="ws://edge-a.example.com:6872,ws://edge-b.example.com:6872" \
  --agent.configFile="/opt/monit-agent/agent.yaml" \
  --agent.hostLocator="10.0.1.12"

The Agent reconnects automatically. If the current connection is unavailable, it continues trying other Edge addresses.

Use Basic Auth or TLS

If Basic Auth is enabled on Edge, pass both the username and password:

sudo /opt/monit-agent/monitagent \
  --agent.edgeAddresses="wss://edge.example.com:6872" \
  --agent.edgeBasicUser="<EDGE_BASIC_USER>" \
  --agent.edgeBasicPass="<EDGE_BASIC_PASSWORD>" \
  --agent.configFile="/opt/monit-agent/agent.yaml" \
  --agent.hostLocator="10.0.1.12"

If Edge uses a private CA certificate, specify the CA file:

sudo /opt/monit-agent/monitagent \
  --agent.edgeAddresses="wss://edge.example.com:6872" \
  --agent.edgeTLSCAFile="/etc/monit-agent/edge-ca.pem" \
  --agent.configFile="/opt/monit-agent/agent.yaml" \
  --agent.hostLocator="10.0.1.12"

When TLS parameters are configured, the Edge address should use wss:// or https://.

Install as a system service

After the foreground startup works, install the Agent as a system service:

cd /opt/monit-agent

sudo ./monitagent \
  --agent.edgeAddresses="ws://<EDGE_HOST>:<EDGE_PORT>" \
  --agent.configFile="/opt/monit-agent/agent.yaml" \
  --agent.hostLocator="<THIS_HOST_LOCATOR>" \
  --audit.dir="/var/log/monit-agent/audit" \
  --install

sudo ./monitagent --start
sudo ./monitagent --status

View logs:

sudo journalctl -u monitagent -f

If you modify the Edge address, Basic Auth, TLS parameters, or hostLocator, restart the Agent. After modifying agent.yaml, send SIGHUP to reload the configuration:

sudo systemctl kill -s HUP monitagent

Approve a blocked Shell command

shell.exec automatically runs read-only diagnostic commands that meet its built-in safety rules. If a command does not pass the automatic rules but you have confirmed that it is appropriate for the current machine, sign in to the Linux host running the Agent and open an approval session as root:

sudo /opt/monit-agent/monitagent shell-approval

After the session connects, it displays a waiting status. When commands need approval, the terminal shows only the commands and a ten-second countdown:

Press Enter to approve every command in the current batch.
Press n to reject every command in the current batch.
If you do not respond within ten seconds, the batch is rejected automatically. Concurrent commands that arrive later are queued and receive a full ten-second window after they are displayed.
Input while no command is pending does not execute anything; the terminal continues to display the waiting status.
Press Ctrl-C to close the approval session.

Only one approval session can be active for an Agent. To take over an existing session, run:

sudo /opt/monit-agent/monitagent shell-approval --replace

Only root can open or replace a session. Pending commands are rejected if the Agent restarts or the session disconnects, and you must open a new session after a restart. High-risk operations such as shutdown, reboot, system destruction, or reading sensitive credentials cannot be enabled through human approval.

Next step

After the Agent starts successfully, a host object usually appears on the monitoring object page within a few seconds. Next, read Configure Monitoring Objects to add database and middleware objects in agent.yaml.

Quick Start

Data Sources

Alert Engine

Alert Rules

Monitoring Objects

Active Alerts

Rule Repository

Folder Management

FAQ

Install monit-agent

Before you begin