Simmetric Chat
Volver a la documentación
Guía 01

Guía de inicio

Simmetric Chat es una plataforma de chat IA local-first y capaz de funcionar sin conexión (air-gap): funciona sin conexión a servicios cloud externos, con LLM local (Ollama), embeddings locales (Xenova) y base vectorial local (LanceDB). Sin embargo, pued…

4 min de lectura

Simmetric Chat es una plataforma de chat IA local-first y capaz de funcionar sin conexión (air-gap): funciona sin conexión a servicios cloud externos, con LLM local (Ollama), embeddings locales (Xenova) y base vectorial local (LanceDB). Sin embargo, puede usar proveedores cloud (OpenAI, Anthropic, OpenRouter) y una base vectorial remota (Qdrant) cuando estén configurados.

Requisitos previos

  • Node.js ≥ 24 y pnpm 11.24.0 (el gestor del monorepo; `corepack enable && corepack prepare [email protected] --activate`)
  • PostgreSQL 16 (base de datos principal)
  • Ollama (opcional pero recomendado para el LLM local) - https://ollama.com
  • Docker + Docker Compose (para el despliegue contenerizado, ver 09 - Deployment)

Verificar:

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

Instalación (desarrollo local)

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

El monorepo usa pnpm workspaces + Turborepo. Los paquetes viven en packages/: shared, server, frontend, collector, widget, más la app de escritorio src-tauri/.

Variables de entorno

Todos los paquetes leen el `.env` en la raíz del repo (el único archivo de configuración runtime; el antiguo nivel de .env por paquete se eliminó: precedencia process.env > .env raíz > valores por defecto del código). Crea el archivo mínimo:

bash
cp .env.example .env

Secrets obligatorios (JWT_SECRET, COLLECTOR_SECRET) y clave del widget:

env
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 es requerida por el servicio widget (su propio esquema Zod saca el proceso sin ella); el servidor la registra como clave API de la cuenta widget-service al arrancar (idempotente). Opcionales en desarrollo: API_KEY_HMAC_SECRET (las claves API sk- quedan inutilizables hasta que se defina) y ENCRYPTION_KEY (fallback scryptSync(JWT_SECRET); obligatoria en producción). Un LICENSE_KEY ausente significa build Community.

Tabla completa de variables de entorno: 03 - Configuration.

Base de datos

Crea la base de datos PostgreSQL (p. ej. docker compose -f docker/docker-compose.infra.yml up -d postgres), luego genera el cliente Prisma, aplica las migraciones y el seed:

bash
pnpm db:generate                  # genera el cliente Prisma (+ fix de symlink Prisma 7/pnpm)
pnpm --filter server db:migrate   # aplica las migraciones (interactivo)
pnpm --filter server db:seed      # roles por defecto (Admin, Superuser, User), permisos, config, templates

Alternativa al seed manual: en una base vacía, el frontend muestra el asistente de configuración en 4 pasos (admin, proveedor LLM, base vectorial) - o el servidor auto-siembra el admin de bootstrap (SEED_BOOTSTRAP_ADMIN=true por defecto, configurable via SEED_ADMIN_USERNAME / SEED_ADMIN_PASSWORD / SEED_ADMIN_EMAIL, valores por defecto admin / admin123 / [email protected] con mustChangePassword=true). El auto-registro está cerrado por defecto (ALLOW_REGISTRATION=false): un admin crea los usuarios desde Settings o via POST /api/auth/admin-register.

Iniciar el desarrollo

Un único comando arranca todos los servicios mediante Turborepo:

bash
pnpm dev

Puertos por defecto:

ServicePuertoDescripción
frontend5173SPA Vite (React 19), proxy /api → server
server3000API Express + Swagger en /api-docs
collector3210Microservicio de ingestión de documentos
widget3211Servicio de widget embebible (Preact)

Abre http://localhost:5173, inicia sesión con admin / admin123, cambia la contraseña.

Si Ollama no está en ejecución, los chats fallan con un error de conexión. Descarga un
modelo con ollama pull gemma4:latest && ollama serve, o configura un proveedor cloud en
Settings → Providers.

Recorrido rápido de la UI

  • Sidebar - grupos filtrados por rol: Overview (dashboard), Chat (chat, projects, workspaces), Knowledge (documents, base de conocimiento, uploads), Platform (widgets, marketplace, analytics - admin), System (event log, SSO - admin/enterprise). Las entradas siguen las 13 secciones de menú RBAC.
  • Chat - streaming token por token, selección de modelo por chat (paleta Cmd+K), comparación lado a lado (Cmd+Shift+M), citas RAG, comando slash /model.
  • Documents - carga drag & drop (PDF, DOCX, XLSX, PPTX, TXT, MD, CSV, imágenes con OCR), estado pending → processing → completed → failed.
  • Settings - 5 pestañas principales (Perfil, Proveedores LLM, Apariencia, Seguridad, Avanzado) que anidan las subsecciones: Providers, LLM & Embedding, Vector DB, API Keys, Roles, Users, MCP Connections, Maintenance, Backups, DLP, Widget (página dedicada), OCR, etc.
  • Maintenance - reindexación RAG con un clic tras un cambio de modelo de embedding.

Primeros pasos recomendados

  1. Configura un proveedor - Settings → Providers: añade Ollama (local) u OpenAI/Anthropic.
  2. Crea un workspace y un proyecto - los documentos y los chats están limitados al workspace.
  3. Carga un documento - Documents → upload; espera al estado completed.
  4. Chatea - abre un chat en el workspace y haz preguntas sobre el documento (RAG híbrido).
  5. (Admin) Explora el marketplace - instala un servidor MCP para extender el agente con herramientas.

Siguientes pasos