Configuration reference

The agent is configured via a YAML file (default: config.yaml in the same directory as the binary). Running --init generates this file automatically. Every field is documented below.

Full example

cluster:
  name: "My Production Cluster"
  endpoint: "https://localhost:9200"
  environment: "production"
  username: "osd-agent"
  password: "your-password"
  # api_key: "base64-encoded-opensearch-api-key"
  tls_skip_verify: false
  # ca_cert_path: "/etc/ssl/certs/my-ca.pem"

saas:
  api_url: "https://opensearchdoctor.com"
  api_key: "osd_your_key_here"

agent:
  interval_minutes: 360
  heartbeat_seconds: 300
  log_file: "agent.log"
  # enabled_categories:
  #   - cluster_health
  #   - nodes

cluster

Connection settings for your OpenSearch cluster.

Field	Type	Default	Description
`cluster.name`	string	—	Required. Display name shown in the dashboard. Use something meaningful like `production` or `staging-eu`.
`cluster.endpoint`	string	—	Required. Full URL including port, e.g. `https://localhost:9200`.
`cluster.environment`	string	`production`	Environment tag. One of: `production`, `staging`, `development`, `custom`.
`cluster.username`	string	—	OpenSearch username. Use this OR `api_key`, not both.
`cluster.password`	string	—	OpenSearch password. Required when using username auth.
`cluster.api_key`	string	—	Base64-encoded OpenSearch API key. Use this OR username/password, not both.
`cluster.tls_skip_verify`	bool	`false`	Set to `true` to skip TLS certificate verification. Required for self-signed certificates without a custom CA. Not recommended for production if avoidable.
`cluster.ca_cert_path`	string	—	Path to a custom CA certificate in PEM format. Use when your OpenSearch cert is signed by a private/internal CA and you want proper verification instead of skipping it.

saas

Connection settings for the OpenSearch Doctor platform.

Field	Type	Default	Description
`saas.api_url`	string	`https://opensearchdoctor.com`	Platform API URL. Only change this if you are self-hosting the backend.
`saas.api_key`	string	—	Required. Your agent API key from Settings → Agent Keys. Starts with `osd_`.

agent

Controls how often the agent runs and where it logs.

Field	Type	Default	Description
`agent.interval_minutes`	int	`360`	How often to run a full diagnostic, in minutes. Default is 6 hours. Set to `30` for more frequent checks (uses more API quota). Minimum recommended: 15.
`agent.heartbeat_seconds`	int	`300`	How often the agent sends a heartbeat, in seconds. The dashboard marks the agent offline if no heartbeat is received for 30 minutes.
`agent.log_file`	string	`agent.log`	Path to the log file. Relative paths are resolved from the directory where the agent binary is located.
`agent.enabled_categories`	[]string	all	Limit which check categories run. Leave empty (or omit) to run all 11 categories. Valid values: `cluster_health`, `nodes`, `shards`, `indices`, `performance`, `snapshots`, `ism_policies`, `security`, `plugins`, `ingest_pipelines`, `templates`.

Environment variable override

You can override the platform URL without editing the config file — useful for containers:

OPENSEARCH_DOCTOR_URL=https://your-instance.example.com ./agent --config config.yaml

File permissions

The --init wizard writes config.yaml with 600 permissions (owner read/write only). If you create the file manually, set the same:

chmod 600 config.yaml

← Installation Next: What it checks →