Quickstart

This page takes you from no account to the first findings for one PostgreSQL 18 server. It follows one path: an account with an email address and a password, a Linux server, and one PostgreSQL instance on that server. The installer changes no PostgreSQL setting, and PostgreSQL is not restarted at any point.

The agent is a small program that runs on your server, reads PostgreSQL’s own statistics and sends them to Guardioz. A finding is one result of one check: what Guardioz found on your server, why it matters, and what you can do about it. For the whole picture, see How Guardioz works.

Before you start

You need at least the following. The full list, including what is not supported, is in Requirements.

A server that runs PostgreSQL 18 on Linux, with systemd. PostgreSQL 17 and older are not supported: the installer reads the version of every instance it finds, registers no other version, and stops before it changes anything on the server when no instance runs PostgreSQL 18.
bash, curl, tar, openssl, psql, and Python 3.11 or newer with its venv module on that server. On Debian and Ubuntu the venv module comes from the python3-venv package.
Administrator rights on that server: the root account, or an account that can use sudo. The installer detects which of the two it has. The installer needs those rights, and the agent runs without them: the installer uses them to create a system account for the agent and to make root the owner of the agent’s code, so the running agent cannot change it. PostgreSQL from your system’s packages is set up the same way. See Why the installer needs administrator rights.
Outbound HTTPS from that server to app.guardioz.com. This connection stays in use: the agent opens it to send its data.
Outbound HTTPS from that server to the Python package index, pypi.org and files.pythonhosted.org, during the installation only.
A browser on your own computer.

A PostgreSQL instance is one running PostgreSQL server with its own port and its own data directory. This page covers one instance, because one install command registers one instance. A server that runs more than one PostgreSQL instance is not supported, because the settings recommendations that depend on hardware are computed for the whole server: see Requirements. For a FreeBSD server, see Install on FreeBSD.

Guardioz is in beta. You can sign up, and the product is early - we say so up front. Always free for one user. The Team plan costs $49 per user per month. Creating an account needs no credit card.

Create your account

In your browser, open https://app.guardioz.com/. Guardioz shows the sign-in page with the heading Sign in to Guardioz.
Click Register. Guardioz opens the page Create your Guardioz account.
The form asks for your name, an organization name, your email address and a password of at least 8 characters. The organization name groups your servers in Guardioz, so your company name is a good choice. Enter the four values, and then click Create your account. Guardioz shows the page Check your inbox.
In your mailbox, open the message with the subject Confirm your email - Guardioz and click Confirm Email. Guardioz opens the page Confirm your email address.

The message usually arrives within a few minutes. If it is not there, look in the spam folder, and then see Sign-in and email problems.
Click Confirm email address. Guardioz shows Email confirmed. Opening the link does not confirm the address on its own. The button does.
Click Sign in. Type your email address and your password, and then click Login. Guardioz signs you in and opens the page Select the platform you want to monitor.

Get the install command

Click the card Self-Managed PostgreSQL. Guardioz opens the page Configure Self-Managed PostgreSQL and generates one install command for you.
Leave the operating-system buttons on Linux, and then click Copy command. The button changes to Copied! for two seconds.

The command carries a one-time token and is valid for 60 minutes. After that it no longer works: reload the page to get a new command, and copy that one. Your account stays as it is.
Keep this browser tab open. Under the command the page shows Waiting for server registration… and updates that line by itself while the installer runs.

Run the install command on your server

On your server the installer does the following.

It creates a monitoring role in PostgreSQL, which the agent uses in read-only sessions.
If that role cannot connect over the local socket, it adds one rule for the role to the client authentication file (pg_hba.conf) and reloads the configuration.
It installs the agent under /opt/guardioz-agent.
It installs one service for the PostgreSQL instance and starts it.
It records what it changed in /etc/guardioz-agent/install-manifest.txt, together with how to reverse each change.

The complete list of changes is on What the installer changes on your server. To read the script before you run it, see Install the agent.

If the installer finds more than one PostgreSQL 18 instance, it lists them and asks which one to register. One install command registers one instance, so enter one number. See Install on Linux for the prompt and what to enter.

Open a shell on the server that runs PostgreSQL, as root or as an account that can use sudo. Use an interactive session: when sudo needs a password, it has to be able to ask for it.
Paste the command you copied, and then run it. Do not put sudo in front of it, because the installer elevates the steps that need administrator rights by itself. Your command looks like the following, with a one-time token of your own in place of the three dots:
Terminal window
```
curl -fsSL "https://app.guardioz.com/api/v1/setup/install.sh?token=..." | bash
```
When you run it from an account whose sudo needs a password, sudo asks for it before anything on the server changes. The installer then prints what it does at each step. The last lines are similar to the following:
```
...
=== Setup complete! ===

  Registered instances: 1
  Config dir: /etc/guardioz-agent/
  Services: systemctl list-units 'guardioz-agent-*'
  Dashboard: https://app.guardioz.com/servers
```

Exit code 0 means that the server was registered, and it includes a run whose heading reads === Setup finished with errors ===, so read the last lines as well as the exit code. When the run reached the registration step and registered nothing, the last lines read Registered instances: 0 and the exit code is 1. A run that stopped before that step ends with a line that starts with Error: instead. When the heading reads === Setup finished with errors ===, look back through the output for the first error message, and then see Installation problems.

Wait for Guardioz to confirm the installation

Go back to the browser tab with the install command. The page checks the status every three seconds without reloading, and the status line under the command moves through three texts:

Waiting for server registration… - Guardioz has not received the registration yet.
Server registered, installing agent… - the server is registered. The installer is collecting and sending the first snapshot, and then it installs and starts the agent’s service. This step takes longer on a large database.
Agent installed and running! - the service runs.

The card Setup complete! then appears, and Guardioz opens the Findings page by itself after a few seconds.

The installer registers the server and sends the first complete snapshot in the same step. A snapshot is one set of measurements that the agent sends to Guardioz, so the first results do not wait for the hourly collection.

If the line stays on Waiting for server registration… after the installer has finished, Guardioz received no registration from this command. Read the last lines the installer printed, and then see Installation problems.

If the line stays on Server registered, installing agent…, the server is registered and appears under Servers. Either the agent’s service did not start, or the installer’s final message did not reach the page. The last lines the installer printed say which of the two it is. For both, see Installation problems.

Read your first findings

Guardioz has already opened the Findings page for you. If you are somewhere else, open Findings in the top navigation. The page opens on the view Issues only and lists one row for each group of checks that needs attention, most serious first.
Click a row. The page that opens lists what the finding is about, for example a PostgreSQL setting or an index, most serious first.
For a setting or an index, click its row. Its own page shows what Guardioz measured on your server and what to do next. Where Guardioz can give an exact statement, the page shows it with a Copy button.
To see the checks that passed as well, go back to Findings and change the drop-down that reads Issues only to All checks.

The first results appear within a few minutes of the setup page reporting success. Until the first snapshot is stored, the page shows the heading All clear with the subtitle No snapshots received yet. Together they mean that nothing is stored yet, not that the checks found nothing. Reload the page a few minutes later. If the subtitle still reads No snapshots received yet., see Agent and data problems.

All clear with a subtitle that names the time of the latest snapshot means that no group of checks has an open finding on your servers. Right after the installation the analysis of the first snapshot can still be running, so reload the page once if you see this in the first minutes.

From now on the agent collects once an hour. After its service starts, the first time and after every later restart, it waits one full hour before the next collection. The installation already sent the first snapshot. See When the agent collects.

Next steps

Read your findingsSeverities, views, states, and what Age counts.

Apply a recommendationWhere to run a statement, and when the finding changes afterwards.

Check that the agent worksService status, the log line that proves a snapshot was sent.

If something did not work, see Installation problems or Agent and data problems. If neither helps, write to contact@guardioz.com - see Get help.