synaplan

---

Quickstart

On this machine

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

Open http://localhost:5173. A status screen is up within seconds and lists every boot step, then switches to the app when it is ready. First start: 5–15 minutes. Later starts: seconds.

make up answers on :5173 before the rest of the images finish pulling. docker compose up -d starts the same stack; :5173 stays quiet until those pulls finish.

1. Log in as admin@synaplan.com / admin123. The status screen shows this too.
2. Paste one provider key. Free: Groq. The app opens AI provider setup until a key is in place. You do not edit a config file for that.
3. Same notes in the terminal: docker compose logs -f startup-notes.

No cloud key? COMPOSE_PROFILES=local-ai ENABLE_LOCAL_GPT_OSS=true make up pulls a local chat model (gpt-oss:20b, ~14 GB). Chat starts when the download finishes.

Published image, no git checkout

Two files, then start. A Docker GUI uses the same pair: paste compose.yaml and select .env.

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
docker compose up -d

Open http://127.0.0.1:8000 (SYNAPLAN_HTTP_BIND plus SYNAPLAN_HTTP_PORT).

SYNAPLAN_VERSION in that .env is a release tag (5.1.1 in the example). Newer tags are on the releases page. Never set latest. Leave the eight secret lines commented out — the first start writes them to data/secrets.env. Back that file up with the database. Leave both admin lines empty and create the first administrator in the browser, or set BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD together.

If you change the bind, the port, or the public address, set APP_URL, FRONTEND_URL and REALTIME_ALLOWED_ORIGINS to that same address. Live chat stays disconnected when they do not match.

To move to another release, back up ./data first, change SYNAPLAN_VERSION, and run docker compose up -d again. Rolling the tag back after a migration needs the backup: Update a self-hosted deployment.

Closed network

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

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://<address>/. The machine creates the certificate. The browser warns once.

Any IPv4 address on that network works, including 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10 and 169.254.0.0/16, plus a block you assigned and do not announce.

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 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. A public name keeps your own HTTPS proxy and leaves this off.

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

On a server

The commands above are the development stack (source build, Vite, MailHog, phpMyAdmin) or the published image. For a Linux server, the installer writes deploy/.env, pins the latest release, and runs prepare → pull → validate → start → smoke-test. Secrets land 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

The same steps by hand are in Installation and deploy/README.md. Flags: bash install.sh --help.

One-liner for the development stack, if you would rather not clone by hand:

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

---

Why Synaplan

• Freedom, not a plan tier. The whole platform — backend, frontend, widgets, plugins — is Apache-2.0 and starts with one command. Self-hosted is the same software as the cloud.
• Hundreds of models, one place. OpenAI, Anthropic, Google Gemini, Groq, Mistral, xAI, HuggingFace, sovereign EU providers, and any local model via Ollama. Swap a provider per task in the UI.
• The planner spends the expensive model only where it matters. A request becomes a small task graph (extract → summarize → generate → reply). Live cards show the steps. Every answer shows what it cost.
• Yours, including offline. On-prem, EU cloud, or fully air-gapped. No training on your data. No forced telemetry.
• Where you already work. Web, iPhone, Android, Desktop, Outlook, a chat widget, WhatsApp, email — plus Microsoft 365, Dropbox, Nextcloud / ownCloud, calendars, Jira, Confluence and OpenCloud.
• Extend it without a fork. Plugins, an OpenAPI REST API, an MCP server and client, and an Anthropic-compatible endpoint for Claude Code and friends. Optional sidecars stay off until you turn them on.

---

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 same stack but :5173 stays silent until every image is pulled — make up exists so the status page answers within seconds.

No AI weights are downloaded by default, so the first boot is dominated by the Docker images and npm ci. COMPOSE_PROFILES=local-ai is the same switch a self-hosted install uses in deploy/.env, and it pulls 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
make up
# already running? pick up the new key with:
# docker compose restart backend worker

---

Access

Service	URL
App	http://localhost:5173
API	http://localhost:8000
API Docs	http://localhost:8000/api/doc
phpMyAdmin	http://localhost:8082
MailHog	http://localhost:8025 (SMTP on :1025)
Qdrant	http://localhost:6333
Tika	http://localhost:9999
Ollama	http://localhost:11435 (local-ai profile only)
TTS	http://127.0.0.1:10200 (localhost-only, no UI — GET /health; host port is SYNAPLAN_TTS_PORT)

Default Login Credentials:

Email	Password	Level
admin@synaplan.com	admin123	ADMIN
demo@synaplan.com	demo123	PRO
test@example.com	test123	NEW (unverified)

---

Features

• AI Chat — Ollama, OpenAI, Anthropic, Gemini, Groq, Mistral, xAI, TrustedTokens (DE), A2Agent (CN), 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)
• Mobile Apps — Chat, documents and voice on iPhone and Android, pointed at web.synaplan.com or at your own server (App Store · Google Play)
• Synaplan Desktop — Pair a computer and run skills on it. Open Manage → Channels → Synaplan Desktop. No installer yet (synaplan-desktop)
• AI assistants — Saved recipes (instructions, knowledge folders, tools, triggers) that you publish in versions (assistants)
• Tools & approvals — One tool registry; write-class actions pause under Approvals (tools)
• People & groups — Share folders, chats, assistants and tasks; Operate → People (people)
• File work — Short Python or Node runs on copies of files you picked, in an isolated sidecar (guide)
• 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, with a Steps editor and webhook trigger (Manage → Automations → Saved Tasks)
• Watched pages — Save a URL, compare it on a schedule, and mail the diff when it changes
• Audio — Whisper transcription (input) + optional synaplan-tts (output; five baked voices, UI language selects the voice)
• Documents — PDF, Word, Excel, images with OCR; the assistant can also build and revise Office files; optional Collabora CODE sidecar for 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 Manage → Connections → 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 Manage → Developer & devices → Coding clients (guide)

---

AI Providers & Models

Synaplan is provider-neutral: connect the providers you want in Operate → AI infrastructure → Providers & keys (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.

Provider	Variable in backend/.env	Models
OpenAI	OPENAI_API_KEY	GPT-5.6 Sol / Terra / Luna, GPT-5.5 (+ Pro), GPT-5.4 (+ mini / nano), GPT Image, Whisper, text-embedding-3
Anthropic	ANTHROPIC_API_KEY	Claude Opus 5, Sonnet 5, Fable 5, Opus 4.8, Haiku 4.5 (chat + vision)
Google Gemini	GOOGLE_GEMINI_API_KEY	Gemini 3.x / 2.5 chat + vision, Nano Banana (incl. Pro / Lite), Veo 3.1, Gemini TTS
Groq	GROQ_API_KEY	Qwen 3.6 27B (chat + vision), GPT-OSS 20B/120B, Whisper Large v3
Mistral 🇫🇷	MISTRAL_API_KEY	Mistral Medium 3.5 (+ vision), Mistral Large 3, Voxtral transcription + TTS
xAI	XAI_API_KEY	Grok 4.7 / 4.6 / 4.5 (+ vision, 500K context), Grok Imagine image + video (incl. Pro / 1.5 tiers)
Meta	META_API_KEY	Muse Spark 1.3 (+ vision) — Meta Model API
TrustedTokens 🇩🇪	TRUSTEDTOKENS_API_KEY	GLM 5.2 / 5.3 (+ Flash vision), Chimera, Qwen3.6 35B (+ vision), GPT OSS 120B — sovereign inference on German GPUs (TNG), zero data retention
A2Agent 🇨🇳	A2AGENT_API_KEY	Qwen3.8 MAX / Flash (+ vision), DeepSeek V4 Pro / Flash, MiniMax M3 — Chinese frontier models via the A2Agent gateway
HuggingFace	HUGGINGFACE_API_KEY	Kimi K3 / K2.5 / K2.6 / K2.7 Code (chat + vision)
TheHive	THEHIVE_API_KEY	Flux Schnell, SDXL
Higgsfield	HIGGSFIELD_API_KEY + HIGGSFIELD_API_SECRET	Soul, Reve, DoP, Kling 2.1
Cloudflare Workers AI	CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN	bge-m3 embeddings (also usable as embedding fallback)
Ollama 🇩🇪 self-hosted	OLLAMA_BASE_URL (no key)	Any local model — chat, vision, bge-m3 embeddings

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, so an existing install is repointed to a supported successor instead of silently keeping a dead model — a retirement records the successor and every install is switched off on the next deploy. See docs/PRICING_MAINTENANCE.md.

---

Lean by design: core vs optional building blocks

make up 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 http://localhost:5173 lists the live on/off state of every block, and Operate → System status (/admin/features) does the same after login.

Block	Gives you	Default	Switch
Core — frontend, backend, worker, scheduler, db (MariaDB), redis	The app, its API, async jobs, scheduled jobs, storage, cache and queues	always on	—
Ollama (ollama)	Local AI on your hardware: bge-m3 embeddings for document search, optional local chat (ENABLE_LOCAL_GPT_OSS=true)	off	COMPOSE_PROFILES=local-ai make up — the same switch as deploy/.env in production
Qdrant (qdrant)	Vector database for AI memories, feedback analysis and large-scale RAG	on	docker compose stop qdrant — document search itself runs on MariaDB VECTOR (the default VECTOR_STORAGE_PROVIDER), so RAG keeps working; memories pause
Centrifugo (centrifugo)	Live support: human takeover of widget chats, typing indicators, operator notifications (realtime guide)	on	REALTIME_ENABLED=false make up (then docker compose stop centrifugo) — the dashboard falls back to plain REST refreshes
Apache Tika (tika)	Text extraction from PDF, Word, Excel and 1000+ formats for RAG	on	docker compose stop tika — uploads then index plain text / OCR only
Collabora CODE (collabora)	Office files: thumbnails, “Download as PDF”, inline preview, “Combine as PDF” (~2 GB RAM) — details	off	docker compose --profile office up -d
Docling (docling)	Layout-aware extraction (tables, headings) in front of Tika — module	off	docker compose --profile docling up -d
SearXNG (searxng)	Self-hosted web search so queries stay on your network — module	off	docker compose --profile searxng up -d
File work (compute)	Short Python / Node jobs on copies of files you pick — details	on	COMPUTE_URL=disabled make up
Text-to-speech (tts)	Spoken answers, five built-in voices — details	on	docker compose stop tts
Keycloak (keycloak)	SSO test realm for OIDC development (configuration)	off	docker compose --profile oidc up -d

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 always starts web/worker/scheduler plus db/redis/centrifugo/tika/qdrant and spoken answers, with office, local-ai and compute as profiles (COMPOSE_PROFILES=office,local-ai,compute 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 four internal services (no host ports, no setup needed):

Service	Role
redis	Mandatory shared infrastructure: cache, sessions, locks, rate limits, message queues (Redis Streams), Centrifugo engine
centrifugo	WebSocket gateway for realtime features (live chat takeover, typing indicators, operator notifications) — browsers connect same-origin via /connection/websocket
worker	Symfony Messenger consumer that executes async jobs (AI processing, document indexing, widget crawling)
scheduler	Ticks every 60 s: saved tasks, media-job reaping, ephemeral-file cleanup, update check

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

Voice output starts with make up — synaplan-tts, image ghcr.io/metadist/synaplan-tts. The image already contains five Piper voices (English, German, Spanish, French, Turkish). Stop the tts container to hide the speaker control.

# Already running after `make up`. Standalone on 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://tts:10200).

The UI language selects the voice. Chat sends the active frontend locale (en / de / es / fr / tr); if the backend detects a different reply language, that wins. Piper then maps the short code to the matching baked voice (German UI → kerstin, 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 make up 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://<existing-collabora-host>:9980 make up

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.

---

File work

The assistant can run a short Python or Node program on copies of files you already picked and hand the result back as files — a chart from a CSV, a merged spreadsheet, a renamed folder of PDFs. The program runs in an isolated sidecar. PHP never talks to Docker.

git clone and make up start it. Compose builds the sidecar and the Python/Node runtimes from this repo, wires a local token, and turns the feature on. No profile, no image pin, no extra .env.

The local token is fixed. Do not change it:

synaplan-dev-compute-token-change-me-32b

Compose uses that value for the app and the sidecar whenever COMPUTE_TOKEN is unset, and the nightly load uses the same value. A developer install must not depend on a newly generated secret. A production or shared host sets its own COMPUTE_TOKEN (openssl rand -hex 32 in deploy/.env). prepare.sh writes one when that value is empty. Never reuse the demo token there, and never publish port 8080.

To hide it: COMPUTE_URL=disabled make up (or FEATURE_COMPUTE_ENABLED=false). Production self-host adds compute to COMPOSE_PROFILES in deploy/.env. Cloud uses a separate gVisor box, not this T1 sidecar on the web nodes.

Full guide: docs/COMPUTE.md · docs.synaplan.com — Secure compute.

---

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 && make up

# 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):

Guide	Description
Installation	Local development stack and production self-hosting (deploy/)
Configuration	Environment variables, API keys
Feature flags	Every wave feature (people & sharing, assistants, tools, saved-task steps, desktop, file work, …): admin toggle, FEATURE_* env pin, defaults
File work / compute	Optional sidecar: flags, compose profile, quotas, workspaces
Connections	Microsoft 365, Dropbox, Nextcloud / WebDAV, CalDAV, Jira / Confluence
AI Model Pricing	Model catalog, provider prices, retiring a model
Development	Commands, testing, architecture
Realtime / WebSockets	Centrifugo + Redis realtime layer, multi-node deployment
Observability	Request correlation ids, redacted event ring, admin logs API
Office documents	Optional Collabora CODE sidecar (PDF export, previews, convert-to)
RAG System	Document search and processing
Chat Widget	Embed chat on websites
WhatsApp	Meta Business API setup
Email	Email channel integration
Anthropic-compatible API	Claude Code / Messages API gateway (POST /v1/messages)
Secure compute (user docs)	What people see: File work card, Workspace, quotas

Related Repositories

Repo	Purpose
synaplan	Main app (this repo)
synaplan-docs	Public docs site (docs.synaplan.com)
Synamail	Outlook add-in
synaplan-desktop	Synaplan Desktop (Windows, macOS, Linux). No installer yet; build from source.
synaplan-apps	iOS and Android apps — App Store · Google Play
synaplan-nextcloud	Nextcloud integration
synaplan-opencloud	OpenCloud integration
synaplan-tts	Optional Piper TTS — image with 4 baked voices
synaplan-sortx	Document-sorting plugin + local tool
synaplan-charts	Helm charts for Kubernetes
synaplan-platform	Production deployment configs

---

Project Structure

synaplan/
├── backend/        # Symfony PHP API
├── frontend/       # Vue.js SPA
├── docs/           # Developer documentation
├── deploy/         # Production self-host compose + lifecycle scripts
├── sidecars/       # Optional sidecars (secure compute)
├── _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