DOCS

Product Guide

Everything you need to install, connect and run ClusterEye in production: architecture, the ports to open, the minimum database privileges per engine, and the install commands.

Overview

ClusterEye has three components: the Agent running on monitored hosts, the central API, and the web UI. Data flows one way — the agent dials out, and ClusterEye never opens an inbound connection into your database.

The agent collects

Runs on the monitored host, connects to the database with a read-only account and reads host metrics from /proc.

Ships over gRPC

Streams to the API over a single outbound TLS connection (443/tcp). The agent opens no listening port.

The API processes and stores

Metadata goes to PostgreSQL, time-series metrics to InfluxDB; the anomaly, baseline and correlation engines run here.

The UI shows it

Served from the same 443 port: dashboards, alerts, RCA and reports.

Two collection modes

AGENT-BASED

PostgreSQL, MongoDB, MS SQL Server, Oracle, MySQL/MariaDB, ClickHouse. The agent runs on the database host, which is what makes host metrics, log analysis and config drift possible.

AGENTLESS

Azure SQL (Database + Managed Instance), Azure PostgreSQL Flexible Server, Redis, Elasticsearch/OpenSearch. The connection is made directly from the ClusterEye API server; nothing is installed on the target — which is the only option for managed services. Host-level metrics are not collected in this mode.

Network & ports

The rules to open in the customer firewall. The agent only ever dials out — you never need to expose an inbound port on a monitored host.

RequiredOptional / situationalLocalhost only — no firewall rule

FROMTOPORTPROTOCOL

Agent hostClusterEye server443/tcpgRPC over HTTP/2 (TLS)

The agent's only outbound connection. nginx terminates TLS and forwards gRPC to the API. Outbound only.

Agent hostClusterEye server80/tcpgRPC h2c (plaintext)

Alternative for internal networks without TLS. Used when the agent is installed without --tls.

Browser (DBA/SRE)ClusterEye server443/tcpHTTPS

Web UI and REST API. The same port carries both UI and gRPC traffic.

Agent hostarchive.clustereye.com443/tcpHTTPS

Only for install and auto-update of the agent. In air-gapped setups copy the binary manually (-b flag).

nginxClusterEye API50051/tcpgRPC

Listens on 127.0.0.1 — never exposed, no firewall rule needed.

nginxClusterEye API8080/tcpHTTP

REST API upstream. Listens on 127.0.0.1.

ClusterEye APIPostgreSQL (metadata)5432/tcpPostgreSQL

Platform metadata database. Local with --postgres=local, or a separate host with external.

ClusterEye APIInfluxDB8086/tcpHTTP

Time-series metrics. Can be disabled entirely with --influxdb=none (metric charts are then unavailable).

AgentPostgreSQL5432/tcpPostgreSQL

Usually localhost — the agent runs on the database host it monitors.

AgentMongoDB27017/tcpMongoDB wire

The mongos port on sharded clusters; mongod directly on replica sets.

AgentMS SQL Server1433/tcpTDS

Dynamic port or SQL Browser (1434/udp) if a named instance is used.

AgentOracle1521/tcpOracle Net

Listener port. Connects to the CDB$ROOT or a PDB service name.

AgentMySQL / MariaDB3306/tcpMySQL

performance_schema must be enabled.

AgentClickHouse9000/tcpNative protocol

The HTTP interface (8123) is not used — the native protocol is required.

ClusterEye APIRedis6379/tcpRESP

Agentless engine: the connection originates from the API server, not from an agent.

ClusterEye APIAzure SQL (Database / MI)1433/tcpTDS over TLS

Agentless engine. Allow the ClusterEye API server's egress IP in the Azure SQL firewall, or use a private endpoint / VNet integration.

ClusterEye APIAzure PostgreSQL Flexible Server5432/tcpPostgreSQL over TLS

Agentless engine. TLS is mandatory (sslmode=require). Requires a firewall rule or private access (VNet).

ClusterEye APIElasticsearch / OpenSearch9200/tcpHTTPS/HTTP

Agentless engine. Oracle DML Audit ingest uses the same cluster.

The short version for firewalls

For most deployments one rule is enough: outbound TCP from every database host to 443/tcp on the ClusterEye server. Database ports (5432, 1433, 1521, 27017, 3306, 9000) are usually loopback because the agent runs on the same machine, so they never reach the firewall. The agentless engines (Azure SQL, Azure PostgreSQL, Redis, Elasticsearch) are the exception: those ports must be reachable from the ClusterEye API server, and the Azure ones additionally need a firewall rule or private endpoint.

Quick start

Pick the one that fits — all three are one-command installs.

FULL STACKEnd-to-end platform on a single host — ideal for dev & POC.

Kind + Helm

Installs Kind, Helm and the complete ClusterEye stack on Ubuntu 24.04.

bash

1curl -sSL https://archive.clustereye.com/clustereye-stack-install.sh | bash

STANDALONEProduction-ready — nginx + TLS + systemd.

Bare-metal Linux

Full platform directly on Linux — no Docker, no Kubernetes.

bash

1curl -fsSL https://archive.clustereye.com/deploy/standalone/install.sh | sudo bash -s -- \
2  --api-version=VERSION --ui-version=VERSION \
3  --domain=YOUR_DOMAIN_OR_IP --postgres=local

AGENTPlatforms: postgres · mongo · oracle · mysql

Agent only (Linux)

Just the agent, talking to an existing ClusterEye server.

bash

1curl -sSL https://archive.clustereye.com/install.sh | sudo bash -s -- \
2  -p postgres --api-url <clustereye-host> --tls

Standalone install

ClusterEye API + UI on bare-metal Linux servers — no Docker, no Kubernetes. Comes with nginx reverse proxy.

Ubuntu 22.04+RHEL 8/9Oracle Linux 8/9

ClusterEye API

Go binary — REST API (:8080) + gRPC (:50051)

ClusterEye UI

Pre-built static frontend assets

nginx

Reverse proxy — TLS + plaintext h2c, HTTP/2, gRPC

PostgreSQL

Local or external database

InfluxDB

Optional time-series metrics

Single-command install (no Docker)

Auto-generated 10-year self-signed TLS certificate

nginx reverse proxy — HTTPS + plaintext h2c side-by-side

HTTP/2 and gRPC support (TLS and plaintext)

Optional local or external PostgreSQL

Optional local or external InfluxDB

Hardened systemd service

Independent API and UI versioning

Install options

All install.sh flags.

REQUIRED

--api-version=<ver>API binary version

--ui-version=<ver>UI assets version

--domain=<host|ip>Server domain or IP

POSTGRESQL

--postgres=local|externalMode (default: local)

--postgres-host=<host>External PG host

--postgres-port=<port>External PG port (default: 5432)

--postgres-user=<user>External PG user (default: postgres)

--postgres-password=<pwd>External PG password

--postgres-dbname=<n>DB name (default: clustereye)

--postgres-sslmode=<mode>SSL mode (default: disable)

INFLUXDB

--influxdb=local|external|noneMode (default: local)

--influxdb-url=<url>External InfluxDB URL

--influxdb-token=<token>External InfluxDB token

--influxdb-org=<org>Org (default: clustereye)

--influxdb-bucket=<bucket>Bucket (default: clustereye)

TLS

--tls=self-signed|providedMode (default: self-signed)

--cert=<path>Cert file (with --tls=provided)

--key=<path>Key file (with --tls=provided)

NETWORK

--port=<n>HTTPS port (default: 443)

--http-port=<n>|nonePlaintext h2c port (default: 80)

--bind-host=<host>Bind address (default: 0.0.0.0)

--extra-hostnames=a,b,cAdditional TLS SANs

OTHER

--no-firewallSkip firewall config

-h, --helpShow help

--versionShow installer version

Upgrade

In-place upgrade of API binary or UI assets. Config, secrets, TLS and databases are preserved.

bash

1curl -fsSL https://archive.clustereye.com/deploy/standalone/upgrade.sh | sudo bash -s -- \
2  --api-version=NEW --ui-version=NEW

--api-version=<ver>Upgrade API binary to this version

--ui-version=<ver>Upgrade UI assets to this version

-h, --helpShow help

Uninstall

Without flags: removes systemd service, binary, nginx config and journald drop-in. Configs, secrets, TLS and databases are preserved.

bash

1sudo ./uninstall.sh --purge --purge-db --purge-influxdb --yes-i-mean-it

(no flags)Remove only binary, systemd, nginx, journald

--purgeAlso remove /etc/clustereye, /var/lib/clustereye, /var/log/clustereye, web assets, user/group

--purge-dbAlso remove local PostgreSQL packages and data

--purge-influxdbAlso remove local InfluxDB packages and data

--yes-i-mean-itSkip confirmation prompt

ClusterEye Agent

Agent for PostgreSQL, MongoDB, Oracle, MySQL/MariaDB, MS SQL Server and ClickHouse. It runs on the monitored database host and opens only an outbound gRPC connection.

Linux one-liner:

bash

1curl -sSL https://archive.clustereye.com/install.sh | sudo bash -s -- -p postgres

-p, --platformRequired — postgres, mongo, oracle or mysql

--api-urlClusterEye API server address (host or host:port)

--registration-tokenOne-time registration token generated in the UI

-d, --install-dirInstall directory (default: /opt/clustereye)

-b, --local-binaryCopy a local binary instead of downloading a release (air-gapped)

--tlsUse TLS for the gRPC connection (default: off)

-k, --insecureSkip TLS certificate verification (for self-signed certs, with --tls)

Windows

For Windows x64:

clustereye-agent.exe

ClusterEye Agent for Windows

↓ Download

clustereyesetup.exe

Setup wizard for Windows

↓ Download

agent.yml.example

Example configuration file

↓ Download

Minimum privileges per engine

The smallest privilege set the customer must grant the ClusterEye monitoring account. The baseline is read-only and safe to grant everywhere; the optional rows are needed only if you want the matching action feature.

PostgreSQL

Agent-basedDefault port: 5432

BASELINE — READ-ONLY

sql

1CREATE ROLE clustereye LOGIN PASSWORD '<strong-password>';
2
3-- pg_monitor = pg_read_all_settings + pg_read_all_stats + pg_stat_scan_tables
4GRANT pg_monitor TO clustereye;
5
6-- repeat for every monitored database
7GRANT CONNECT ON DATABASE <db> TO clustereye;
8
9-- pg_hba.conf: allow clustereye from the agent host (scram-sha-256)

PREREQUISITES & NOTES

shared_preload_libraries = 'pg_stat_statements' (restart required) — for query intelligence

CREATE EXTENSION pg_stat_statements; — top queries / query analysis

CREATE EXTENSION pgstattuple; + GRANT EXECUTE ON FUNCTION pgstattuple(regclass), pgstatindex(text) — bloat analysis

Optional: CREATE EXTENSION hypopg; — hypothetical validation of index advice

The agent OS user must read postgresql.conf, pg_hba.conf and the log directory (add it to the postgres group)

OPTIONAL — FEATURE-GATED

FEATUREREQUIRED GRANT

Kill / cancel sessionGRANT pg_signal_backend TO clustereye;

Tuning Advisor apply (ALTER SYSTEM + reload)

SUPERUSER — or PG 15+: GRANT ALTER SYSTEM ON PARAMETER <knob> TO clustereye; GRANT EXECUTE ON FUNCTION pg_reload_conf() TO clustereye;

Missing-index apply / rollback, REINDEXOwnership of the target tables (or CREATE on schema). Advice + HypoPG validation work without it.

Failover / promote / rebuild

OS: sudo -u postgres pg_ctl (NOPASSWD), pg_rewind/pg_basebackup; replication user needs REPLICATION + EXECUTE on pg_ls_dir, pg_stat_file, pg_read_binary_file

The baseline is fully read-only. A missing grant only disables that collector with a warning — the agent still starts.

What happens if a grant is missing?

No collector ever takes the agent down over a missing privilege. That collector logs a warning, the capability is marked unavailable, and everything else keeps running. Action features (kill, plan forcing, tuning apply) fall back to recommend-only.

Verify & troubleshoot

What to check in the first five minutes after an install.

Is the agent service up?

If the service runs but the node never shows up in the UI, it is almost always networking or database credentials.

bash

1systemctl status clustereye-agent
2journalctl -u clustereye-agent -f --no-pager

Can it reach the API?

Run this from the agent host. No answer means the 443/tcp rule; if you use a self-signed certificate install the agent with -k.

bash

1curl -sS -o /dev/null -w '%{http_code}\n' https://<clustereye-host>/api/v1/health

Is the database account sufficient?

This succeeds once the baseline grants are in place. Use the equivalent for your engine (Oracle: V$SESSION, MSSQL: sys.dm_exec_sessions).

bash

1psql -h <host> -U clustereye -c 'SELECT count(*) FROM pg_stat_activity;'

Query intelligence empty?

If metrics flow but the query list stays empty, the missing piece is almost certainly an engine prerequisite: pg_stat_statements, Query Store, performance_schema or log_queries.

bash

1SELECT * FROM pg_extension WHERE extname = 'pg_stat_statements';

Releases

Linux x86_64 agent binaries. Verify with SHA256.

VERSIONDATEARCHDOWNLOAD

v2.0.34LATESTJun 23, 2026x86_64

SHA256 ↓ bin

v2.0.33Jun 11, 2026x86_64

SHA256 ↓ bin

v2.0.32Jun 11, 2026x86_64

SHA256 ↓ bin

v2.0.28Jun 1, 2026x86_64

SHA256 ↓ bin

ARM64 support is available since v2616101459 (Sep 16, 2025). Windows x64 binaries are also downloadable.