vitrus

<p align="center">
  <a href="https://vitrus.dev"><img src=".github/assets/banner.png" alt="Vitrus — open-source analytics for every app you ship. One panel you can check." width="100%"></a>
</p>

<p align="center">
  <b>Open-source analytics for every app you ship. One panel you can check.</b><br>
  Cookie-free web and product analytics for websites, iOS and Android apps — traffic, users, retention and<br>
  revenue side by side, without storing who your users are. Every number carries the SQL that produced it,<br>
  and your AI agent can ask about all of them over MCP. One process, on your own server.
</p>

<p align="center">
  <a href="https://vitrus.dev/demo"><b>Live demo</b></a> ·
  <a href="#ask-your-ai-about-your-analytics"><b>Use with ChatGPT / Claude</b></a> ·
  <a href="https://vitrus.dev"><b>Website</b></a> ·
  <a href="https://app.vitrus.dev"><b>Cloud</b></a> ·
  <a href="https://vitrus.dev/docs"><b>Documentation</b></a> ·
  <a href="#quickstart"><b>Quickstart</b></a> ·
  <a href="https://vitrus.dev/compare">Compare</a> ·
  <a href="https://vitrus.dev/changelog">Changelog</a> ·
  <a href="https://github.com/Vitrus-Dev/vitrus/discussions">Discussions</a>
</p>

<p align="center">
  <a href="LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-5bc8af"></a>
  <img alt="Runtime dependencies: 0" src="https://img.shields.io/badge/runtime%20deps-0-5bc8af">
  <img alt="Tracker: 3.0 KB gzipped" src="https://img.shields.io/badge/tracker-3.0%20KB%20gzip-5bc8af">
  <img alt="Services to install: 0" src="https://img.shields.io/badge/services%20to%20install-0-5bc8af">
  <a href="https://github.com/Vitrus-Dev/vitrus/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Vitrus-Dev/vitrus/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://github.com/Vitrus-Dev/vitrus/releases"><img alt="Release" src="https://img.shields.io/github/v/release/Vitrus-Dev/vitrus?color=5bc8af"></a>
</p>

<p align="center">
  <img src=".github/assets/hero-split.png" alt="The Vitrus dashboard in light and dark, on a demo workspace with sample data: KPIs with evidence badges, a trend against the previous period, and the deterministic digest" width="100%">
</p>

## Quickstart

You need [Bun](https://bun.sh) 1.3 or newer. That is the whole list.

```bash
git clone https://github.com/Vitrus-Dev/vitrus && cd vitrus
bun install && bun run build:tracker
alias vitrus="bun $PWD/packages/cli/src/cli.ts"

vitrus init                                   # creates ./vitrus.db and a secret salt
vitrus site add "My site" example.com         # prints your script tag
VITRUS_PASSWORD="a long secret" vitrus start  # ingest + dashboard on http://localhost:3000
```

Then one line in your site's `<head>`:

```html
<script defer data-site="SITE_ID" src="https://YOUR-HOST/v.js"></script>
```

Mobile apps: [Vitrus for Swift](https://github.com/Vitrus-Dev/vitrus-swift) (iOS, iPadOS, macOS — Swift Package Manager)
and [Vitrus for Flutter & Dart](https://github.com/Vitrus-Dev/vitrus-dart). Same panel, user ids hashed on the device,
no device identifier.

No Docker Compose file, no database server, no migration step. Rather not run it? **[app.vitrus.dev](https://app.vitrus.dev)**
is the same engine, hosted, with a free plan — and **[the live demo](https://vitrus.dev/demo)** opens the full hosted
dashboard on sample data, no account needed.

## Every number opens the query that made it

Click a figure and you get the SQL that ran, its parameters, the window and the result — not a
description of the number, the number's origin. It is the same evidence the AI summary is checked against.

<p align="center">
  <img src=".github/assets/shot-main-evidence.webp" alt="The unique-visitors figure opened in the evidence panel: the SQL query, its parameters, the result and the time window (demo workspace, sample data)" width="100%">
</p>

That matters more now that models write the reports. When an AI-written sentence contains a number
that is not in the evidence, Vitrus **drops the sentence** before it reaches you:

```
Visitors are down 18% against the previous period. [e1]
The drop coincides with the last deploy. [e1, e7]
✗ dropped: "The new theme caused a 41.7% fall in conversion."
   → 41.7 is in no evidence record, and "caused" is a claim nobody can make from this data.
```

## Every app you ship, one panel

Shipping several apps — web and mobile — usually means one admin page per app just to see who signed up.
Add one line where your app knows the user is signed in, and Vitrus counts **who is new, who came back, who you lost
and who started paying**, per app and for all of them side by side:

```js
vitrus.identify(user.id)           // required: hashed in the browser, never sent raw
vitrus("signup")                   // optional
vitrus("plan", { plan: "pro" })    // optional: your own plan labels
```

<p align="center">
  <img src=".github/assets/shot-portfolio.webp" alt="The Portfolio page: one card per app with its active users, a trend line, Web/iOS/Android badges, active, new and lost users, paying users and revenue (demo workspace, sample data)" width="100%">
</p>

- **Every user, under a made-up name.** Open an app and each signed-in user is a row — returning, one-time or signed
  up only, actions, active days, visits, joined, last active; opened, actions by day and recent visits — shown as
  "Amber Falcon · 3f9a2c", because no email or name is stored to show.
- **Lifecycle per app.** New, active, came back, lost, net, quick ratio, one-and-done, current plans, became and
  stopped paying — each with its query.
- **Ask your AI.** "Which of my apps lost the most users this week?" — `get_portfolio` and `get_lifecycle` over MCP
  answer with counts and the queries behind them.
- **Hashed before it leaves the browser.** The script sends `sha256(site + "|" + id)`; the server hashes that again with
  a secret before storing it. Your users' ids — often emails — never reach the server. No WebCrypto, no id sent.
- **Separate per app, by design.** The same person in two of your apps is two unrelated hashes; nobody can join them.
  Portfolio totals say so instead of pretending to deduplicate.
- **Personal fields dropped twice.** Email, phone, name, address, password, token and similar properties — and any value
  shaped like an email or phone number — are removed in the browser and again on the server, and the removal is counted.
- **No auth provider to connect.** Works the same with Supabase, Clerk, Firebase, Better Auth or your own login.

<p align="center">
  <img src=".github/assets/shot-users.webp" alt="The Users page: returning, one-time and signed-up-only users, and a row per user under a made-up name with actions, active days and visits; one row opened to actions by day and recent visits (demo workspace, sample data)" width="100%">
</p>

Self-hosted: `GET /api/people?site=…`, `GET /api/lifecycle?site=…` and `GET /api/portfolio` on your server; over MCP, `get_lifecycle` and
`get_portfolio`. [How it is counted →](https://vitrus.dev/docs/lifecycle)

## A whole analytics product

<table>
  <tr>
    <td width="50%"><img src=".github/assets/tile-globe.webp" alt="The 3D globe with sessions at their cities"><br><b>Globe.</b> Sessions at their city, on a canvas drawn from our own geometry — no map provider, no GeoIP database.</td>
    <td width="50%"><img src=".github/assets/tile-realtime.webp" alt="Real-time visitors and the live event feed"><br><b>Real-time.</b> Who is on the site now, and the latest events, streamed as they arrive.</td>
  </tr>
  <tr>
    <td><img src=".github/assets/tile-ai.webp" alt="AI assistant referrals separated from AI crawler reads"><br><b>AI traffic.</b> Visitors ChatGPT and Claude sent you, kept apart from the crawlers that read your pages.</td>
    <td><img src=".github/assets/tile-funnel.webp" alt="An ordered funnel with drop-off"><br><b>Funnels.</b> Ordered — a step counts only after the one before it, so the conversion is not inflated.</td>
  </tr>
  <tr>
    <td><img src=".github/assets/tile-journeys.webp" alt="A Sankey of page journeys"><br><b>Journeys.</b> The paths people take, as a Sankey you can filter by start and end.</td>
    <td><img src=".github/assets/tile-revenue.webp" alt="Revenue by channel"><br><b>Revenue.</b> Per currency, never converted, attributed to where the visit began.</td>
  </tr>
  <tr>
    <td><img src=".github/assets/tile-performance.webp" alt="Core Web Vitals at p75"><br><b>Web Vitals.</b> LCP, INP, CLS, FCP and TTFB at the percentile you choose, per page.</td>
    <td><img src=".github/assets/tile-retention.webp" alt="A retention cohort matrix"><br><b>Retention.</b> Cohorts of identified users — and an honest blank for days that have not happened yet.</td>
  </tr>
  <tr>
    <td><img src=".github/assets/tile-heatmap.webp" alt="A click heatmap over a recorded page"><br><b>Heatmaps.</b> Clicks and scroll depth per device class, drawn over the page from your own recordings — nothing extra collected.</td>
    <td><img src=".github/assets/tile-users.webp" alt="The Users page"><br><b>Users.</b> Every signed-in user under a made-up name — returning, one-time, signed up only — with actions by day.</td>
  </tr>
</table>

<sub>Screenshots: the hosted dashboard on a demo workspace; every figure is sample data — <a href="https://vitrus.dev/demo">open it yourself</a>. The self-hosted
dashboard in this repository is simpler today — see <a href="#architecture">Architecture</a> for exactly which views it renders.</sub>

## Ask your AI about your analytics

Vitrus speaks MCP. Your assistant reads your analytics — read-only — and every number it gets back comes
with the query that produced it, so it can cite instead of assert. Listed in the official
[MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=dev.vitrus) as `dev.vitrus/analytics`.

| Where | How |
|---|---|
| **ChatGPT** · **Claude** (web & desktop) | Add a custom connector with `https://app.vitrus.