Getting Started

Synaplan is an open-source AI platform — chat, knowledge (RAG), media and agents on infrastructure you control. The complete platform is Apache-2.0 licensed, Dockerized, and starts with one command. Self-hosted is the same software as the cloud version at web.synaplan.com.

This page gets you from zero to your first AI answer on your own machine. For a deeper look at install options and common pitfalls, continue with Quickstart & Self-Hosting.

Your first answer in three steps

Prerequisites: Docker + Docker Compose v2, Git, 8 GB RAM minimum, and ~4 GB free disk for the standard install (no AI weights are downloaded by default — but file work and spoken answers start with the stack).

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.)

1. Open http://localhost:5173 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 on a cold cache, ~2 minutes warm; every later start: seconds). Not sure if it's still booting? docker compose logs -f startup-notes explains what is happening and prints READY the moment the app answers.
2. Log in as [email protected] / admin123.
3. Connect an AI provider — the app takes you there. Until a key is in place, chat is replaced by a first-run setup screen. Open AI provider setup, paste one key (free: Groq), and you are chatting. You never touch a config file.

The first-run wizard, in short

• The first-run screen is the setup. An empty install blocks chat with a single Open AI provider setup button. The same cards live on Operate → AI infrastructure → Models & 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. Keys live encrypted in your own database, not in a plaintext file on disk.
• Active instantly. No restart and no rebuild — the next message already uses the new key.
• .env still works. Keys already in backend/.env are imported into the encrypted store on first use.

No cloud key at all? Local AI is an opt-in Compose profile. COMPOSE_PROFILES=local-ai make up adds Ollama with the bge-m3 embedding model (~1 GB) for document search; COMPOSE_PROFILES=local-ai ENABLE_LOCAL_GPT_OSS=true make up also pulls a local chat model (gpt-oss:20b, ~14 GB — GPU or a strong CPU recommended). Chat begins working when the download finishes; the status screen shows the progress.

Default logins (development stack)

These seeded accounts exist in the local development stack only. A production install creates its own first administrator — see Production Deployment.

Where to go next