Administration

What an operator manages in a Synaplan instance: AI providers and their keys, users, models, and the security-relevant settings. The operator area lives in the web app under Operate (visible to accounts with the ADMIN level).

Optional services and providers — Tika, Docling, Collabora, SearXNG, local TTS, Ollama, Higgsfield, Google AI, TheHive, Stripe, in-app purchases, WhatsApp — are feature modules. Operate → Feature Status shows which ones this installation has; each has its own enable guide under Feature modules.

AI providers & keys

Synaplan is provider-neutral: connect the providers you want on Operate → AI infrastructure → Models & keys (/admin/setup) — the same cards that appear as the first-run screen on a fresh install. The other tabs of that page (document extraction, web search provider, reranking, model import) are covered on AI infrastructure.

  • Validated live. A key is tested against the provider's API before it is saved, so a typo fails immediately.
  • Encrypted at rest. Keys are stored encrypted in your own database, not in a plaintext file.
  • Active instantly. No restart or rebuild needed.
  • Self-repairing defaults. If the default chat model points at a provider without a key, Synaplan repoints it to one that works.
  • .env import. Keys set in backend/.env (e.g. GROQ_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY) are read at container start and imported into the encrypted store on first use; a key later saved in the UI wins permanently.

Supported providers include OpenAI, Anthropic, Google Gemini, Groq, Mistral, xAI, TrustedTokens, HuggingFace, TheHive, Higgsfield, Cloudflare Workers AI, and any local model via Ollama. The full provider/variable table is in the main README; key-related FAQs are on the Developer FAQ page.

Models & pricing

Every model carries its provider's own rate (USD per 1M tokens, or per image / second / character for media) — no proprietary credit unit. Users pick a model per task (chat, vision, image, video, audio, embeddings); the selector shows cost badges, GET /api/v1/config/models returns priceIn / priceOut, and the Statistics page logs the real cost of each call.

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. Details: PRICING_MAINTENANCE.md.

Users

The admin panel shows users, usage and system health. On the development stack, three accounts are seeded (see Getting Started) — change or remove them before exposing an instance.

On a production install the first administrator comes from one of three places: the first-run wizard at /setup, the bootstrap variables of the deploy/ contract, or an OIDC role claim on an SSO instance. Which one to pick, and how to switch the wizard off: First-Run Setup & Administrators.

Named teams live on Operate → People when IAM.GROUPS_ENABLED is on. Sharing a folder or chat with a group is a second flag (IAM.SHARING_ENABLED) and stays off until you turn it on. How to create a group, who may share, and the SQL for both flags: People & groups.

Versioned, publishable assistants are a third flag (AGENTS.ENABLED, seeded off). With it on, Manage → Instructions becomes Manage → Assistants. Flag and SQL: Assistants. Export & import of assistants and instructions is a fourth flag (BUNDLE.ENABLED, seeded off) — Settings for your own items, Operate for an instance-wide file. SQL is on the Assistants page.

Tools and approvals (TOOLS.*) live under Operate → System configuration → Routing → Tools and approvals. The registry is on by default; approvals and custom HTTP tools stay off until you turn them on. Flags and defaults: Tools & approvals.

Deleting a user removes what that user owned — chats, files, assistants, saved tasks and the shares on them. Copies other people made stay theirs.

Branding

The platform is white-label capable: name, logo and look can be rebranded from the admin settings without forking the code.

Security checklist

  • Terminate HTTPS in front of the app — the production contract binds to 127.0.0.1:8000 and expects a reverse proxy. Do not bind to 0.0.0.0 (Docker's iptables rules bypass host firewalls like ufw).
  • Guard deploy/data/secrets.env — it holds the generated database, realtime and application secrets, and must be part of every backup. See Production Deployment.
  • Rotate the seeded dev credentials if you ever expose a development stack.
  • Close the first-administrator window on a publicly reachable host — finish the wizard immediately after deploying, or avoid it entirely with the bootstrap variables or SSO. See First-Run Setup & Administrators.
  • Keep APP_SECRET stable — changing it makes the provider API keys stored in the database undecryptable.
  • Configuration reference for everything else (public URLs, SMTP, Qdrant, feature flags): CONFIGURATION.md.

Self-awareness settings

The AI assistant can say what this installation can actually do — which providers are connected, which optional services are running, and what is deliberately unsupported. That answer is built from a live inventory, not from a static feature list.

Flags (SELF_AWARE in BCONFIG)

Setting Default When it is off
ENABLED on The assistant no longer answers "what can you do here?" from the inventory; /help behaves like a normal chat message.
INVENTORY_IN_GENERAL on The live capability block is only used on the dedicated product topic, not on everyday chat.
DOCS_RAG_ENABLED on How-to answers no longer retrieve official documentation pages. The daily docs sync still runs.
DOCS_MANIFEST_URL https://docs.synaplan.com/docs-manifest.json Empty string disables documentation sync (air-gapped, or when you do not want outbound fetches). Point it at a mirror of the docs site if you host your own.

These rows are inserted on first seed and never overwritten. Change them in Operate → System configuration or with a BCONFIG update; no restart is required.

Refreshing the documentation corpus

docker compose exec -T backend php bin/console app:selfaware:sync-docs

The command fetches /docs-manifest.json from the configured URL, downloads changed Markdown pages, and re-indexes them. It also runs once a day on the scheduler role, and again shortly after a published version bump. The corpus is system-owned and never shown in a user's file list.

Release checklist: KNOWN_ABSENT

PlatformCapabilityInventory::KNOWN_ABSENT is the only hand-maintained list: capabilities the product deliberately does not offer (for example music generation). “Running code” is special: it is listed as absent, but on an installation with the Secure compute module on, the inventory reports File work as available instead and points at modules/compute. On every release that ships a new capability, review that list — remove an entry the product now provides, and add an alternative for anything newly and deliberately unsupported.