Requirements

This page lists what a server needs before the Guardioz agent is installed on it, and what Guardioz does not support today. The procedure itself is on Install the agent.

PostgreSQL

What	Requirement
Version	PostgreSQL 18
Host	The same server that the agent is installed on
Socket directory	The default one: /var/run/postgresql on Linux, /tmp on FreeBSD
Database	A database named postgres. The agent connects to it for the statistics that cover the whole instance, and to each of your other databases in turn for their own statistics, up to 20 databases taken in the order of their names. See Limits.
Role	The installer creates the role guardioz_monitor, which the agent uses in read-only sessions, and grants it pg_monitor, the role built into PostgreSQL for monitoring tools. It allows reading statistics and settings. It does not allow reading the rows of your tables. Security and access has the details.

The agent runs on the same server as PostgreSQL, for two reasons. First, it connects over the local Unix socket, so no network port is opened to your database. Second, the agent measures the machine that it runs on - the memory, the processors and the disk under the data directory - and Guardioz computes its settings recommendations from those measurements. An agent on a different machine describes a machine that PostgreSQL does not run on. The recommendations that depend on hardware are then wrong for your server, and nothing in Guardioz marks them as such. For why the agent sends data out at all, see Security and access.

In the Guardioz web application, the setup page calls the monitoring role a monitoring user, and the page of a server shows its name next to User:.

The agent is built to keep its load on your database small. It collects about once an hour, runs its read-only queries one at a time, each with a time limit, and measures sizes on disk once a week. Guardioz is not real-time monitoring, and no email tells you that your database or your server stopped. See Why the agent collects once an hour.

The version is checked twice. The installer reads the version of every PostgreSQL instance it finds. When none of them runs PostgreSQL 18, the installer stops before it changes anything on the server. Guardioz checks the version again when the server registers. A refused version leaves the install command unused. You can move the instance to PostgreSQL 18 and run the same command again while that command is still valid. Install the agent says how long a command stays valid.

Operating system

System	Status
Linux with systemd	Supported. Verified on Debian 13 with PostgreSQL 18.
FreeBSD	Supported. Verified on FreeBSD 15.0 with PostgreSQL 18.

The Linux installer needs bash and systemd. Before it changes anything on the server, it checks for the programs listed in Software on the server and stops with a message that names what is missing. For systemd it checks for systemctl. If it stops on your system, write to contact@guardioz.com.

What is not supported

• PostgreSQL 17 and older, and any version newer than 18.
• Managed PostgreSQL services, where you cannot open a shell on the database server: Amazon RDS for PostgreSQL, Amazon Aurora, Azure Database for PostgreSQL, Google Cloud SQL, and hosted platforms such as Neon, Supabase, Railway, Render, Fly.io and Heroku Postgres. Support for Amazon RDS for PostgreSQL is planned.
• PostgreSQL in a container: Docker, Docker Compose, and platforms that deploy containers for you, such as Coolify, Dokploy and CapRover. The installer needs PostgreSQL and its local socket on the host that it runs on. When they are not there, it stops before it changes anything, with Error: psql not found. Install PostgreSQL client tools first., with Error: cannot connect to PostgreSQL., or with a message that starts with Error: Guardioz could not run commands as.
• PostgreSQL run by a Kubernetes operator, such as CloudNativePG.
• An agent that you place on another machine and point at the database over the network. The installer does not set the agent up that way. When the agent is made to run that way anyway, the result is misleading: the host profile then describes the agent’s machine, the disk figures for the data directory are missing or describe the wrong disk, and the settings recommendations that depend on hardware are computed for the wrong machine. The first section of this page explains why.
• Linux without systemd. When the systemctl command is missing, the installer stops before it changes anything, with Error: systemctl not found. The agent runs as a systemd service, and Linux without systemd is not supported.
• macOS and Windows.
• A replica (a standby server), also a replica in a high-availability cluster such as one managed by Patroni. Guardioz does not support replicas. Install the agent on the primary server. A replica is read-only, and the installer creates the monitoring role and sets its password, which PostgreSQL does not allow there. The installer checks the role of the instance before it changes anything, and on a replica it stops with Error: the PostgreSQL instance on port 5432 is a replica (a standby server)., with the port of your instance. The install command stays unused, so you can run the same command on the primary server. In a Patroni cluster, the primary is the member that patronictl list shows as Leader. Guardioz monitors the instance that you registered, not the cluster, and it does not follow a failover. When a failover turns that instance into a replica, its agent keeps sending snapshots, and the checks that apply only to a primary show Not evaluated: Open transactions and cleanup, Tables behind on cleanup, and Transaction log archiving when archive_mode is on. The new primary has no agent until you install one there, and it then starts in Guardioz as a new server, without history.
• A PostgreSQL instance whose Unix socket directory is not the default one.
• A host that reaches the internet only through an HTTP proxy. The agent has no proxy setting.
• A server that runs more than one PostgreSQL instance. The agent measures the whole server - its memory, its processors and the disk under the data directory - and it does not know what the other instances use. The settings recommendations that depend on hardware are then sized as if the registered instance had the server to itself, and nothing in Guardioz marks them as such. The index checks do not depend on hardware, so they are not affected. One install command registers one instance: the installer asks which one to register and changes nothing on the others.

If your case is on this list and you want to use Guardioz, write to contact@guardioz.com and say which one.

Privileges during the install

Where	What is needed
Operating system	root, or an account that can use sudo
PostgreSQL	An account that can create roles and grant pg_monitor: a superuser, or a role with CREATEROLE that also has the ADMIN option on pg_monitor

When you run the installer from an account that is not root and cannot use sudo, the installer stops with a message and changes nothing on the server.

The installer needs administrator rights, and the agent runs without them. What the installer sets up belongs to the operating system or to the account that owns PostgreSQL: it creates a system account for the agent’s service, it makes root the owner of the agent’s code and configuration file, and it writes the service definition. The service then runs under that system account, and the installer confirms it by reading the account of the running process. PostgreSQL from your system’s packages is set up the same way: installed with administrator rights, run under its own account without them. The reasoning, and a command that shows the account on your own server, are in Why the installer needs administrator rights.

The installer reaches PostgreSQL over the local socket, and it does not ask you which PostgreSQL account to use. It tries, in this order, the account named in the PGUSER environment variable, the account you run the installer from, and the account that owns the running PostgreSQL process (usually postgres). It uses the first one that can connect and can create roles. When none of them can, the installer stops before it changes anything on the server. It tries them on the port of each PostgreSQL instance it finds running on the server, not only on 5432. The account that owns PostgreSQL connects with its own settings: the installer does not pass the PG variables of your session, such as PGUSER, to it.

The installer uses that account to create the monitoring role and to grant it pg_monitor. Its own check tests only whether the account is a superuser or has CREATEROLE. An account that can create the role but cannot grant pg_monitor gets past that check, and the installer reports the grant either way. The agent then reads less than it needs, and part of the collected data is recorded as not measured. When you do not install as a superuser, confirm first that your account can grant pg_monitor.

The monitoring role’s password is generated on your server and written to the agent’s configuration file there. Guardioz stores no password for your database. The agent does not run as root: the installer creates a system account for it. On FreeBSD, daemon(8), the program that supervises the agent, stays under root and starts the agent under that account. The full list of changes is on What the installer changes on your server.

Software on the server

Linux

Software	What it is for
bash	The install command downloads the installer and runs it with bash. The installer is a plain text file, so you can save it and read it before you run it: see Install the agent.
systemd	The agent runs as a systemd service, one service per PostgreSQL port.
psql	The installer uses it to reach PostgreSQL.
Python 3.11 or newer, with the venv module	The agent is a Python program and runs in its own virtual environment.
curl	The install command uses it, and the installer downloads the agent with it.
tar, openssl	Unpacking the agent and generating the monitoring role’s password.

On Debian and Ubuntu the venv module comes from the python3-venv package. The installer stops with a message that names the package when Python cannot create a virtual environment.

The installer uses python3 when it is Python 3.11 or newer. On some systems python3 is older: Python 3.10 on Ubuntu 22.04, and Python 3.9 on Red Hat Enterprise Linux, Rocky Linux and AlmaLinux 9. There the installer looks for python3.14, python3.13, python3.12 and python3.11, in that order, and uses the first one that can create a virtual environment. Install one of them next to the system Python before you run the install command: python3.11 and python3.11-venv on Ubuntu 22.04, or python3.11 on the Enterprise Linux 9 family. Do not replace the system python3, because the operating system’s own tools use it. When no Python is new enough, the installer stops before it changes anything on the server.

The installer also gives the agent’s system account permission to enter the PostgreSQL data directory. This is traverse permission only: the account cannot list the directory and cannot read the files in it. The agent needs it to measure the free space of the transaction log directory (pg_wal). The grant uses setfacl, and the installer installs the acl package when setfacl is missing. This is the only system package the Linux installer adds. When the grant does not work, the install continues and the free space of the transaction log directory is recorded as not measured.

FreeBSD

Software	What it is for
psql	The installer uses it to reach PostgreSQL.
fetch	The install command uses it.
pkg with a reachable repository	The installer installs the agent’s Python dependencies from it.
sudo, when you do not run the installer as root	Every privileged step goes through it.

Python does not have to be installed beforehand. The installer looks in the pkg repository for a Python version that has the psycopg2, pyyaml and requests packages. It installs that Python version when it is missing, and it stops with a message when the repository has no such version.

Network access

Destination	Direction	Port	When
app.guardioz.com	Outbound from your server	443/TCP	During the install, and for every snapshot afterwards
The Python package index: pypi.org, and files.pythonhosted.org for the downloads. A server configured with its own index uses that one instead.	Outbound from your server	443/TCP	Linux install only
Your distribution’s package repository	Outbound from your server	As configured	Linux install only, and only when setfacl is missing
The FreeBSD pkg repository	Outbound from your server	As configured	FreeBSD install only

Every connection starts on your server. Guardioz opens no connection to your server, and no inbound port is opened. The PostgreSQL port is not exposed either: the installer opens no network access for the monitoring role. When that role cannot already connect, the installer adds one rule for the local socket. Access to app.guardioz.com must stay open after the install, because that is where each snapshot goes.

Your browser

Guardioz runs at https://app.guardioz.com/ in a web browser. JavaScript must be turned on. The page that shows the install command needs it to create the command and to update its status while the installer runs, and the Copy buttons on a finding need it.

Next steps

Install the agentChoose the operating system of the server where PostgreSQL runs.

What the installer changes on your serverEvery change on the host and in PostgreSQL, and how each one is recorded.

Security and accessWho connects to your database, with which rights, and where the data goes.