synaplan

Why Synaplan?

• We open-source artificial intelligence. The complete platform — backend, frontend, widgets, plugins — is Apache-2.0, Dockerized, and starts with one command. No core/enterprise split, no functional downgrade: self-hosted is the same software as our cloud.
• Hundreds of models, one platform. OpenAI, Anthropic, Google Gemini, Groq, Mistral, xAI, HuggingFace, sovereign EU providers, and any local model via Ollama — swap providers per task in the UI, without touching a config file. No vendor lock-in, ever.
• DAG task routing that saves tokens. An AI planner decomposes complex requests into a directed task graph (extract → summarize → generate → reply) and routes every step to the model that fits it — a cheap fast model for extraction, a strong one only where reasoning is needed. Live task cards stream while the graph executes, and every answer shows what it cost.
• Sovereign by design. Run on-prem, in the EU cloud, or fully air-gapped: chat, RAG knowledge search, document processing, transcription and speech run with zero internet connection. No training on your data, no forced telemetry — proven in production up to 5,000-workplace offline deployments.
• Everywhere you work. Web app, iPhone app, Outlook add-in, embeddable chat widget, WhatsApp, email — plus the tools you already run: Microsoft 365, Dropbox, Nextcloud / ownCloud, calendars, Jira and Confluence, and OpenCloud.
• Extensible without forking. A non-invasive plugin system, an OpenAPI-documented REST API, an MCP server *and* client, and an Anthropic-compatible endpoint for Claude Code and friends.

Your first answer in three steps

One line — the installer checks Docker, fetches Synaplan, and starts the stack:

curl -fsSL https://raw.githubusercontent.com/metadist/synaplan/main/install.sh | bash

Or do exactly the same by hand:

git clone https://github.com/metadist/synaplan.git
cd synaplan
docker compose up -d

1. Open immediately. A live status screen appears within seconds and shows every boot step — database, backend, AI model download, interface — then switches to the app automatically the moment it is ready (first start: 5–15 minutes; every later start: seconds). It also lists which optional building blocks (Qdrant, Centrifugo, Collabora, …) this install is running and how to switch each on or off. The same notes print in `docker compose logs -f startup-notes`.

2. Log in as `admin@synaplan.com` / `admin123` — the status screen shows these too.

3. Connect an AI provider — the app takes you there. Until a key is in place, chat answers in demo mode and points you to the setup. Open AI provider setup, paste one key (free: Groq), and you are chatting. You never touch a config file.

That is the whole local-hosting onboarding. After chat works, open Channels → Connections to hook up Outlook, Nextcloud, Dropbox, a calendar, or Jira / Confluence — then you can say *"summarize the latest mail from X"* or *"create a picture and put it in nextcloud"*.

Key management, the short version

• The first-run screen is the setup. You do not have to hunt through Admin: an empty install blocks chat with a single Go to AI provider setup button. The same wizard lives at Admin → AI Providers (`/admin/setup`) later.
• Tested before it's saved. The key is validated against the live provider API, so a typo fails immediately instead of at your first chat.
• Encrypted at rest. It lives encrypted in your own database, not in a plaintext file on disk.
• Active instantly. No restart and no rebuild — the next message already uses it.
• Defaults repair themselves. If the default chat model points at a provider you have no key for, Synaplan repoints it to one that works, so chat is never dead on a fresh install.
• Local-model progress is visible. A download card in the setup wizard (and in `docker compose logs -f backend`) shows how far the optional Ollama pull has got; cloud chat works while it runs.
• `.env` still works. Keys already in `backend/.env` are imported into the encrypted store on first use, and a key you later save in the UI wins permanently.

No cloud key at all? Start with `ENABLE_LOCAL_GPT_OSS=true docker compose up -d` to pull a local chat model (`gpt-oss:20b`, ~14 GB, GPU or a strong CPU recommended). Chat begins working when the download finishes.

Host it on your own server

The commands above start the development stack (source build, Vite, MailHog, phpMyAdmin). For a production install on a Linux box, the same installer drives the published image and the `deploy/` contract — it writes `deploy/.env` for you (the step most installs stumble over), pins the latest release, creates the first administrator, and runs the full lifecycle (prepare → pull → validate → start → smoke-test). Secrets are generated on first start and recorded in `deploy/data/secrets.env`:

curl -fsSL https://raw.githubusercontent.com/metadist/synaplan/main/install.sh | \
  bash -s -- --mode server --domain https://ai.example.com

Prefer manual control? The identical steps by hand:

cp deploy/selfhost.env.example deploy/.env
# Set SYNAPLAN_VERSION, public URL, and BOOTSTRAP_ADMIN_* (or leave both admin vars empty and sign up later)
deploy/scripts/prepare.sh
docker compose --env-file deploy/.env -f deploy/compose.yaml pull
deploy/scripts/validate-release.sh
docker compose --env-file deploy/.env -f deploy/compose.yaml up -d

After login, the same first-run provider screen applies. Full walkthrough: Installation · deploy/README.md.

Take the tour

Click any screenshot to see it full size.

ChatEvery answer shows what it cost

Provider setupOne key, tested and encrypted

Model choiceA different model per task

RAG searchSemantic search over your files

Media generationImages, video and audio in chat

Chat widgetOne snippet, any website

AI instructionsYour own system prompts

FilesUploads become knowledge

PluginsExtend without forking

AdminUsers, usage and health

BrandingWhite-label the whole app

Regenerate these assets after a UI change with scripts/build-readme-tour.sh.

One AI, everywhere you work

The same assistant, the same knowledge base, the same model policy — on every channel your team already uses. Connect a system once under Channels; the planner can then read from it and deliver results into it.

Conversation surfaces

Connected systems

Set these up under Channels → Connections (or Channels → MCP servers / Channels → Email). In chat, use the channel word shown as a pill on the Connections page — for example *nextcloud*, *dropbox*, *outlook*.

Details and channel words: docs/CONNECTIONS.md.

The Synaplan ecosystem

Everything below is the same platform, packaged for different homes. Pick what fits — nothing else is required.

Prerequisites

• Docker + Docker Compose v2 (Docker Desktop on macOS/Windows, or Docker Engine + the Compose plugin on Linux)
• Git
• 8 GB RAM minimum (16 GB recommended for the local-AI standard install)
• ~9 GB free disk for the standard install (~5 GB for minimal, +~14 GB if you enable the local chat model)
• Free TCP ports `5173`, `8000`, `8082`, `8025`, `3307`, `6333`, `11435`

> Apple Silicon (M1–M4) Macs — build the backend image, don't pull it. The three-step start above already does this: `docker compose up -d` builds the backend and worker locally from a multi-arch base image, so PHP/FrankenPHP runs natively on `arm64` with no emulation tax. That is by far the fastest setup, and it is the default — you don't have to do anything special. The pre-built `ghcr.io/metadist/synaplan` image published for production deployments is `linux/amd64` only, so pulling it instead means running the whole backend under emulation. The first local build takes a few minutes; every later start is a cache hit. Two optional dev tools (phpMyAdmin, MailHog) are still amd64-only upstream images — if you keep them, enable Docker Desktop → Settings → General → "Use Rosetta for x86/amd64 emulation on Apple Silicon" (macOS 13+) so those two emulate quickly.

Install Options

The standard install downloads the local embedding model (`bge-m3`, ~1 GB) in the background for RAG and semantic search; progress is shown in the app.

Prefer the shell to the UI for provider keys? Keys in `backend/.env` still work — the backend reads that file when the container starts and imports the key into the encrypted store on first use. Write the key before starting, or restart the containers afterwards:

echo "GROQ_API_KEY=your_key" >> backend/.env
docker compose -f docker-compose-minimal.yml up -d
# already running? pick up the new key with:
# docker compose restart backend worker

Access

Default Login Credentials:

Features

• AI Chat — Ollama, OpenAI, Anthropic, Gemini, Groq, Mistral, xAI, TrustedTokens (DE), HuggingFace (provider list)
• Self-aware assistant — Ask "What can you do here?" or type `/help`; the AI assistant answers from this installation's live capabilities, not a generic brochure
• Multi-Task DAG Routing — An AI planner decomposes complex requests into a directed task graph (extract → summarize → generate → reply), routes each step to the model that fits it, and streams live task cards while the steps execute — cheaper models for simple steps means fewer wasted tokens
• RAG Search — Semantic document search with MariaDB VECTOR or Qdrant
• Chat Widget — Embed on any website (widget guide)
• iPhone App — Chat, documents and voice input on iOS, pointed at web.synaplan.com or at your own server (App Store)
• Live Support — Realtime WebSocket layer (Centrifugo + Redis): human takeover of widget chats, typing indicators, operator notifications (realtime guide)
• WhatsApp — Meta Business API integration
• Email — AI-powered email responses, plus live mailbox search (IMAP and Microsoft 365)
• Connections — Microsoft 365, Dropbox, Nextcloud / ownCloud / WebDAV, CalDAV — read mail, file results, write calendar events (connections guide)
• Saved Tasks — Pin a multi-step plan and run it on demand or on a schedule (Channels → Saved Tasks)
• Audio — Whisper transcription (input) + optional synaplan-tts (output; four baked voices, UI language selects the voice)
• Documents — PDF, Word, Excel, images with OCR; optional Collabora CODE sidecar for office thumbnails, PDF export, preview and combine (office documents)
• AI Memories — User profiling with Qdrant vector search
• Feedback System — Feedback capture and analysis powered by Qdrant
• Plugins — Non-invasive plugin system (plugin guide)
• MCP Server *(early access)* — Connect AI clients (Claude, Cursor, …) over the Model Context Protocol; your RAG and memories become tools at `POST /mcp` (MCP guide)
• MCP Client *(early access)* — Connect *your* MCP servers (Jira, Confluence, CRM, wiki, n8n, …) under Channels → MCP Servers. The planner pulls live data via `mcp_fetch` and, when you enable allow write actions on that server, can create tickets or pages via `mcp_action` — destructive tools stay refused. SSRF-guarded, per-topic opt-in. Seeded `BCONFIG` flags (`MCP.CLIENT_ENABLED`, `MULTITASK.MCP_FETCH_ENABLED`, `MULTITASK.MCP_ACTION_ENABLED`) turn this on; an explicit `0` row is the operator kill switch. See docs/MULTITASK_DATA_NODES.md
• Claude Code & Anthropic-compatible API — Point Claude Code or any Anthropic-protocol client at your instance (`POST /v1/messages`); configure under Channels → AI Agents (guide)

AI Providers & Models

Synaplan is provider-neutral: connect the providers you want in Admin → AI Providers (keys are validated live and stored encrypted in the database, active without a restart), or set the env variables below in `backend/.env` — those are read at container start and imported into the encrypted store on first use. Each user picks a different model per task (chat, vision, image, video, audio, embeddings) — nothing is hardcoded.

Transparent pricing. Every model carries its provider's own rate (USD per 1M tokens in/out, or per image / second / character for media) — no proprietary credit unit in between. The selector shows a Free / Low / Mid / High cost badge next to each model and on every answer, `GET /api/v1/config/models` returns `priceIn` / `priceOut`, and the Statistics page logs the real cost of each call. On the hosted instance at web.synaplan.com that same catalog is what your plan meters against; self-hosted with Ollama, the per-token cost is simply zero. Details: Model pricing & cost transparency.

> Model catalog changes (new models, retired generations, price updates) ship as seeders plus a migration, so an existing install is repointed to a supported successor instead of silently keeping a dead model. See docs/PRICING_MAINTENANCE.md.

Lean by design: core vs optional building blocks

`docker compose up -d` starts a complete platform, but the core is deliberately small: the app, its database and Redis. Everything else is a building block that adds one capability and costs RAM. Switch a block on when you need it and off when you don't — Synaplan keeps running either way and simply hides the matching feature. The boot status screen at lists the live on/off state of every block, and Admin → System Status (`/admin/features`) does the same after login.

Keep a default-on block off across restarts. `docker compose stop` is undone by the next `up -d`. To make a block opt-in permanently, give it a profile in a `docker-compose.override.yml` (not tracked by git) — plain `up -d` then skips it, `--profile optional` brings it back:

services:
  qdrant:
    profiles: [optional]

Production follows the same rule set: `deploy/compose.yaml` ships the core plus Qdrant, Centrifugo and Tika, with `office` and `local-ai` as profiles (`COMPOSE_PROFILES=office,local-ai` in `deploy/.env`); Kubernetes installs wire the same services via synaplan-charts. The other dev-only containers (`phpmyadmin`, `mailhog`, `frontend-widgets`, `startup-notes`) never ship to production.

Realtime & Background Processing

Both compose files also start three internal services (no host ports, no setup needed):

In a multi-node cluster all nodes share one Redis, so WebSocket events published on one node reach browsers connected to any other. Details: docs/REALTIME.md.

Text-to-Speech (Optional)

Voice output is an optional companion, not part of the core stack — synaplan-tts, image `ghcr.io/metadist/synaplan-tts`. The image already contains four Piper voices (English, German, Spanish, Turkish). Synaplan runs fully without it; the speaker control appears when the service answers.

# Same compose file (recommended)
docker compose --profile tts up -d

# Or standalone, on this host or another machine
docker run -d --name synaplan-tts -p 127.0.0.1:10200:10200 ghcr.io/metadist/synaplan-tts:latest

The backend looks at `SYNAPLAN_TTS_URL` (compose default `http://host.docker.internal:10200`).

The UI language selects the voice. Chat sends the active frontend locale (`en` / `de` / `es` / `tr`); if the backend detects a different reply language, that wins. Piper then maps the short code to the matching baked voice (German UI → Thorsten, Spanish → davefx, …). There is no separate voice picker. Add more Piper models by dropping `.onnx` + `.onnx.json` into the extra-voices volume — see synaplan-tts README and docs.synaplan.com/tts.

Office documents (Optional Collabora CODE)

Office thumbnails, “Download as PDF”, inline preview, officemaker PDF output,

legacy / Apple format conversion, and “Combine as PDF” need a Collabora CODE

sidecar (`collabora/code`). Chat, Tika RAG and officemaker DOCX / XLSX / PPTX

work without it. The sidecar is off by default (`--profile office`) so

`docker compose up -d` does not pull the image or spend the extra ~2 GB RAM.

# Dev / minimal — compose already defaults OFFICE_CONVERT_URL to http://collabora:9980
docker compose --profile office up -d

# Production (deploy/) — env, not backend/.env
# in deploy/.env:  COMPOSE_PROFILES=office
docker compose --env-file deploy/.env -f deploy/compose.yaml --profile office up -d

# Already running CODE (Nextcloud, OpenCloud, another compose)
OFFICE_CONVERT_URL=http://:9980 docker compose up -d

Do not put `OFFICE_CONVERT_URL` in `backend/.env`: Compose injects the

variable, so the file cannot override it. Deployments set the env on the host

or in compose. `OFFICE_CONVERT_URL=disabled` turns the engine off.

Collabora never sees Synaplan users. Convert-to is a server-to-server POST

of a file; identity stays in Synaplan (login + file ownership). No Collabora

accounts, no WOPI token on this path. HTTP 403 is usually CODE’s

`net.post_allow.host` rejecting the compose subnet.

Full operator guide: docs.synaplan.com/office-documents.

Kubernetes / reuse in other projects:

synaplan-charts `docs/collabora-office-engine.md`.

Common Commands

# Startup progress ("please wait..." notes + READY message)
docker compose logs -f startup-notes

# Logs
docker compose logs -f backend

# Restart
docker compose restart backend

# Reset database
docker compose down -v && docker compose up -d

# Run tests
make test

# Code quality
make lint

Documentation

User-facing & API docs live at **docs.synaplan.com**. Source: `metadist/synaplan-docs`.

In-repo guides (for developers working on this codebase):

Related Repositories

Project Structure

synaplan/
├── backend/        # Symfony PHP API
├── frontend/       # Vue.js SPA
├── docs/           # Documentation
├── deploy/         # Production self-host compose + lifecycle scripts
├── _docker/        # Docker configs
└── plugins/        # Plugin system

Community & Support

• **Discord** — chat with the team and community; the fastest place for self-hosting and configuration questions
• **GitHub Issues** — bugs and feature requests
• **www.synaplan.com** — product, hosting and enterprise contact

Contributing

See AGENTS.md for development guidelines and code standards.

License

Apache-2.0