slimlytics

# Slimlytics

**Private, real-time web analytics. Know what works, skip the noise.**

[Website](https://slimlytics.com) · [Start free (hosted)](https://slimlytics.com/register) · [Pricing](https://slimlytics.com/pricing) · [Docs](https://slimlytics.com/docs) · [Agent setup](https://slimlytics.com/docs/mcp) · [Privacy model](https://slimlytics.com/privacy)

[![Watch the 30-second Slimlytics tour](https://slimlytics.com/video/slimlytics-promo-poster.jpg)](https://slimlytics.com/#tour)

Slimlytics shows you who is on your site right now, where they came from, and what they did, without cookies, fingerprinting, or session replay. One small first-party script, a clean dashboard, and a live visitor stream. Your AI coding agent can even install it for you.

> **Looking for the product?** Head to **[slimlytics.com](https://slimlytics.com)**. You do not need to clone this repository to use Slimlytics. The hosted version has a free plan and takes about a minute to set up.

## Hosted or self-hosted: your call

Every feature is included on every option. Pick the one that fits.

|  | **Slimlytics Cloud** (hosted) | **Self-hosted** (this repo) |
| --- | --- | --- |
| Best for | Anyone who wants analytics, not another server to babysit | Teams who want full control of their infrastructure |
| Setup | Create an account, paste one script tag | Docker Compose, PostgreSQL, Caddy |
| Servers, upgrades, TLS, GeoIP data | Handled for you | You run them |
| Cost | Free plan for one site; paid plans from $7/month | $0, unlimited sites and page views |
| Support | Community, email, or priority email by plan | Community |
| Get started | **[Create a free account](https://slimlytics.com/register)** | [Quick start](#self-hosting-quick-start) below |

Plan limits and current prices are on the [pricing page](https://slimlytics.com/pricing).

## Why Slimlytics

- **Private by default.** No tracking cookies, no cross-site profiles, no form capture. Sensitive query parameters are redacted before storage, and Do Not Track and Global Privacy Control are respected.
- **Real-time Spy.** Watch visitors arrive and move through your site as it happens.
- **Reports that matter.** Pages, referrers, countries, devices, campaigns, visitors, and custom events, ranked and exportable to CSV.
- **Goals and marketing insights.** Goals, UTM attribution, journeys, sequential funnels, revenue, anomalies, AI referrals and crawlers, and optional Google Search Console sync.
- **First-party delivery.** Serve the tracker from your own domain with generated Caddy, Nginx, or Apache routes, so ad blockers break it less often.
- **Agent-native.** A remote MCP server with browser OAuth lets Claude Code, Codex, Hermes, or any MCP client create your site, wire up tracking, and verify it.
- **Fast and small.** A Rust API, PostgreSQL, and a Svelte dashboard with light, dark, and system themes.

## Let your AI agent install it

Connect your coding agent to the hosted MCP server once, then ask it to set up analytics:

```bash
claude mcp add --transport http slimlytics https://slimlytics.com/api/mcp
```

```text
> Set up Slimlytics for https://shop.example.com behind Nginx and verify it.
```

The agent creates the site, adds the first-party proxy routes and script tag, and confirms the first page view landed. Codex and Hermes instructions are in the [agent guide](https://slimlytics.com/docs/mcp) (repository copy: [docs/MCP.md](docs/MCP.md)). Scoped personal tokens and the REST API are also supported.

---

## Self-hosting and development

Everything below is for running your own instance or contributing. If you just want analytics, [Slimlytics Cloud](https://slimlytics.com/register) is the faster path.

### Feature details

- Multiple sites with independent write keys, origins, timezones, and retention settings
- 28-day overview cards and comparison metrics
- Real-time Spy activity over Server-Sent Events
- Pages, referrers, countries, devices, campaigns, visitors, and custom events
- Standard UTM attribution and basic goals
- CSV export
- Cookieless tracking by default
- Bot filtering by crawler product name and by published Google, Meta, and Bing crawler networks
- "Ignore my visits" opt-out link per browser, with no cookies
- Sensitive query-parameter redaction and no form capture
- First-party tracker delivery to reduce accidental blocking
- Clicky-style first-party proxy setup with per-site paths, Caddy/Nginx/Apache configuration, and test links
- Responsive Svelte interface with light, dark, and system themes
- Docker Compose deployment with PostgreSQL and Caddy

## Architecture

```text
Browser tracker ──POST──▶ Rust/Axum API ──▶ PostgreSQL
                              │
Dashboard ◀── JSON + SSE ─────┘
    ▲
    └──────── Caddy ──────── Internet
```

- `backend/` — Axum, Tokio, SQLx, PostgreSQL
- `frontend/` — Svelte 5, SvelteKit, TypeScript
- `tracker/` — framework-independent TypeScript tracker
- `cli/` — installable Rust CLI for account, site, and tracking setup automation
- `migrations/` — PostgreSQL schema
- `docker/` — production container definitions and reverse proxy
- `scripts/` — verified backup and guarded restore tooling

## Self-hosting quick start

Requirements: Docker with Compose v2+. Prefer not to run servers? [Slimlytics Cloud](https://slimlytics.com/register) is free to start.

Generate a private `.env` with independent random database, JWT, and visitor-hash secrets:

```bash
./scripts/generate-env.sh
```

Review the generated URLs and deployment settings before starting. The script refuses to overwrite an existing `.env`.

Then start the stack:

```bash
make up
docker compose ps
curl --fail http://localhost:8080/health
```

Open http://localhost:8080 for the public marketing site. Create an account at `/register` (or sign in at `/login`), then use the dashboard at `/app` to add a site and copy its generated tracking snippet. Pricing and privacy pages live at `/pricing` and `/privacy`. The default listener is deliberately loopback-only and is suitable for local use or an existing TLS reverse proxy.

For a public VPS where this stack should terminate TLS itself, point DNS at the host, set `SLIMLYTICS_DOMAIN` and `ACME_EMAIL` in `.env`, then run:

```bash
docker compose -f compose.yaml -f compose.production.yaml up -d --build
```

The production overlay publishes ports 80/443, enables automatic HTTPS, persists Caddy certificates, and configures the application origin. Do not expose the base HTTP stack directly to the Internet.

## Local development

Requirements:

- Rust 1.97.1 (pinned in `rust-toolchain.toml`)
- Node.js 24+
- PostgreSQL 16+

```bash
make setup
make test
make check
make build
```

### Docker with live reload

```bash
make dev        # http://localhost:8080
make dev-logs   # follow frontend and backend output
make down
```

`make dev` layers `compose.dev.yaml` over the normal stack. Svelte changes hot-reload in the browser through Caddy. Changes to backend sources, `Cargo.toml`/`Cargo.lock`, `build.rs`, migrations, or `docs/openapi.json` rebuild and restart the API automatically. The first backend build compiles every dependency and takes a few minutes; later rebuilds are incremental. If edits are not detected (some network or VM file systems), set `VITE_WATCH_POLLING=true` in `.env`. Run `make up` to return to the production-like images.

### Visitor locations

`make geoip` downloads the free [DB-IP City Lite](https://db-ip.com/db/download/ip-to-city-lite) database (CC BY 4.0, no account) to `data/geoip/`, and Compose mounts it into the backend. Lookups happen locally, so visitor IPs are never sent to a third party. Production deploys refresh it monthly. Without the file, locations are simply disabled. Local requests arrive from private Docker addresses, which have no location; test against a deployment or with `cargo test --test enrichment -- --ignored` (set `GEOIP_TEST_DATABASE`). Trusted Cloudflare location headers take precedence when `TRUST_PROXY=true`.

### Test locally with a real account

`make sync-account` copies one account from a remote deployment into the local Docker database, so you can sign in locally with the same email and password and see the same sites and analytics. Configure `SYNC_SOURCE_SSH`, `SYNC_SOURCE_PATH`, `SYNC_SOURCE_COMPOSE_FILES`, `SYNC_EMAIL`, and optionally `SYNC_EVENT_DAYS` in `.env` (see `.env.example`). The remote is only read; locally, that account and its sites are replaced, including any local site with the same domain. Other users, API tokens, OAuth state, and Search Console connections are never copied, and report subscriptions arrive disabled. Both databases must be on the same migration.

### Without Docker

Start PostgreSQL with Docker if desired, then run the API and Svelte dev server separately:

```bash
docker compose up -d db
export DATABASE_URL='postgres://slimlytics:YOUR_PASSWORD@localhost:5432/slimlytics'
cargo run --manifest-path backend/Cargo.toml
npm --prefix frontend run dev
```

## Tracker

The dashboard generates random, editable first-party paths plus the matching Caddy, Nginx, or Apache configuration. After installing that server configuration, the measured site needs only a same-origin snippet:

```html
<script async src="/456bbb63bb86.js"></script>
```

The generated JavaScript path returns the complete tracker initialized for that site's exact beacon path. The generated test links verify both routes without inserting a fake analytics event. See `docs/FIRST_PARTY_PROXY.md`.

The tracker never captures form values. Cookieless tracking, Do Not Track, and Global Privacy Control behavior are documented in `docs/PRIVACY.md`.

## Rust CLI and AI agents

Install the `slimlytics` binary with Rust's Cargo:

```bash
cargo install --locked --git https://github.com/djedi/slimlytics --tag cli-v0.2.0 slimlytics-cli
slimlytics auth login --email you@example.com
```

Login exchanges the short-lived password session for an expiring, revocable personal API token. The credential file is store