Install & operate
Self-hosting
One process, zero runtime dependencies.
What you need#
Bun 1.3 or newer. Nothing else — the database is one embedded SQLite file and there is no second service to install.
bun install -g @vitrus-dev/cli 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
The password guards the dashboard and the read API; the tracker and ingest stay public because your visitors'
browsers call them. Without it, anyone who can reach the port can read your analytics, and
vitrus start warns you.
Settings#
| Setting | Default | What it does |
|---|---|---|
--port | 3000 | Listen port: vitrus start --port 8080. |
VITRUS_PASSWORD | — | Password for the dashboard and the read API. Set it. |
VITRUS_DB | ./vitrus.db | Database file. Back up this one file. |
OLLAMA_URL | http://127.0.0.1:11434 | Local model for digest phrasing: vitrus digest SITE_ID --llm ollama:<model>. |
VITRUS_LLM_KEY / VITRUS_LLM_URL | — | Bring your own key for an OpenAI-compatible endpoint: --llm openai:<model>. |
No model is used unless you pass --llm to vitrus digest; the digest is written deterministically.
What the self-hosted server does not do yet#
The open-source core holds the whole engine, but the self-hosted server exposes less of it than the cloud. Today
vitrus start does not:
- mount the MCP module, or deliver the scheduled digest (run
vitrus digestyourself); - accept server-side forwarded requests — the path that sees signed agents and crawlers that never run JavaScript;
- take row filters, or render the sessions, users, journeys, goals and globe views;
- have accounts, teams, roles, invitations, sign-in with Google or GitHub, or billing — those are the cloud.
The building blocks are in the core, and wiring them into vitrus start is on the
roadmap. If you need them
today, compare self-hosting with the cloud.
Reverse proxy and country data#
The country breakdown is read only from your proxy's header. We do not bundle a GeoIP
database — a 60+ MB file with a monthly update cycle would break the one-command install on its
own. Supported headers: Cloudflare (CF-IPCountry), Vercel, Fly,
CloudFront, Netlify. With none of them the country table stays empty and the dashboard says why.
City, region and coordinates (the Globe's Timeline, Coordinates and Subdivisions modes) need
one more step on Cloudflare: Rules → Settings → Managed Transforms → Add visitor location
headers. That adds cf-ipcity, cf-region-code,
cf-iplatitude and cf-iplongitude. Vercel and
CloudFront send their equivalents without extra setup. Coordinates are rounded to 0.1° (about 11 km)
before they are stored — city precision, which is all IP geolocation honestly has — and the IP itself
is never stored. Without these headers the Globe works at country level and says what is missing.
Backups#
WAL mode means three files; do not copy them while the process is running:
sqlite3 /var/lib/vitrus/vitrus.db ".backup '/backup/vitrus.db'"