Developer FAQ

Answers to the most common questions about installing, configuring, and developing with Synaplan.

Installation#

New to self-hosting? Start with the Quickstart & Self-Hosting walkthrough — it covers the smooth install path and the common pitfalls (the local-AI model download, Qdrant, TTS, the office engine, and the production Galera cluster). The answers below are the detailed reference.

How do I install Synaplan?#

Clone the repository and start the Docker services:

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

make up starts the status page on :5173 first, then pulls and starts the rest (a plain docker compose up -d starts the same stack but :5173 stays silent until every image is pulled). Open http://localhost:5173 immediately — a live status screen shows the boot progress and switches to the app when it is ready (first start: 5–15 minutes on a cold cache, ~2 minutes warm; later starts: seconds).

What are the install options?#

No AI weights are downloaded by default. The older docker-compose-minimal.yml still starts a leaner stack but is no longer needed — the standard stack is the cloud-AI-only stack. (install.sh --minimal is deprecated and simply starts the standard stack.)

What are the default login credentials?#

What services are available after startup?#

What runs under the hood?#

Besides the URLs above, the stack starts several more services. Internal-only with no host ports: Redis (cache, sessions, locks, job queues, realtime engine), Centrifugo (WebSocket gateway for live support), a background worker (async AI/indexing jobs), a scheduler (saved tasks, reapers, the daily update check) and the compute sidecar (file work — never publish its :8080). Published dev ports: Qdrant (:6333), Tika (:9999) and Piper TTS (127.0.0.1:10200). Optional profiles add Ollama (local-ai), Docling (docling), SearXNG (searxng), Collabora CODE (office) and Keycloak (oidc). They need zero configuration locally — see Architecture & Realtime for what each one does. (Production deploy/compose.yaml keeps all of these internal-only — only the web service binds a host port there.)

Configuration & the .env File#

What is the .env file?#

The file backend/.env is where the infrastructure configuration lives: database connections, email settings, authentication, realtime secrets, and more. (AI provider API keys are best managed in the UI under Operate → AI infrastructure → Models & keys — env keys are supported as a bootstrap and imported into the encrypted store on first use.)

A fully documented template is provided at backend/.env.example. To get started:

cp backend/.env.example backend/.env

Then edit backend/.env with your own values. The file is git-ignored, so your credentials stay local.

What are the main sections in .env?#

Do I need to set all variables?#

No. The only things required for a working local install are the defaults already in .env.example. Everything else is opt-in — add API keys for the providers you want to use, and leave the rest empty.

Adding Your Own API Keys#

What's the easiest way to add a key?#

Use the UI: log in as an admin and open Operate → AI infrastructure → Models & keys. Paste the key and it is validated live against the provider, stored AES-256 encrypted in the database, and active immediately — no restart, no .env editing. The same page can set the provider's recommended models as the install-wide defaults in one click.

The env variables below still work and are the right tool for scripted or orchestrated deploys: a key found in the environment is imported into the encrypted store on first use. Rotating the env value rotates the stored copy; a key saved through the UI permanently wins over the env var, so you can remove it from .env afterwards.

Which providers can I plug in?#

Every key is optional and independent: add only the ones you want (via Operate → AI infrastructure → Models & keys or the env variable), and the matching models appear in the selector. How that filter works, and how to run with only local models: AI providers & models and Air-gapped installation.

How do I add an OpenAI key?#

Paste it under Operate → AI infrastructure → Models & keys, or set it in backend/.env:

OPENAI_API_KEY=sk-your-openai-key-here

The GPT-5.6 family (Sol, Terra, Luna), GPT-5.5 / GPT-5.5 Pro, the GPT-5.4 family, GPT-4o mini, GPT Image 1.5, Whisper, and the text-embedding-3 models will become available in the model selector.

How do I add an Anthropic key?#

ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here

Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Opus 4.8, and Claude Haiku 4.5 will appear (chat + vision).

Older generations (Claude Opus 4.1 / 4.5 / 4.6 / 4.7 and Sonnet 4.5 / 4.6) were retired from the catalog in July 2026. On an existing install, a migration deactivates those rows and repoints any default that still used them to the current equivalent — Sonnet 5 for the Sonnet line, Opus 4.8 for the Opus line. Nothing is deleted, so past messages keep their model reference.

How do I add a Google Gemini key?#

GOOGLE_GEMINI_API_KEY=your-gemini-key-here

Enables Gemini 3.1 Pro, Gemini 3.5 / 3 Flash, Gemini 3.1 Flash-Lite, the Gemini 2.5 family, plus Google's media models (Imagen 4 including Fast and Ultra, Nano Banana / 2 / Pro, Veo 3.1 video, Gemini Flash TTS).

How do I add a Groq key?#

GROQ_API_KEY=gsk_your-groq-key-here

Groq provides ultra-fast inference for open models like Llama 3.3 70B, Llama 3.1 8B Instant, Qwen3 32B, and GPT-OSS 20B/120B, plus Llama 4 Scout vision and Whisper Large v3 transcription.

How do I add a Mistral key?#

MISTRAL_API_KEY=your-mistral-key-here

French/EU-hosted models: Mistral Medium 3.5 (chat + vision), Mistral Large 3, and the Voxtral audio pair (Mini Transcribe for speech-to-text, Voxtral TTS for voice output).

How do I add an xAI (Grok) key?#

XAI_API_KEY=your-xai-key-here

Enables Grok 4.5 chat and image understanding with a 500K-token context window, Grok Imagine for image and video generation, and Grok voice (TTS + transcription). Get a key at console.x.ai under Team → API Keys.

How do I add a TrustedTokens key? 🇩🇪#

TRUSTEDTOKENS_API_KEY=your-trustedtokens-key-here

TrustedTokens is TNG Technology Consulting's sovereign inference platform: open-weight models served from GPUs in Munich, under German jurisdiction, with zero data retention and no CLOUD Act exposure. Synaplan talks to it through its OpenAI-compatible API at https://api.trustedtokens.eu/v1, so it behaves like any other cloud provider — but the tokens never leave Germany.

Enabling the key adds:

Get a key at trustedtokens.eu under Account → API Access.

How do I add a HuggingFace key?#

HUGGINGFACE_API_KEY=hf_your-token-here

Routes the Kimi K2.5, K2.6 and K2.7 Code models (chat + vision) through HF Inference.

How do I add image and video generation?#

THEHIVE_API_KEY=your-thehive-key-here
HIGGSFIELD_API_KEY=your-higgsfield-key-here
HIGGSFIELD_API_SECRET=your-higgsfield-secret-here

TheHive adds Flux Schnell and SDXL image models; Higgsfield adds Soul and Reve images plus DoP and Kling 2.1 video. Higgsfield needs both halves of the credential — the key alone will not authenticate. Google's Imagen / Nano Banana / Veo models come with the Gemini key instead.

How do I use Ollama (local models)?#

Ollama is the opt-in local-ai Compose profile — no API key needed:

COMPOSE_PROFILES=local-ai make up

That pulls bge-m3 (embeddings, ~1 GB) in the background; add ENABLE_LOCAL_GPT_OSS=true to also pull gpt-oss:20b for local chat (~14 GB, GPU or a strong CPU recommended). Inside the Docker network the backend reaches it at http://ollama:11434. To point at an Ollama already running on the host instead (and skip the container):

OLLAMA_BASE_URL=http://host.docker.internal:11434

Pull further models manually and import them under Operate → AI infrastructure → Models & keys → Local AI → Import pulled models, then activate them under Manage → Assistants → Models:

docker compose exec ollama ollama pull llama3.2:3b

Can I use multiple providers at the same time?#

Yes. Set as many API keys as you like. Each user chooses a model per task (chat, vision, embeddings, image generation) under Manage → Assistants → Models; administrators curate which models are active and default on the same page.

Model Pricing & Cost Transparency#

What does each model cost?#

Every model in the catalog carries its provider price — input and output, in USD per 1M tokens (or per generated image / video / minute for media models). Nothing is hidden behind a proprietary "credit" unit: the number Synaplan bills against is the provider's own rate.

You can see it in three places:

• In the app — the model selector puts a cost badge (Free / Low / Mid / High) next to every option, computed from the real in/out prices of the models offered alongside it, so a cheaper alternative is visible at the moment you choose. The same badge sits on each answer, next to the model that produced it.
• On the Usage page (Account → Usage; administrators: the Usage tab of Operate → Overview) — every call is logged with its model, provider, channel, tokens and computed cost, so you can trace consumption per day and per model.
• Over the API — GET /api/v1/config/models returns priceIn and priceOut per model, and admins get the full catalog with editable prices under Manage → Assistants → Models.

On the hosted instance at web.synaplan.com, that same catalog is what the free and paid tiers meter against, so the price you read in the selector is the price you pay for.

Which models are the cheapest?#

Prices span three orders of magnitude, so model choice matters more than anything else you can tune:

Self-hosting with Ollama removes the per-token cost entirely — you trade it for GPU capacity. A common setup routes everyday chat to a low-cost or local model and reserves a frontier model for the tasks that actually need it.

Does self-hosting cost anything?#

Synaplan itself is Apache-2.0 licensed and free to run. Your only AI cost is what your chosen providers charge — and with Ollama on your own GPU, that can be zero. The cost tracking, budgets and markup machinery described in Hosting Platform is there for operators who resell capacity; it does nothing on a private install.

Docker & Development#

How do I view logs?#

docker compose logs -f backend     # Backend logs
docker compose logs -f frontend    # Frontend dev server
docker compose logs -f worker      # Background jobs (Messenger consumer)
docker compose logs -f centrifugo  # Realtime WebSocket gateway
docker compose logs -f             # All services

How do I restart a service?#

docker compose restart backend
docker compose restart frontend

How do I reset the database?#

docker compose down -v    # Removes all volumes (data)
make up                   # Fresh start with seed data

How do I run tests?#

make test                          # All tests (backend + frontend)
make -C backend test               # Backend only (PHPUnit)
make -C frontend test              # Frontend only (Vitest)

How do I run linting and static analysis?#

make lint                          # Backend + frontend lint
make -C backend phpstan            # PHP static analysis
docker compose exec -T frontend npm run check:types   # TypeScript check

How do I build the frontend for production?#

make -C frontend build             # Build the Vue SPA
make -C frontend build-widget      # Build the embeddable widget

Qdrant & Vector Search#

What is Qdrant used for?#

Qdrant is a vector database that powers three features:

1. RAG Document Search — Semantic search over indexed documents
2. AI Memories — User profiling and long-term context
3. Feedback System — False-positive detection and learning

Do I need LibreOffice?#

Only if you want the new office capabilities: Word/Excel/PowerPoint thumbnails, Download as PDF, inline preview, officemaker PDF output, conversion of .doc / .xls / .ppt / .rtf / iWork before analysis, and combining Office files into one PDF. Chat, Tika RAG and officemaker DOCX/XLSX/PPTX work without it.

The engine is the Collabora CODE sidecar (OFFICE_CONVERT_URL), not apt install libreoffice on the host. Enable it with docker compose --profile office up -d (local compose already defaults the URL). On deploy/, set COMPOSE_PROFILES=office in deploy/.env — not in backend/.env. An existing Nextcloud / OpenCloud CODE works if the backend and worker can reach it; Collabora never sees Synaplan users. See Office documents.

Why don't my Word files get a thumbnail?#

Office posters need the Collabora sidecar. PDF first-page posters work without it (Imagick / pdftoppm). If the engine is off (OFFICE_CONVERT_URL empty or disabled), Word / Excel / PowerPoint tiles stay as icons — that is expected. See Office documents.

Do I need Qdrant?#

No. Qdrant starts automatically with make up, but Synaplan works fully without it. If Qdrant is unavailable, memories and vector search are simply disabled. MariaDB VECTOR can serve as an alternative for basic vector operations.

Common Issues#

Project Structure#

synaplan/
├── backend/          # Symfony 8 PHP API
│   ├── src/          # Controllers, Services, Repositories
│   ├── .env.example  # Configuration template
│   └── tests/        # PHPUnit tests
├── frontend/         # Vue 3 + TypeScript SPA
│   ├── src/          # Components, stores, services
│   └── tests/        # Vitest tests
├── docs/             # Internal documentation
├── _docker/          # Docker build configs
└── plugins/          # Installed plugins (synaads, synaform, …)

Synaplan Desktop#

How do I pair a computer?#

In the web app open Manage → Developer & devices → Desktop, create a pairing code, and enter your Synaplan address plus that code in the desktop app. The key is scoped and stored in the OS secret store. Full walkthrough: Synaplan Desktop.

Why is the Desktop page missing on my instance?#

Pairing is on by default since 4.8, so an administrator has switched DESKTOP_AGENT.ENABLED off (Operate → System configuration → Features) or pinned FEATURE_DESKTOP_AGENT_ENABLED=false, or a group policy turned the desktop agent off for your group. Chat from the desktop app additionally needs the Messages gateway (MESSAGES_GATEWAY.ENABLED, off until an administrator turns it on under Manage → Developer & devices → Coding clients).

Which skills ship with the app?#

Ten zero-setup skills (slides, invoices, charts, email drafts, calendar invites, and more) plus a tiny hello-files example. They need Python 3 only. See Desktop: Skills.

What the AI assistant can do#

Can Synaplan create PDFs, compose music, or run code?#

It depends on this installation — and the honest answer is in the chat, not in a global yes/no.

• PDFs. Creating or exporting a PDF needs the optional office engine on that instance. Many installs can already produce Word (DOCX) and analyse uploaded PDFs. Ask "Can you create PDFs?" in chat; the assistant will say what is available here and what the alternative is.
• Music. The platform does not include a music or song model. The assistant can write original lyrics in a style you describe. Spoken audio needs text-to-speech on that install.
• Running code. When the installation has the Secure compute module on — the standard stack starts it with everything else — the assistant can run short Python or Node file work on copies of the files you chose, in an isolated sidecar, and hand back result files. Operators find the dedicated-box and production paths on Run the compute sidecar (gVisor on a separate host in production). Without it the assistant does not execute code on the server; named Desktop skills can run on a paired computer when that feature is enabled.

Type /help or "What can you do here?" for the live inventory of this workspace.

Why does the assistant say it cannot do X when the docs say it can?#

The documentation describes the product. The assistant answers for this workspace. A live inventory of connected providers and optional services wins when the two disagree — for example the docs mention PDF export, but this install has no office engine, so the assistant will say no and point at DOCX instead. Ask in chat; that is the source of truth for here.

More Resources#

• Architecture & Realtime — Service map, Redis, Centrifugo, clustering
• Plugins & Integrations — Synaads, Synaform 4.x, TTS, Synasort, Nextcloud, OpenCloud, ownCloud.online
• Widget Integration — Embed the chat widget on any website
• Outlook Add-in (Synamail) — Generally available Outlook add-in
• Synaplan Desktop — Pair a computer and run local Agent Skills
• Run the compute sidecar — File work for developers and operators
• Code Examples — cURL, Node.js, PHP snippets
• GitHub: synaplan — Main repository
• GitHub: Synaads — AI marketing campaign plugin
• GitHub: Synaform — AI document-merge plugin (4.x)
• GitHub: synaplan-tts — Text-to-Speech service
• GitHub: synaplan-nextcloud — Nextcloud integration
• GitHub: synaplan-opencloud — OpenCloud / oCIS integration
• GitHub: synaplan-owncloud-online — ownCloud.online integration
• GitHub: synaplan-charts — Helm charts for Kubernetes
• All repositories — Everything we maintain and support