Quickstart

This guide gets the full stack (web app, API, worker and PostgreSQL storage) running with Docker Compose, then connects a database and starts an agent for it.

Early preview

QueryPilot is at an early version (0.1.0). APIs, configuration and the telemetry protocol may still change between releases.The source code is not public yet. It will be published soon under the Apache-2.0 license. Until then, commands that clone the repository will work once it is available.

Requirements

• Docker with the Compose plugin (docker compose)
• openssl (or any other way to generate 32 random bytes)
• A PostgreSQL 12+ database to observe. The bundled PostgreSQL works for evaluation.

Run with Docker Compose

1. Get the code and create an environment file. The repository becomes available when the source is published; the URL below is a placeholder until then.

   git clone https://github.com/your-org/querypilot.git
   cd querypilot
   cp .env.example .env

2. Set the encryption key. QueryPilot encrypts stored database credentials with this key (AES-256-GCM). It is required; the API refuses to start without it.

   openssl rand -base64 32

   Paste the output into .env:

   .env

   QUERYPILOT_ENCRYPTION_KEY=<paste the generated key>

3. Start the stack.

   docker compose up -d --build

   This starts postgres, api, worker and web. The API applies database migrations on startup, so there is no separate migration step.

4. Open the app at http://localhost:3000. The API listens on http://localhost:8080 and serves its OpenAPI description at http://localhost:8080/api/docs.

Note

Nothing else is required: no cloud account, no LLM and no Prometheus. Optional extras are behind Compose profiles: --profile observability adds Prometheus and Grafana, --profile ai adds a local Ollama container (AI features themselves are on the roadmap).

Connect a database

1. Prepare the database: enable pg_stat_statements and create a least-privilege role. See PostgreSQL prerequisites. The bundled postgres service already preloads and creates pg_stat_statements.

2. In the web app, go to Databases → Add database and enter host, port, database name, username, password and SSL mode.

3. Click Test connection. The API connects with the credentials, without saving them, and returns a capability checklist with a remediation for anything missing.

4. Save. The password is encrypted at rest and never returned by the API.

Evaluating against the bundled PostgreSQL

The connection test runs from inside the API container, so use host postgres, port 5432, database querypilot, user querypilot, password querypilot (the Compose defaults).

Start an agent

The agent is what collects telemetry. It runs next to the database it observes and only makes outbound connections.

1. Open the database’s page and, under Agents, click Create agent.

2. Copy the token. It is shown once. The panel also shows a ready-to-run docker run command and the environment variables the agent needs.

3. Run the agent. Pick whichever matches your setup:

   Compose (evaluation)

   The Compose file has an opt-in agent service that talks to the API over the Compose network:

   QUERYPILOT_AGENT_TOKEN='<token>' \
   QUERYPILOT_TARGET_DATABASE_URL='postgres://querypilot:querypilot@postgres:5432/querypilot' \
   docker compose --profile agent up -d agent

   docker run

   The command generated by the UI looks like this (the password is always a placeholder):

   docker run -d --name querypilot-agent --restart unless-stopped \
     -e QUERYPILOT_API_URL='http://your-querypilot-host:8080' \
     -e QUERYPILOT_AGENT_TOKEN='<token>' \
     -e QUERYPILOT_TARGET_DATABASE_URL='postgres://querypilot:<password>@db.internal:5432/app' \
     querypilot/agent:latest

   The image name is what the API prints; build it yourself from infrastructure/docker/agent.Dockerfile if you are not pulling a published image.

4. Within a heartbeat (30 seconds by default) the agent shows as ONLINE. Query statistics are collected every 15 seconds; the overview and the query explorer fill in as samples arrive.

Development setup

To work on QueryPilot itself, run the apps from source.

Requirements: Node.js 20.11+, pnpm 9.15, Docker (for the development PostgreSQL).

pnpm install
cp .env.example .env          # set QUERYPILOT_ENCRYPTION_KEY
pnpm dev:setup                # start PostgreSQL, build, migrate, seed
pnpm dev                      # API, worker and web with hot reload

pnpm dev:setup runs pnpm dev:db && pnpm build && pnpm db:migrate && pnpm db:seed. The agent is not part of pnpm dev; start it separately once you have a token:

# QUERYPILOT_API_URL, QUERYPILOT_AGENT_TOKEN and QUERYPILOT_TARGET_DATABASE_URL in .env
pnpm --filter @querypilot/agent dev

Other useful scripts:

Command	What it does
pnpm dev:all	Run every app, including the agent, in watch mode
pnpm lint / pnpm typecheck	ESLint and TypeScript across the monorepo
pnpm test	Unit tests (Vitest)
pnpm test:integration	Integration tests
pnpm db:migrate / pnpm db:seed	Apply migrations / create the default organization and project
pnpm docker:up / pnpm docker:down	Start / stop the Compose stack