Synaplan — official documentation for the open-source AI knowledge platform.
Machine-readable catalog (schema synaplan-docs-manifest/1): https://docs.synaplan.com/docs-manifest.json

## Getting started

- [Introduction & Auth](https://docs.synaplan.com/): Official Synaplan documentation: self-host an open-source AI knowledge platform with RAG, an embeddable chat widget, a REST & OpenAI-compatible API, a transparently priced multi-provider model catalog (OpenAI, Anthropic, Gemini, Groq, Mistral, TrustedTokens, Ollama), plugins (Synaads, Synaform 4.x), Nextcloud / OpenCloud / ownCloud.online integrations, and the Synamail Outlook add-in.
- [Getting Started](https://docs.synaplan.com/getting-started): Install Synaplan locally in three steps with docker compose, log in as admin@synaplan.com, and connect an AI provider key through the first-run wizard (free Groq key supported). From zero to your first AI answer in minutes.

## Install & self-host

- [Quickstart & Self-Hosting](https://docs.synaplan.com/quickstart): Self-host Synaplan with Docker in minutes — and avoid the common pitfalls: the local-AI (Ollama) model download, whether you need Qdrant, optional Text-to-Speech, and the production MariaDB Galera cluster. Minimal vs standard install, prerequisites, and health checks.
- [Office documents](https://docs.synaplan.com/office-documents): Optional Collabora Online sidecar for Synaplan office features: thumbnails, PDF export, inline preview, officemaker PDF, legacy format conversion, and combine-as-PDF. Deployments set OFFICE_CONVERT_URL; convert-to never sees Synaplan users. Host apt LibreOffice is not enough.
- [Production Deployment](https://docs.synaplan.com/production): Self-host Synaplan in production with the deploy/ contract: published images, generated secrets, consistent backups and restores via lifecycle scripts, pinned version updates, and platform adapters for Elestio, AWS Marketplace and Umbrel.
- [Kubernetes (Helm Charts)](https://docs.synaplan.com/kubernetes): Official Helm charts for Synaplan on Kubernetes: install from GHCR as OCI artifacts or from source, optional NVIDIA Triton inference chart, Ollama or Triton AI backends, and a complete helmfile example deployment.
- [Hosting Platform](https://docs.synaplan.com/hosting): How hosting providers run Synaplan commercially: multi-node Galera + Redis reference architecture, GPU inference with Ollama or Kubernetes, rolling Docker-image updates that never touch customer data, and built-in tiers, quotas, budgets and Stripe billing to sell AI to customers.

## Using Synaplan

- [Using Synaplan](https://docs.synaplan.com/using-synaplan): A task-oriented tour of the core Synaplan features: chat with per-answer cost tracking and per-task model choice, document upload and semantic RAG search, AI memories, saved tasks with scheduling, connections and approvals.
- [Assistants](https://docs.synaplan.com/assistants): An assistant is a saved recipe: instructions, models, knowledge, tools and triggers, owned by one person, published in immutable versions to a group or the whole instance. Gallery, seven-section builder, mail and schedule triggers, export and import, AGENTS.ENABLED.
- [Tools & approvals](https://docs.synaplan.com/tools-and-approvals): One tool registry, write-class approvals in chat and under Manage → Automations → Approvals, pause and resume on Saved Tasks, and optional custom HTTP / OpenAPI tools on Connections. Flags TOOLS.REGISTRY_ENABLED, TOOLS.APPROVALS_ENABLED, TOOLS.CUSTOM_HTTP_ENABLED.

## Chat widget

- [Widget Integration](https://docs.synaplan.com/widget): Add the Synaplan AI chat widget to any website with one ES-module script. Configuration options, JavaScript API, file uploads, theming, and cross-origin (CORS) setup.

## Channels & integrations

- [Channels: WhatsApp & Email](https://docs.synaplan.com/channels): Connect Synaplan to the WhatsApp Business API (multi-number, media, Whisper transcription) and the email channel (topic-specific addresses, threading, live IMAP mailbox search). Setup pointers and links to the full guides.
- [Outlook Add-in (Synamail)](https://docs.synaplan.com/synamail): Synamail is the generally available Outlook add-in for Synaplan: summarise, translate, draft replies, Contact AI Profiling, Writing assistant, and save emails to your knowledge base. Works on Web, Windows, Mac and Linux.
- [Plugins & Integrations](https://docs.synaplan.com/plugins): Extend Synaplan with open-source plugins: Synaads, Synaform 4.x (AI form fill), TTS, plus Nextcloud, OpenCloud / oCIS, and ownCloud.online cloud integrations.
- [Linked platforms](https://docs.synaplan.com/platform-links): Link a Nextcloud, ownCloud or OpenCloud server to Synaplan: register the instance, approve it, and let users connect their existing Synaplan account with a one-time link code. Scoped, revocable API keys, PLATFORM_LINKS.ENABLED flag, audit trail, and the partner handshake API.
- [Mobile Apps](https://docs.synaplan.com/mobile-apps): The Synaplan apps for iPhone and Android bring chat, documents, assistants and voice input to your phone — pointed at web.synaplan.com or at your own self-hosted server. App Store and Google Play.
- [MCP Server & Client](https://docs.synaplan.com/mcp): Synaplan speaks MCP in both directions: connect AI clients to the Streamable HTTP /mcp endpoint (API-key/OIDC auth, rag_search, memory_search), and connect your own MCP servers as read-only data sources for the multi-task planner (mcp_fetch, Channels → MCP Servers, MCP.CLIENT_ENABLED).
- [MCP OAuth connectors](https://docs.synaplan.com/mcp-oauth): Connect Notion MCP, Higgsfield MCP, and any standard remote MCP server that signs in with OAuth. Admin flag MCP.OAUTH_CONNECTORS_ENABLED, Connect / Reconnect flow, example configurations.
- [Claude Code (Anthropic API)](https://docs.synaplan.com/claude-code): Use Synaplan as the backend for Claude Code: the Anthropic-compatible gateway at POST /v1/messages with BYO or operator Anthropic keys, budget metering, per-session AI summary chats, model aliases to OpenAI/Gemini, and native MCP for RAG and memories.
- [Text-to-Speech (TTS)](https://docs.synaplan.com/tts): Add voice output to Synaplan with the optional synaplan-tts companion: Docker image with five baked Piper voices (en, de, es, fr, tr), UI language selects the voice, extras via EXTRA_VOICES_DIR, or a cloud voice with ELEVENLABS_API_KEY.

## Synaplan Desktop

- [Synaplan Desktop](https://docs.synaplan.com/desktop): Synaplan Desktop is a companion app for Windows, macOS and Linux that pairs a computer with your Synaplan workspace: chat with your Synaplan account and run installable Agent Skills locally under a folder allowlist. The scoped pairing key is stored in the OS secret store.
- [Desktop: Skills](https://docs.synaplan.com/desktop-skills): Enable and run Agent Skills on your own computer with Synaplan Desktop: ten bundled zero-setup skills (slides, invoices, charts, email drafts, calendar invites), enable/disable per skill, and a no-shell execution model.
- [Desktop: This computer](https://docs.synaplan.com/desktop-folders): Control which folders Synaplan Desktop skills may read, where generated files are saved (the out-box in your home directory), and the always-on deny rules for sensitive files. Path confinement refuses junction, symlink and .. escapes.
- [Desktop: Check this computer](https://docs.synaplan.com/desktop-tools): How Synaplan Desktop detects the local tools skills rely on — Python, Node.js and LibreOffice — per platform (Windows py launcher and PATHEXT, macOS Homebrew and Command Line Tools, Linux PEP 668), and why it never constructs a shell.

## Administration

- [Administration](https://docs.synaplan.com/administration): Operate a Synaplan instance: connect AI provider keys (validated live, encrypted at rest), manage users and the model catalog with transparent pricing, white-label branding, and the production security checklist.
- [AI infrastructure](https://docs.synaplan.com/ai-infrastructure): Operate → AI infrastructure: swap the services behind Synaplan without code changes. Document extraction chains with the optional Docling sidecar, web search via Brave, self-hosted SearXNG, Tavily, Exa, Firecrawl or Perplexity, an eval-gated rerank stage (TEI, Jina, Cohere, Voyage), and importing models from any OpenAI-compatible endpoint or Ollama.
- [People & groups](https://docs.synaplan.com/people-and-groups): Create groups on the People page, add members and managers, and turn IAM.GROUPS_ENABLED on. Sharing a folder or chat (IAM.SHARING_ENABLED) stays off until an operator turns it on. Continue a shared chat as your copy; ownership never moves; admins do not read private content.
- [First-Run Setup & Admins](https://docs.synaplan.com/first-run-setup): How a fresh Synaplan instance gets its first administrator: the setup wizard at /setup, switching it off with SETUP_WIZARD_ENABLED=false, the BOOTSTRAP_ADMIN_* variables, and SSO-only instances where an OIDC role claim (OIDC_ADMIN_ROLES, OIDC_ROLE_CLAIMS) grants admin without a single local account.

## Feature modules

- [Feature modules](https://docs.synaplan.com/modules): The twelve optional feature modules of a Synaplan installation — sidecars, AI providers, commerce and channels — what each adds, the Not installed / Needs setup / Available states on Operate → Feature Status, the app:modules:list command, the feature_not_configured answer and the MODULES.GATE_<ID> flags.
- [Module: Apache Tika](https://docs.synaplan.com/modules/tika): The tika feature module: text extraction from PDFs and Office files, TIKA_BASE_URL and the TIKA_* settings, what the extraction chain does without it, how to point at an external Tika, and how to read its Feature Status.
- [Module: Docling](https://docs.synaplan.com/modules/docling): Enable the optional Docling sidecar for table- and heading-preserving document extraction: the docling Compose profile, DOCLING_BASE_URL, timeout and size limits, adding it to the Documents chain in front of Tika, and the fallback behaviour when it is down.
- [Module: Office conversion](https://docs.synaplan.com/modules/office-convert): The office_convert feature module: thumbnails, PDF export, inline preview and combine-as-PDF for Office files through a Collabora CODE engine. The office Compose profile, OFFICE_CONVERT_URL for an existing Collabora, what still works without it.
- [Module: SearXNG web search](https://docs.synaplan.com/modules/searxng): Run web search for chat on your own SearXNG instance: the searxng Compose profile, SEARXNG_BASE_URL, the JSON output format an external instance needs, selecting it on the Web search tab, and the fallback to a cloud provider.
- [Module: Piper text-to-speech](https://docs.synaplan.com/modules/piper-tts): The piper_tts feature module: spoken answers from the local synaplan-tts service with five baked-in voices. The tts Compose profile, a standalone container, SYNAPLAN_TTS_URL, the health probe, and the cloud voices that work without it.
- [Module: Local AI (Ollama)](https://docs.synaplan.com/modules/local-ai): The local_ai feature module: chat and embedding models through Ollama with zero per-token cost. The local-ai Compose profile in dev and production, OLLAMA_BASE_URL for an existing Ollama, importing pulled models, sizing, and the model-download pitfall.
- [Module: Higgsfield](https://docs.synaplan.com/modules/higgsfield): The higgsfield feature module: Soul and Reve text-to-image, DoP and Kling 2.1 image-to-video. Platform credentials (HIGGSFIELD_API_KEY + HIGGSFIELD_API_SECRET) versus each user's own Higgsfield connection, and how the two interact.
- [Module: Google AI](https://docs.synaplan.com/modules/google-ai): The google_ai feature module: Gemini chat and vision, Imagen and Veo generation, transcription. Entering the key in the admin UI or as GOOGLE_GEMINI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY, the Vertex AI transport, and which key source is in effect.
- [Module: TheHive](https://docs.synaplan.com/modules/thehive): The thehive feature module: Flux Schnell and SDXL text-to-image models through TheHive. One variable, THEHIVE_API_KEY, switches it on; activating the catalog rows and reading the Feature Status.
- [Module: Stripe billing](https://docs.synaplan.com/modules/stripe-billing): The stripe_billing feature module: subscription checkout, top-ups, billing portal and the Stripe webhook. What open-source mode means while it is off, the keys and price ids that make it configured, the webhook events, and the routes the module gate protects.
- [Module: Mobile in-app purchases](https://docs.synaplan.com/modules/mobile-iap): The mobile_iap feature module for operators who ship their own build of the Synaplan apps: IAP_PRODUCT_* tier mapping, store prices, Apple StoreKit 2 and Google Play receipt verification, the store notification endpoints, and one-owner-per-subscription rules.
- [Module: WhatsApp channel](https://docs.synaplan.com/modules/whatsapp): The whatsapp feature module: WHATSAPP_ENABLED, access token and webhook verify token, registering the callback URL at Meta, choosing the assistant that answers on WhatsApp, multi-number support, and what the Channels page shows when the module is absent.
- [Module: Secure compute (file work)](https://docs.synaplan.com/modules/compute): The compute feature module: the assistant runs short Python or Node file work on copies of your files in an isolated sidecar. COMPUTE_URL and COMPUTE_TOKEN, the COMPUTE.ENABLED flag, the compute Compose profile, per-user workspaces, the pinned website allow-list, quotas, approvals, and what the AI can and cannot do.

## Developers

- [Architecture & Realtime](https://docs.synaplan.com/architecture): How Synaplan fits together: the Docker service map, multi-task message routing with AI planning, SSE vs WebSocket streaming, the Centrifugo realtime gateway, and how one shared Redis makes a multi-node cluster work — cache, sessions, locks, queues and realtime fan-out.
- [Multi-Task (DAG) Routing](https://docs.synaplan.com/dag-routing): How Synaplan turns a complex request into a DAG of tasks: an AI planner decomposes the message into capability steps (chat, RAG, web search, media, document, calendar .ics), runs them in dependency order, and streams live task cards over SSE. One prompt, multiple generated files — extensible and self-hosted.
- [REST Architecture](https://docs.synaplan.com/rest): How Synaplan's RESTful API is structured: resource paths under /api/v1, JSON formats, error handling, legacy api.php actions, and per-user plugin endpoints.
- [Interactive API (Swagger)](https://docs.synaplan.com/openapi): Explore the Synaplan OpenAPI (Swagger) reference: OpenAI-compatible chat completions, image generation, audio transcription, models, widgets and document endpoints.
- [Code Examples](https://docs.synaplan.com/examples): Copy-paste Synaplan API examples: OpenAI SDK chat, document upload for RAG, SSE streaming, image generation, audio transcription, and WhatsApp messaging in cURL, Node.js and PHP.
- [Contributing](https://docs.synaplan.com/contributing): How to contribute to the open-source Synaplan ecosystem: the repository map, development guidelines and quality gates, plugin development, Discord community and GitHub issues.
- [Developer FAQ](https://docs.synaplan.com/faq): Answers to common Synaplan questions: Docker install options, .env configuration, adding AI provider keys (OpenAI, Anthropic, Gemini, Groq, Mistral, TrustedTokens, Ollama), transparent per-model pricing, Qdrant, and troubleshooting.