How to use Vitrus

The complete guide — cloud edition. Self-hosting? See the open-source docs.

Vitrus is your company's glass-box brain: connect the tools you already use, ask anything in plain language, and get a clear answer, its sources, and an honest list of what your company hasn't written down yet. This page walks through the whole product.

Getting started (3 minutes)

  • Sign in at app.vitrus.dev with GitHub or Google. Your first sign-in creates a workspace named after you — rename it anytime in Account.
  • Connect a source (below). Free includes 2 connectors; the first sync usually finishes in under a minute.
  • Ask a question. You'll get an answer with [n] citations, a confidence score, and the yellow gap box — what's missing, deterministically detected.

Free plan: 1 brain · 1 seat · 2 connectors · 5,000 nodes. Every page works on Free — limits apply only when you act (connect a third source, invite a second member).

Connecting your sources

Every connector turns its source into typed, permission-aware knowledge nodes. Tokens are stored encrypted (AES-256-GCM), isolated per workspace, and source permissions are re-captured on every sync — removed from a private channel means access revoked on the next sync. What each one needs:

  • GitHub — a personal access token with read access to the repo (github.com/settings/tokens) + owner/repo. Issues, PRs and discussions become nodes; private repos get a fail-closed ACL group.
  • Slack — a bot token (xoxb-…) with channels:history, channels:read, users:read; invite the bot to the channel and paste the channel ID. One node per thread, @mentions linked to people.
  • Notion — an internal integration token (notion.so/my-integrations); share the pages you want ingested with the integration.
  • Linear — a personal API key (Settings → API), optionally a team key.
  • Google Drive — an OAuth token with drive.readonly; Docs and text files become markdown nodes.
  • Jira / Confluence — an Atlassian API token + your site (yourco.atlassian.net) + account email; optionally a project/space key.
  • GitLab — an access token with read_api + the project path; issues and MRs arrive like GitHub's.
  • Discord — a bot token with the Message Content intent, invited to your server; paste the channel ID.
  • WhatsApp Business — a Meta system-user token + phone number ID; customer (1:1) messages stream in live via webhook. For internal project groups, see the next section.
  • MCP bridge — point Vitrus at any MCP server URL (+ optional bearer): its resources become a source. Anything with an MCP server can feed your brain.
  • Email / Calendar — staged imports today: drop the documented JSON export server-side; participants/attendees become the ACL.

Step-by-step token instructions for each provider live in the in-app guide: app.vitrus.dev/docs.

WhatsApp groups → company memory

Most real decisions never make it into a doc — they happen in the WhatsApp group you made for the project. Vitrus can turn those groups into queryable company memory, and answer questions right in the chat.

  • How it works — you add the Vitrus agent (the open-source @vitrus/whatsapp bridge) to a group on a burner number you own. Every message becomes a knowledge node; ask vitrus <question> in the group and you get an answer, its sources, and the gap box — inside WhatsApp.
  • Connect it from Connectors → WhatsApp Groups: set the answer scope (which principals a group's answers may use) and optional retention. Then run the bridge, scan the QR, and add the number to your groups.
  • Consent-first & read-mostly — the agent only replies when addressed, never speaks first, and anyone can type /vitrus off to stop capture in a group.
  • Fail-closed — in-chat answers use that group's own knowledge plus org-wide PUBLIC only, unless an admin widens the scope. Set a retention window for KVKK/GDPR auto-expiry.
  • Why a bridge? — the official WhatsApp API can't join existing groups, so this uses a self-hosted linked-device bridge: your number, your data, no third-party cloud.

Asking & the gap box

One question returns four things:

  • Answer — synthesized only from your sources; every claim carries a [n] citation.
  • Sources — click a citation to open the node with the exact supporting passages (trace-to-source).
  • Gap box — the product's core: referenced-but-undocumented topics, contradictions, stale knowledge. Detected deterministically from the graph — not an LLM's opinion.
  • Confidence — 0–1, from retrieval strength and source age. Low confidence plus gaps is the honest “we don't actually know this”.

The glass-box pages

  • Gaps — everything your brain knows it doesn't know: missing docs, contradictions, stale entries, single-point (bus-factor) risks, uncited claims.
  • Systems map (Ops) — operational risk read off the graph, deterministically: bottlenecks, single-point/bus-factor people, unowned services, redundant tools, broken handoffs.
  • Conflicts — where two sources contradict each other, shown side by side with resolution status.
  • Graph — the typed knowledge graph; wikilinks become edges automatically, and connected nodes show their real titles, not raw ids.
  • Entities — people and projects fused across sources (Slack-alice and GitHub-alice become one node).
  • Verify — paste any claim → grounded / stale / contradicted / unsupported with sources and conflicts. Agents can call this too, to fact-check themselves before acting.

Proactive watch

Vitrus doesn't just answer — it tells you what needs attention before you ask. The Attention view (and vitrus watch on the CLI) surfaces stale knowledge, unresolved incidents, and gaps that are aging over time — the same deterministic analysis, made temporal. Wire it to a Slack digest to get a scheduled “here's what's drifting” message, so nothing important quietly rots.

Agent access (MCP)

Every workspace exposes https://api.vitrus.dev/t/<org>/mcp with bearer auth. The dashboard's Agent access page generates ready-to-paste setup for Claude Code, Codex, Cursor, OpenClaw and Hermes — for example:

claude mcp add --transport http vitrus \
  https://api.vitrus.dev/t/<org>/mcp \
  --header "Authorization: Bearer <token>"

openclaw mcp add vitrus --url https://api.vitrus.dev/t/<org>/mcp \
  --transport streamable-http --header "Authorization: Bearer <token>"

The token carries your identity: an agent sees exactly what you can see — org-scoped, ACL-filtered, audit-logged. Agents read before they act and write after they decide, so a whole fleet finally shares one trustworthy memory. Exposed tools: think · search · verify · gap_report · node · skill_export.

Enterprise & on-prem text-to-SQL

For regulated teams that legally can't send data to a cloud model, Vitrus Enterprise runs fully on-prem / air-gapped over your own databases:

  • Governed Text-to-SQL — ask in plain language, get an answer from your live database, with a deterministic SQL guard that refuses to invent tables or columns and shows exactly what it ran.
  • Verified-query memory — only human-approved, guard-passed queries become memory, so the system gets more trustworthy over time instead of drifting.
  • Local model — a Gemma/Ollama model runs inside your network; no schema and no data ever leave the building.
  • PII / KVKK controls — per-connection masking and row limits, enforced by the guard.

It's already running inside a metropolitan municipality serving millions of citizens. Talk to us for an on-prem deployment.

Team & permissions

  • Invite members by email from Account; each seat is one member with full dashboard + MCP access.
  • Roles: admin (members, connectors, workspace name), member, viewer (read-only).
  • Fail-closed ACL: if the source restricted it, the brain restricts it — enforced on every answer, re-captured on every sync, visible in the Team & ACL preview, recorded in the audit log.

Pricing & limits

  • Free — $0: 1 brain · 1 seat · 2 connectors · 5,000 nodes, full dashboard, support included.
  • Pro — $25/seat/month or $249/seat/year: seats as you grow, every connector, 500k nodes.
  • Enterprise — custom: on-prem / air-gapped, governed local Text-to-SQL, SSO, compliance.
  • No lock-in — your knowledge stays portable Markdown; leaving the cloud is vitrus import on your own machine with the same Apache-2.0 engine.

Self-hosting & the open core

The full engine — hybrid retrieval, gap analysis, verify, MCP server, CLI — is Apache-2.0-licensed at github.com/ahmetvural79/Vitrus, with quickstart, architecture and scaling docs. Gap analysis is never gated: the cloud sells operations (managed connectors, team, compliance), not capability.

Stuck? Open a support ticket — available on every plan, free included.