Getting Started

Simmetric Chat is a local-first, air-gap capable AI chat platform: it works without a connection to external cloud services, with a local LLM (Ollama), local embeddings (Xenova) and a local vector DB (LanceDB). It can however use cloud providers (OpenAI, Anthropic, OpenRouter) and a remote vector DB (Qdrant) when configured.

Prerequisites

• Node.js ≥ 24 and pnpm 12.8.1 (the monorepo manager, pinned via packageManager; corepack enable && corepack prepare [email protected] --activate)
• PostgreSQL 16 (main database)
• Ollama (optional but recommended for the local LLM) - https://ollama.com
• Docker + Docker Compose (for containerized deployment, see 09 - Deployment)

Verify:

node -v && pnpm -v && psql --version

Installation (local development)

git clone <repo> simmetric-chat
cd simmetric-chat
pnpm install

The monorepo uses pnpm workspaces + Turborepo. The packages live in packages/: shared, server, frontend, collector, widget, plus the src-tauri/ desktop app.

Environment variables

Every package reads the repo-root `.env` (the single runtime config file; the old per-package .env layer was removed: precedence is process.env > root .env > code default). Create the minimal file:

cp .env.example .env

Required secrets (JWT_SECRET, COLLECTOR_SECRET) and the widget key:

JWT_SECRET=$(openssl rand -hex 32)
COLLECTOR_SECRET=$(openssl rand -hex 32)
WIDGET_API_KEY=$(openssl rand -hex 32)
DATABASE_URL=postgresql://simmetricchat:simmetricchat@localhost:5432/simmetricchat
LLM_PROVIDER=ollama
LLM_MODEL=gemma4:latest
OLLAMA_BASE_URL=http://localhost:11434

WIDGET_API_KEY is required by the widget service (its own Zod schema exits the process without it); the server registers it at boot as the API key of the widget-service account (idempotent). Optional in development: API_KEY_HMAC_SECRET (the sk- API keys stay unusable until it is set) and ENCRYPTION_KEY (fallback scryptSync(JWT_SECRET); required in production). A missing LICENSE_KEY means the Community build.

Full environment-variable table: 03 - Configuration.

Database

Create the PostgreSQL database (e.g. docker compose -f docker/docker-compose.infra.yml up -d postgres), then generate the Prisma client, apply the migrations and the seed:

pnpm db:generate                  # generates the Prisma client (+ Prisma 7/pnpm symlink fix)
pnpm --filter server db:migrate   # applies the migrations (interactive)
pnpm --filter server db:seed      # default roles (Admin, Superuser, User), permissions, config, templates

As an alternative to the manual seed: on an empty database the frontend shows the 4-step setup wizard (admin, LLM provider, vector DB) - or the server auto-seeds the bootstrap admin (SEED_BOOTSTRAP_ADMIN=true by default, configurable via SEED_ADMIN_USERNAME / SEED_ADMIN_PASSWORD / SEED_ADMIN_EMAIL, defaults admin / admin123 / [email protected] with mustChangePassword=true). Self-service registration is closed by default (ALLOW_REGISTRATION=false): an admin creates users from Settings or via POST /api/auth/admin-register.

Starting development

A single command starts every service through Turborepo:

pnpm dev

Default ports:

Open http://localhost:5173, log in with admin / admin123, change the password.

If Ollama is not running, chats fail with a connection error. Pull a model with

ollama pull gemma4:latest && ollama serve, or configure a cloud provider in

Settings → Providers.

Quick UI tour

• Sidebar - role-filtered groups: Overview (dashboard), Chat (chat, projects, workspaces), Knowledge (documents, knowledge base, uploads), Platform (widgets, marketplace, analytics - admin), System (event log, SSO - admin/enterprise). Items follow the 15 RBAC menu sections (the two v0.28.1 additions: skills, plugins).
• Chat - token-by-token streaming, per-chat model selection (Cmd+K palette), side-by-side comparison (Cmd+Shift+M), RAG citations, /model slash command.
• Documents - drag&drop upload (PDF, DOCX, XLSX, PPTX, TXT, MD, CSV, images with OCR), status pending → processing → completed → failed.
• Settings - 5 top-level tabs (Profile, LLM Providers, Appearance, Security, Advanced) nesting the sub-sections: Providers, LLM & Embedding, Vector DB, API Keys, Roles, Users, MCP Connections, Maintenance, Backups, DLP, Widgets (dedicated page), OCR, etc.
• Maintenance - one-click RAG reindex after an embedding model change.

Recommended first steps

1. Configure a provider - Settings → Providers: add Ollama (local) or OpenAI/Anthropic.
2. Create a workspace and a project - documents and chats are workspace-scoped.
3. Upload a document - Documents → upload; wait for the completed status.
4. Chat - open a chat in the workspace and ask questions about the document (hybrid RAG).
5. (Admin) Explore the marketplace - install an MCP server to extend the agent with tools.

The new v0.28.1 guides

The guide grew by six new technical pages: 13 - Connectors, 14 - Wiki Knowledge Engine, 15 - Custom Skills, 16 - Document DLP Pipeline, 17 - Quotas & Costs, 18 - Synthesis Pipeline.

v0.28.1 Provenance

Operational reference - Simmetric Chat v0.28.1 (docs updated 2026-10-02, census SHA `aca5b8ff').

Next steps

• Understand how it works underneath: 02 - Architecture
• All env vars and feature flags: 03 - Configuration
• Embedding the chat on your site: 06 - Widget Integration