Quickstart: connect your first Postgres database

Praxion installs nothing on your database and asks for no inbound access. The agent is a single process you run inside your own network — a Docker container or a native binary — and it opens an outbound connection to the control plane. It reads pg_stat_statements from your read-only replica, anonymizes what it finds, and sends metadata only. The rows in your tables never leave your network.

Connecting a database takes two moves: run the agent, then tell the dashboard which database to watch. The Connect a database screen in the dashboard walks you through both.

0Prerequisites

• A Praxion workspace — sign up at dashboard.praxionapp.com
• A Postgres replica you can reach from the machine that will run the agent, with a read-only user on it
• pg_stat_statements enabled on that replica (step 1)
• Docker, or permission to download and run the native binary on Windows (x64), macOS (Intel or Apple silicon), or Linux (x64)
• Outbound HTTPS from that host to the control plane. Nothing needs to be exposed inbound.

1Enable pg_stat_statements on the replica

The agent reads query statistics from pg_stat_statements, so the extension has to be loaded on the replica. If it is not already on, add it to shared_preload_libraries and restart the replica:

# postgresql.conf
shared_preload_libraries = 'pg_stat_statements'

CREATE EXTENSION pg_stat_statements;

Confirm it is live:

SELECT count(*) FROM pg_stat_statements;

The count can be zero on a freshly restarted instance — that is fine. It starts recording from the restart onward.

2Create the agent credentials

In the dashboard, open Connect a database and look at 1. Create the credentials.

Name the agent first — it is optional, but it is worth it. The name is shown on the Agents screen next to the id, and it names the folder the agent installs into: ~/.praxionagents/<name> rather than wherever the terminal happened to be. Give each agent on a machine a different name — orders-replica, eu-west-primary.

Then press Create AGENT_ID and LICENSE_KEY. The license key authenticates everything the agent sends, and it is shown once only: Praxion stores a hash of it and no plaintext copy, so it cannot be shown again. If you lose it, you create a new pair and redeploy.

3Paste the replica connection string (optional)

The Connection string field takes a DSN in the usual shape:

postgres://user:password@host:5432/database

It is assembled into the commands below in your browser and is never sent to Praxion — you can paste it straight from your provider. Leave it empty and the commands print a placeholder you can fill in later.

Paste it before you copy the commands in the next step: the DSN is substituted into them as you type, so the block you copy is the block you can run.

4Start the agent

Under 2. Start the agent pick Docker or Native binary. For the native binary, the Operating system selector is preselected from your browser — change it if the agent will run on a different machine, which it usually will.

Docker

The dashboard prints a two-line command. It is the same on every platform:

docker pull ghcr.io/phjcherry/praxion-agent:latest

docker run -d --name praxion-agent \
  --restart unless-stopped \
  -e AGENT_ID=<AGENT_ID> \
  -e LICENSE_KEY=<LICENSE_KEY> \
  -e CONTROL_PLANE_URL=https://praxion-api-782r.onrender.com \
  -e PG_REPLICA_DSN="postgres://YOUR_DB_USER:YOUR_PASSWORD@YOUR_DB_HOST:5432/YOUR_DATABASE" \
  -p 8081:8080 \
  ghcr.io/phjcherry/praxion-agent:latest

Native binary

Four steps: a folder, the binary, the credentials beside it, then run it. On Linux or macOS:

# 1. A folder for this agent, with the others
mkdir -p ~/.praxionagents/agent && cd ~/.praxionagents/agent

# 2. The agent
curl -fsSL -o agent "https://github.com/phjcherry/praxion-agent/releases/latest/download/praxion-agent_linux_amd64"
chmod +x agent

# 3. Its credentials, beside it
cat > .env <<'PRAXION_ENV'
AGENT_ID=<AGENT_ID>
LICENSE_KEY=<LICENSE_KEY>
CONTROL_PLANE_URL=https://praxion-api-782r.onrender.com
PG_REPLICA_DSN=postgres://YOUR_DB_USER:YOUR_PASSWORD@YOUR_DB_HOST:5432/YOUR_DATABASE
PRAXION_ENV

# 4. Run it — no flags: it reads the .env beside it
./agent

On Windows (x64) the dashboard prints the PowerShell equivalent, which downloads praxion-agent_windows_amd64.exe with Invoke-WebRequest. Two things to know there:

# 1. A folder for this agent, with the others
$dir = Join-Path $HOME ".praxionagents\agent"
New-Item -ItemType Directory -Force $dir | Out-Null
Set-Location $dir

# 2. The agent
Invoke-WebRequest -Uri "https://github.com/phjcherry/praxion-agent/releases/latest/download/praxion-agent_windows_amd64.exe" -OutFile agent.exe

# 3. Its credentials, beside it
@'
AGENT_ID=<AGENT_ID>
LICENSE_KEY=<LICENSE_KEY>
CONTROL_PLANE_URL=https://praxion-api-782r.onrender.com
PG_REPLICA_DSN=postgres://YOUR_DB_USER:YOUR_PASSWORD@YOUR_DB_HOST:5432/YOUR_DATABASE
'@ | Set-Content -Encoding utf8 .env

# 4. Run it — no flags: it reads the .env beside it
.\agent.exe

• Run it from a terminal, not by double-clicking. The agent is a console program, so Explorer closes the window before you can read why it stopped.
• If Windows says "Windows protected your PC", that is SmartScreen reacting to an unsigned download. Choose More info → Run anyway, or use the Invoke-WebRequest line above, which does not trigger it.
• There is a checksums.txt next to each release if you want to verify the download.

What goes in the environment

• AGENT_ID — from step 2. Identifies this agent on the Agents screen.
• LICENSE_KEY — from step 2. Authenticates everything the agent sends.
• CONTROL_PLANE_URL — the Praxion control plane the agent reports to.
• PG_REPLICA_DSN — the read-only connection string for your replica.

5Register the database

The agent reporting is only half of it. Scroll to Register the database and add the database you want Praxion to watch:

• Agent — which agent owns this database. Only agents that have already sent a heartbeat appear in this list; if yours is missing, go back to step 2.
• Host — for example replica.internal.mycompany.local. It is used only to compute a unique identifier and is never stored in plain text.
• Database name — for example production. Treated the same way: fingerprinted together with the host, and the original is discarded.
• Engine — PostgreSQL. Postgres only for now.
• Version — optional. Leave it empty and it is filled in from the agent's report.

Then press Connect. This is the part that gets billed: one line per distinct database, and reconnecting the same one does not count twice.

6Verify it is working

Open Agents. An agent counts as running if it reported in the last 90 seconds:

If something is not working

• The agent is not in the Agent list. That list only shows agents that have already sent a heartbeat, so if yours is missing the process has never reached the control plane. Stay on step 2: check that the container or the binary is actually running, and that the host can reach the control plane over outbound HTTPS.
• The status reads NOT RUNNING. No heartbeat for over 90 seconds. Either the process stopped or it can no longer reach the control plane. Nothing on the dashboard can start or stop it — the agent runs inside your network and only opens connections outwards, so you start and stop it on that host.
• The agent runs but the database is not listed. The dashboard tells you on Billing: "your agents are reporting 1 databases but 0 are registered". Until you register it in step 5, that database's findings will not appear and it is not covered by anything.
• The agent connects but you see no query text. That is Postgres, not Praxion: pg_stat_statements only exposes query text to superusers and to members of pg_read_all_stats. Grant it to the read-only user in your DSN: GRANT pg_read_all_stats TO your_user;.
• The container exits immediately. Run it in the foreground without -d to read the reason — a wrong AGENT_ID, a reused LICENSE_KEY, or a DSN it cannot reach. On Windows, run the binary from a terminal rather than double-clicking it.

7Next steps

• Optimizations — the costed suggestions, with the SQL and the predicted saving
• Schema map — your tables, coloured by what they cost you
• Natural language query — ask in English, get SQL
• Glossary — teach the model what "active customer" means in your business
• CI Gate — connect a repository and stop dangerous migrations in a pull request
• Audit log — every event anchored to the one before it by SHA