Administration

What an operator manages in a Synaplan instance: AI providers and their keys, feature flags, users and groups, 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, secure compute (file work) — are feature modules. Operate → Feature Status shows which ones this installation has; each has its own enable guide under Feature modules. File work and spoken answers start with the standard stack; a dedicated box or cluster follows Run the compute sidecar.

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, and since 4.8 the one web editor for instance provider keys. Operate → System configuration → AI services no longer shows password fields; it shows a status card per provider (set from the environment / Helm, or override under Models & keys) and points here. 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 / Helm import. Keys set in the environment (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 Helm install with keys only in secrets never needs the UI. A key later saved in the UI wins permanently.
• Personal accounts are separate. A user's own Higgsfield credentials and own Anthropic key (for Claude Code) live under Manage → Assistants → Your AI accounts and override the instance key for that user only.

Supported providers include OpenAI, Anthropic, Google Gemini, Groq, Mistral, xAI, TrustedTokens, A2Agent, HuggingFace, TheHive, Higgsfield, Cloudflare Workers AI, optional Perplexity, and any local model via Ollama or an imported OpenAI-compatible endpoint. Users only see models whose provider is configured (Ollama models must be pulled); administrators still see the full catalog, greyed. Saving a key surfaces that provider's models immediately. The rules, the CLI, and local Whisper are on AI providers & models. A fully local install is Air-gapped installation. The full provider/variable table is in the main README; key-related FAQs are on the Developer FAQ page.

Feature flags

Every feature that shipped in the September 2026 waves is behind a flag in BCONFIG (owner 0), and since 4.8 all of them seed on; the migration Version20260911090000 switched the global rows of older installs on as well. File work (COMPUTE.*) seeds on when COMPUTE_URL and COMPUTE_TOKEN are already set at first seed — and the standard compose stack sets and pins them, so file work and workspaces are offered out of the box there. An existing ENABLED row is never overwritten.

Three ways to switch a flag:

Precedence is environment → per-user row → group policy → global row → code fallback. The variable name is derived from the key: IAM.SHARING_ENABLED → FEATURE_IAM_SHARING_ENABLED.

The non-boolean companions (directory claim path, group display names, everyone-shares policy, tool policies per class, approval expiry) stay on the Access → Sharing and Routing → Tool policies tabs. Upgrading from a release before 4.8? A feature you had deliberately switched off comes back on; pin it with FEATURE_*=false before deploying, or switch it off again afterwards. Full reference: FEATURE_FLAGS.md in the main repository.

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) under Manage → Assistants → Models, limited to providers this installation can reach; administrators curate the full catalog (active, selectable, default, prices), including greyed unavailable rows, on the admin-only tabs of that page. See AI providers & models. The selector shows cost badges, GET /api/v1/config/models returns priceIn / priceOut, and the Usage page logs the real cost of each call — Account → Usage for one's own account, the Usage tab of Operate → Overview for everyone. Operate → Model Status lists which configured models answer their health check.

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, groups and the Operate area

Operate (/admin, visible to ADMIN accounts) has six entries: Overview (system info, usage of all users, health), Feature Status (/admin/features — every optional module and companion with its state), Model Status, AI infrastructure, System configuration and People.

Operate → People (/admin/people) is the only home for users since 4.8 (the former Users tab on Overview redirects there): search, change level, impersonate (audited), delete — plus the Groups, Policies, Platform instances and Audit tabs when the matching flags are on. 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 groups, sharing, per-group policies and directory sync: People & groups. Versioned, publishable assistants and Export & import: Assistants. Tools and approvals, the policies per tool class and the saved-task Steps editor: Tools & approvals. All of them are on by default — see the flag table above.

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.
• Pin what must stay off. A FEATURE_*=false variable in the deployment beats any database row and locks the admin toggle — the right tool when a feature must never be switched on by accident (see Feature flags above).
• Configuration reference for everything else (public URLs, SMTP, Qdrant, OIDC): 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)

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. How to start the sidecar: Run the compute sidecar. 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.