metadist/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 and Android apps, Desktop, 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. Optional sidecars stay optional: file work, office conversion and local search never leak a half-working control when they are off.

Your first answer in three steps

Start the published image without a git checkout and without make. Two files: compose.yaml and .env.

1. Save the files.

mkdir synaplan && cd synaplan
curl -fsSL -o compose.yaml https://raw.githubusercontent.com/metadist/synaplan/main/deploy/compose.yaml
curl -fsSL -o .env https://raw.githubusercontent.com/metadist/synaplan/main/deploy/selfhost.env.example

A Docker GUI uses the same two files: paste compose.yaml and select .env.

2. Configure. In .env, SYNAPLAN_VERSION is already a release tag (today 5.0.5). Newer tags are on the releases page. Never set latest. APP_URL, FRONTEND_URL and REALTIME_ALLOWED_ORIGINS are http://127.0.0.1:8000. If you change the bind, the port, or the public address, set all three to the same address you open in the browser. Live chat stays disconnected when they do not match. Leave both admin lines empty to create the first administrator in the browser, or set BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD together.

Leave the eight secret lines commented out. The first start generates them into data/secrets.env. Back that file up with the database: a restored database cannot be opened without it. To choose the values yourself, set each line to the output of openssl rand -hex 32 before the first start. Do not use a replace-with-* example value — the start is refused and nothing is created.

3. Start, then open the app.

docker compose up -d

Open **. That address is SYNAPLAN_HTTP_BIND plus SYNAPLAN_HTTP_PORT. People on a closed network use the opt-in local network certificate and open https:///.

Then connect one AI provider. Open AI provider setup, paste one key (free: Groq), and you are chatting.

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

git clone https://github.com/metadist/synaplan.git
cd synaplan
make up

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 source-checkout onboarding. After chat works, open Manage → 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 Operate → AI infrastructure → Providers & keys (/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.

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 (immutable SemVer, never latest), public URL, and BOOTSTRAP_ADMIN_*
(or leave both admin vars empty and claim the instance through the /setup wizard)
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
deploy/scripts/smoke-test.sh

The installer also accepts --admin-email, --admin-password (auto-generated when omitted), --version (defaults to the latest release), --dir, --branch and --yes — see bash install.sh --help.

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

Local network

Opt-in. The default install stays on this machine at http://127.0.0.1:8000.

Turn it on when the network has no route to the public internet and people open Synaplan by the machine's address. Chat needs https:///. The machine creates the certificate. The browser warns once; continue past that warning.

Any IPv4 address on that network works. That includes every unrouted block:

| Address | Block | | --- | --- | | 10.0.0.15 | 10.0.0.0/8 | | 172.16.5.4 | 172.16.0.0/12 | | 192.168.1.20 | 192.168.0.0/16 | | 100.64.0.8 | 100.64.0.0/10 (shared) | | 169.254.1.20 | 169.254.0.0/16 (link-local) |

Another block you assigned and do not announce is accepted the same way. Pass the address people will type:

cp deploy/selfhost.env.example deploy/.env
Set SYNAPLAN_VERSION. Leave SYNAPLAN_HTTP_BIND at 127.0.0.1.
deploy/scripts/local-tls.sh 10.0.0.15
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

Colleagues open https://10.0.0.15/. Ports 80 and 443 must be free. The command adds the local-tls profile and sets APP_URL, FRONTEND_URL and REALTIME_ALLOWED_ORIGINS to that URL. The app itself stays on 127.0.0.1:8000.

A second interface is another argument: deploy/scripts/local-tls.sh 10.0.0.15 192.168.1.20. Back up deploy/data/tls with the rest of deploy/data. A public name keeps your own HTTPS proxy and leaves local-tls off.

Details: docs.synaplan.com/local-network · deploy/README.md.

---

Take the tour

▶ Watch the full demo on YouTube

Click any screenshot to see it full size.

Chat Every answer shows what it cost	Provider setup One key, tested and encrypted	Model choice A different model per task	RAG search Semantic search over your files
Media generation Images, video and audio in chat	Chat widget One snippet, any website	AI instructions Your own system prompts	Files Uploads become knowledge
Plugins Extend without forking	Admin Users, usage and health	Branding White-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

| Surface | What it does | Get it | |---------|--------------|--------| | Web app | Full chat + admin UI, light/dark, five languages | This repo — make up | | Mobile apps | Chat, documents and voice on iPhone and Android — pointed at web.synaplan.com or your own server | App Store · Google Play | | Synaplan Desktop | Pair a computer and run skills on it. In the web app: Manage → Channels → Synaplan Desktop. No installer yet — build from the repository. | metadist/synaplan-desktop | | Outlook add-in | Bring Synaplan into Outlook (Web, new & classic, Mac) — find and process mail without sending it anywhere | metadist/Synamail | | Chat widget | Embed your assistant on any website with one snippet — cross-origin ready, human takeover included | Widget guide | | WhatsApp & Email | The AI answers on the channel the question came in on | WhatsApp · Email | | MCP & Claude Code | Your RAG and memories as MCP tools; Anthropic-compatible POST /v1/messages endpoint | MCP guide · guide |

Connected systems

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

| Channel | What it unlocks | Setup | |---------|-----------------|-------| | Microsoft 365 | Live Outlook mail search, calendar events (outlook), send from your own mailbox | Manage → Connections — OAuth, no password stored | | Dropbox | Save generated files into a Dropbox folder (dropbox) | Manage → Connections — OAuth | | Nextcloud / ownCloud / WebDAV | File results into a folder you own (nextcloud / folder) | Manage → Connections — app password, never your account password | | CalDAV calendar | Put generated meetings into a calendar you own (calendar) | Same Nextcloud preset can create folder + calendar in one step | | IMAP mailbox | Live search of any IMAP inbox, merged with Microsoft 365 results | Manage → Channels → Email | | Jira & Confluence | Search and summarize; create tickets or pages when you allow writes. A pasted Confluence page is read through the signed-in account | Manage → Connections → MCP Servers — Jira & Confluence card, then sign in with Atlassian (no API token) | | Saved Tasks | Pin a plan and run it on demand or on a schedule (hourly / daily / weekdays) | Manage → Automations → Saved Tasks | | Nextcloud / OpenCloud apps | Use files from those clouds as AI knowledge — the file store stays in charge | synaplan-nextcloud · synaplan-opencloud |

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.

| Project | What it is | |---------|------------| | synaplan | The platform itself (this repo): backend, frontend, widget, plugins, dev stack, and the deploy/ production contract with Elestio, AWS Marketplace, and Umbrel adapters | | synaplan-charts | Helm charts for Kubernetes — for partners and enterprises running K8s clusters | | Mobile apps | Native iOS and Android — App Store · Google Play | | synaplan-desktop | Synaplan Desktop — pair a computer and run skills on it. No installer yet; build from source. | | Synamail | Outlook add-in (Web, new & classic, Mac) — Synaplan inside your mailbox | | synaplan-nextcloud / synaplan-opencloud | Apps for Nextcloud / OpenCloud — use those files as AI knowledge while the file store stays in charge (ownCloud works via the built-in WebDAV connection) | | synaplan-tts | Optional self-hosted text-to-speech service for voice output | | synaplan-base-php | The base Docker image (FrankenPHP + gRPC + whisper.cpp) the platform builds on |

---

Prerequisites

• Docker + Docker Compose v2 (Docker Desktop on macOS/Windows, or Docker Engine + the Compose plugin on Linux)
• Git (the one-line installer also works with curl + tar when git is missing)
• 8 GB RAM minimum (16 GB recommended once you add the local-ai profile)
• ~4 GB free disk for the standard install (includes file work + spoken answers; +~1 GB for local-ai, +~14 GB if you also enable the local chat model)
• Free TCP ports 5173, 8000, 8082, 8025 (+ 1025 SMTP), 3307, 6333, 9999, 11435 (local-ai profile only), 10200 (TTS, localhost-only, SYNAPLAN_TTS_PORT), 8080/8443 (oidc profile only). If one is taken, change that SYNAPLAN_*_PORT in .env (see .env.example) instead of the YAML.

Apple Silicon (M1–M4) Macs — build the backend image, don't pull it. The three-step start above already does this: make up 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 published ghcr.io/metadist/synaplan image is multi-arch too, so pulling it also runs natively.) 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

| Mode | Command | Size | Best For | |------|---------|------|----------| | One-liner | curl -fsSL https://raw.githubusercontent.com/metadist/synaplan/main/install.sh \| bash | ~4 GB | Easiest start — checks prerequisites, fetches, and starts the standard stack (--mode server available for production) | | Standard | make up | ~4 GB | Local try-out: chat, file work, spoken answers — status page first, then the rest; add one provider key and it works | | + local AI | COMPOSE_PROFILES=local-ai make up | ~5 GB | Adds Ollama and the bge-m3 embedding model on your own hardware (local chat model optional, +~14 GB) | | Production | install.sh --mode server or deploy/ compose + scripts | published image | Self-host on a Linux server — see Installation | | Kubernetes | synaplan-charts | published image | Helm-based cluster deployments for partners and enterprises |

A plain docker compose up -d starts the