Quick start

Self-host with Docker Compose. Postgres, the Go API, and the Next.js dashboard come up together. On a self-hosted instance you sign in with the operator account from .env.

1. Start the stack

git clone https://github.com/vector5-ai/analytics
cd analytics
cp .env.example .env
docker compose up --build

# Dashboard  http://localhost:3000
# API        http://localhost:8080

2. Sign in

Open http://localhost:3000/app/login. Default operator account: admin@localhost / changeme. Add a site — the domain must match what you will put in data-domain.

3. Add the tracker

<script defer data-domain="example.com"
  src="http://localhost:8080/js/v5.js"></script>

The script is about 1 KB, sets no cookies, and writes nothing to localStorage. Full options live in Tracker.

4. Add the middleware

Crawlers never load v5.js. Install @vector5/middleware so GPTBot and friends still count.

import { vector5 } from '@vector5/middleware/next'

export const middleware = vector5({
  endpoint: 'http://localhost:8080/api/hit',
  domain: 'example.com',
})

Same package ships Express, Hono, Workers, and Node adapters. See Middleware.

5. Verify

1. 1

   Hit a page as yourself

   Open the site. The dashboard realtime strip should show a human within a few seconds.

2. 2

   Simulate a crawler

   curl -A "GPTBot" https://example.com/docs. The AI Traffic panel should increment GPTBot.

3. 3

   Fetch the manifest

   GET /api/sites/example.com/manifest should report cookies: false, ip_stored: false, and the daily-hash formula.

Hosted instead

The hosted product at vector5.ai is invite-only. Request access. For your own cloud deploy set V5_AUTH_MODE=supabase and point the app at your Supabase project — see Supabase auth.