Installation

The agent is a single binary — no runtime, no Docker, no dependencies. Download it, run --init, and your cluster appears in the dashboard within seconds.

Requirements

Linux, macOS, or Windows (x86_64 or ARM64)
Network access from the agent host to your OpenSearch cluster
Network access from the agent host to opensearchdoctor.com on port 443
An OpenSearch user with read-only access — see minimum permissions
An agent key from your dashboard — Settings → Agent Keys

Linux Installation

⚡ One-liner install (recommended)

Downloads the binary, verifies the checksum, installs it to /usr/local/bin, and launches the setup wizard.

curl -sSL https://opensearchdoctor.com/install.sh | sudo bash

The installer will launch the interactive setup wizard (--init) which guides you through:

Your OpenSearch cluster URL
A display name for the cluster
OpenSearch credentials (username/password or API key)
TLS options (skip / system CA / custom CA file)
Your OpenSearch Doctor API key

After config, the wizard installs the agent as a systemd service — it starts automatically on every boot.

Manual installation

Download the binary

# x86_64
curl -Lo agent https://github.com/opensearch-doctor/agent/releases/latest/download/agent-linux-amd64 && chmod +x agent

# ARM64
curl -Lo agent https://github.com/opensearch-doctor/agent/releases/latest/download/agent-linux-arm64 && chmod +x agent

Run the setup wizard

./agent --init

Manual systemd setup (if you skipped it in --init)

sudo tee /etc/systemd/system/opensearch-doctor-agent.service > /dev/null <<EOF
[Unit]
Description=OpenSearch Doctor Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/agent --config /etc/opensearch-doctor/config.yaml
Restart=always
RestartSec=30
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now opensearch-doctor-agent

Useful commands:

sudo systemctl status opensearch-doctor-agent
sudo journalctl -u opensearch-doctor-agent -f
sudo systemctl restart opensearch-doctor-agent

Verify it's working

After starting the agent, go to your dashboard. The cluster appears within seconds (heartbeat interval is 5 minutes by default). The first diagnostic run starts immediately.

To test locally without sending data to the platform:

./agent --config config.yaml --test

This prints a summary of what was collected and exits without sending anything.

CLI flags reference

Flag	Description
--init	Run the interactive setup wizard
--config <path>	Path to config file (default: config.yaml)
--once	Run diagnostics once and exit — good for cron
--test	Collect and print locally; do NOT send to platform

Next: Configuration reference →