Slimlytics README

Slimlytics

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

Website · Start free (hosted) · Pricing · Docs · Agent setup · Privacy model

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. 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.

Plan limits and current prices are on the pricing page.

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 with a dashboard view of queries, pages, countries, and devices. Slimlytics can add and DNS-verify a site's Search Console property for you.
• 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:

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

> 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 (repository copy: 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 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

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 is free to start.

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

./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:

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:

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+

make setup
make test
make check
make build

Docker with live reload

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 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:

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:

<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:

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 stored in the operating system's private configuration directory with 0600 permissions; automation can instead provide SLIMLYTICS_TOKEN without writing a file.

The idempotent command intended for AI agents creates or reuses a domain and returns the complete server configuration, same-origin snippet, and test URLs:

slimlytics --json site ensure example.com --server caddy

The complete public guide is available at https://slimlytics.com/docs/cli; docs/CLI.md is the repository copy. The interactive Scalar API reference is at https://slimlytics.com/api/docs, backed by the downloadable OpenAPI 3.1 document at https://slimlytics.com/api/openapi.json.

Operations

Production releases use the guarded deployment script:

make deploy

The script requires a clean main branch whose HEAD is already pushed to origin/main. It connects through the dedicated slimdeploy account, requires canonical-path and repository-sentinel checks before any synchronization, runs the complete local test/check/build suite with a lockfile-pinned OpenAPI validator, creates a verified PostgreSQL backup and a source rollback snapshot, synchronizes source while preserving production .env and backups, applies compose.yaml with the production compose.proxy.yaml overlay, and verifies health, readiness, the exact OpenAPI contract, redirect behavior, and the deployed Scalar stylesheet. A failed deployment automatically restores the prior source snapshot, reapplies Compose, and waits for healthy services.

Manual backup and guarded restore remain available:

./scripts/backup.sh
./scripts/restore.sh backups/slimlytics-YYYYMMDDTHHMMSSZ.sql.gz

Backups are gzip-verified. Restore requires typing RESTORE and runs PostgreSQL with ON_ERROR_STOP.

Before upgrading:

1. Run and verify a backup.
2. Pull the desired tagged release.
3. Run docker compose build.
4. Run docker compose up -d.
5. Verify /health, /ready, the dashboard, and test ingestion.

Rollback by checking out the previous tag and restoring the pre-upgrade backup if the migration is not backward compatible.

Admin portal

/admin lists accounts, their sites, devices, and passkeys, and can sign accounts out, disable, re-enable, or delete them. Every action is recorded in an audit log. Grant access from the deployment directory:

scripts/admin-grant.sh you@example.com            # make an admin
scripts/admin-grant.sh you@example.com --revoke   # remove admin access

An admin must add a passkey under Account security (/account). The portal then requires a session that verified that passkey within the last 12 hours. If someone loses every passkey, confirm their identity and run scripts/passkey-reset.sh EMAIL; they can then sign in with their password and add a new one.

Security

• Never commit .env.
• Use unique 32+ byte values for JWT_SECRET and VISITOR_HASH_SECRET.
• Use the tested production Compose overlay or another trusted TLS reverse proxy; never expose login or analytics traffic over plaintext HTTP.
• Keep PostgreSQL private; Compose does not publish its port.
• Restrict each site to expected origins.
• Rotate site write keys and application secrets after suspected exposure.

See SECURITY.md for reporting and deployment guidance.

Documentation

• docs/IMPLEMENTATION_PLAN.md
• docs/ARCHITECTURE.md
• docs/REQUIREMENTS.md
• docs/API.md
• docs/openapi.json
• docs/PRIVACY.md
• docs/PERFORMANCE.md
• docs/FIRST_PARTY_PROXY.md
• docs/SERVER_INGESTION.md
• docs/CLI.md
• docs/MCP.md
• docs/AGENT_INTEGRATION.md
• docs/MIGRATION.md
• docs/OPERATIONS.md
• docs/BILLING.md

Project status

The current release includes collection diagnostics, marketing insights, sequential funnels, Search Console sync, and scoped REST/MCP access for agents. Retention cohorts, heatmaps, uptime monitoring, scheduled notification delivery, white-labeling, and a plugin marketplace remain later features.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md for the development loop and privacy review checklist, and SECURITY.md for reporting vulnerabilities privately.

This codebase is a ground-up rewrite of the earlier Slimlytics projects.

License

Slimlytics is open source under the GNU Affero General Public License v3.0. You can run, study, modify, and self-host it freely. If you offer a modified version to others as a network service, the AGPL requires you to make your modified source available to its users.

Two components meant to be embedded in other projects use the permissive MIT License instead:

• tracker/: the browser tracker script that runs on your website (tracker/LICENSE)
• cli/: the slimlytics command-line tool (cli/LICENSE)

Try it in a minute: slimlytics.com. Free hosted plan, no card required.