RFC: Providers, capability slots and server-side model configuration

[wyuc]

Status (Oct 3): P0–P2 are on main (#1765). The configuration-modes revision (defaults, explicit lock, allowUserKeys, settings derived from what a user can change) ships with 1.2.0 and is in development on integration/server-first, tracked in #1725. See the revision history at the end for what changed in this document.

Summary

This RFC reduces how OpenMAIC connects to models to three concepts:

• Provider: an account the server can call.
• Capability slot: a product use that needs AI, organized as a tree.
• Assignment: which provider and model a slot uses.

Whether a capability is available follows from whether its slot resolves to an assignment. A token plan is an ordinary provider that happens to cover many slots.

All configuration lives on the server, and each source has one job: operators write openmaic.yml (server defaults, plus what they choose to lock), users edit in the web UI and changes are stored in the database, and .env only holds secrets and boot parameters. Changes to the yml take effect on restart. The browser no longer stores keys, and requests no longer carry keys or provider choices.

The goal is a Docker deployment that runs from a single command: zero configuration goes through a first-run wizard, and a real deployment mounts one yml file. Single-user and multi-user deployments use the same mechanism and differ by one policy switch.

Background and problems

OpenMAIC started as a client-side, single-user tool: the person using it, paying for it and configuring it was the same person, and settings lived in the browser. Server persistence is now the only durable store for courses, media and folders (#1658, landed in #1710), so these roles separate. Settings did not move with them: every provider key still lives in the browser and travels with each request. There are six concrete problems today:

1. Three layers of overrides and no single answer. server-providers.yml is the base, environment variables override it field by field, and the browser overrides again per request through headers such as x-api-key, x-model and x-image-provider. No single place decides which model a call uses or where that choice came from.
2. Structured configuration is squeezed into environment variables. The yml can only describe providers, so the default model and per-stage routing have to be written as DEFAULT_MODEL and a JSON string in MODEL_ROUTES. .env.example already has 131 variables, and an operator's MODEL_ROUTES silently overrides the user's per-stage choices.
3. A token plan overwrites other providers instead of being referenced. Connecting a plan writes its key into several other providers' configs, which requires enrollment markers, seed fingerprints, yielding between plans and restore-on-disconnect (apply-token-plan.ts, 766 lines). It also only exists in the browser, so operators cannot use it.
4. Capability switches are scattered across three places. There are browser flags such as imageGenerationEnabled; server flags <CAP>_<VENDOR>_ENABLED=false that can only turn off one vendor; and NEXT_PUBLIC_* values baked in at build time, which a prebuilt image cannot change.
5. Caller-supplied provider endpoints are an attack surface. Because the browser sends base URLs and keys with each request, every route that calls a provider has to defend against server-side request forgery on an address the caller chose. The 1.1.1 and 1.1.2 security releases fixed this class route by route. Keeping provider configuration on the server narrows the surface to configuration writes, validated once when saved.
6. Frontend settings mix five kinds of things. One settings store holds provider credentials, generation options, personal preferences and layout state, and each of the seven capabilities has its own differently shaped provider state.

Scope

This RFC answers one question: when the system calls an AI capability, which vendor, which model, and whose key. The following topics are out of scope and have their own homes:

Topic	Where it belongs	Relation to this RFC
Identity and multi-tenancy	#1658 (identity seam and server persistence)	Only decides which workspace web settings belong to
Product feature flags (Pro workbench, editor, …)	Separate cleanup; move to runtime reads	None
Mute and microphone buttons during playback	In-use controls and personal preferences	None (whether voice input exists at all is the asr slot)
Voice, speed and playback preferences	Personal preferences, stored per user on the server	None
Sidebar and panel widths	Local to the browser	None

Moving each capability's execution dispatch from switch statements to a registry is orthogonal engineering work and can proceed in parallel.

Core model

There are only three concepts; everything else follows from them.

Provider: an account that can be called, made of {id, preset, baseUrl, apiKey}. Which capabilities and models it offers is described by a preset in the built-in registry, not stored in user data. Direct vendors, aggregator gateways, token plans and custom OpenAI-compatible endpoints are all providers; they only differ in how many capabilities they cover.

Capability slot: a product use that needs AI. Slots form a forest with one tree per capability type, and each root is the default for that capability. A dotted child slot's parent is the slot with its last segment removed; top-level LLM use slots have llm as their parent.

Slot	Parent	Requirement	Current stages it covers
llm	—	chat	Every call not covered by a slot below
course.research	llm	chat	web-search-query-rewrite
course.outline	llm	chat	scene-outlines-stream
course.agents	llm	chat	agent-profiles
course.content	llm	chat	scene-content
course.content.slide / .interactive / .quiz / .pbl	course.content	chat	scene-content, split by scene type
course.actions	llm	chat	scene-actions
classroom	llm	chat	chat-adapter, quiz-grade, pbl-chat, pbl-v2-runtime*
agent	llm	chat + tool calling	maic-agent, maic-agent-driver
agent.title	agent	chat	conversation-title (Pro session titles); yml only, not shown in the UI
tts / asr / image / video / webSearch / document	—	own type	One root slot each

The course-related LLM slots map one-to-one to the stations in the Course Model settings (web research, outline, agents, scene content, scene actions, classroom), so the UI, the yml and the database all use the same names.

The test for whether a use gets its own slot is: would a user switch models for this use on its own? If yes, it gets a slot. Purely technical splits (such as the four PBL runtime endpoints, or title generation) are folded into a slot in code. The 21 existing stage keys become an internal "stage → slot" mapping in code, where each stage belongs to exactly one slot; they no longer appear in configuration or the UI. This also replaces the current "station → stage keys" alignment table in the settings UI (station-stage-keys.ts) and the class of bugs where a missed key silently falls back to the main model.

Assignment: slot → providerId:modelId (optionally with call parameters such as thinking, and a fallback model), or an explicit null. A provider without models to pick (most search and document services) is referenced by its id alone (webSearch: tavily), which means its default model; chat slots always name a model. The fallback is the model to retry once on a retryable failure, as introduced in #1614; it belongs to the assignment and is inherited with it.

Inheritance rules

• Resolution walks up from the slot of the call, and the first node with an assignment wins. A parent's value is therefore the default for its whole subtree.
• Inheritance is computed at resolution time, not copied: changing a parent immediately changes every child that has no assignment of its own.
• Unset means keep walking up; an explicit null stops there and makes the whole subtree unavailable.
• Requirements belong to the slot that declares them and are not passed down: each slot checks its own requirements against the model it resolves to, assigned or inherited. If that model does not meet them, the slot is marked "requirement not met" and calls fail loudly instead of silently making do. (agent requires tool calling; agent.title does not, so it can use a cheap model.)
• Locking is explicit: the yml's lock names nodes, and a locked node fixes its whole subtree. Writing a node under slots does not lock it; it sets the server default.

Three consequences:

• Capability availability = whether the slot resolves to an assignment. There are no separate *Enabled flags. An operator turns a capability off by default by writing null on its node, and keeps it off for everyone by also listing it in lock. Capability switches live on the cards in the Course Model settings; the generation composer no longer has them.
• Token plan = a provider covering many slots. Its preset declares recommended assignments with slot keys (for example course.content.slide). "One-click connect" means the first-run wizard adds the provider and fills the slots it covers that are still unassigned; after that it is an ordinary provider. Enrollment markers, seed fingerprints, yielding and restore-on-disconnect all go away.
• Switching models = changing assignments. When a provider is deleted, nodes that referenced it lose their assignment and the UI says so; from then on they inherit from their parent.

Configuration sources

Each source has one job, and they no longer override each other field by field.

Source	Written by	Contains	Takes effect
openmaic.yml	Operator	Providers, assignments, policy; same concepts as the UI	Read at startup; restart to apply
Database	Web settings	Providers, assignments; stored per workspace	Immediately
.env / Secret	Operator	Secrets, boot parameters	Read at startup

There are two rules: what the yml writes under slots is the server default, which users may change in the UI; what it names under lock is fixed together with its subtree, shown as "fixed by the administrator" and read-only. Everything a user changes is stored in the database. .env is only referenced from the yml through ${VAR} and no longer overrides any field directly.

# openmaic.yml
providers:
  minimax:
    preset: minimax              # built-in template (token plan or vendor)
    apiKey: ${MINIMAX_API_KEY}   # secret referenced from the environment
  local:
    preset: openai-compatible
    baseUrl: http://ollama:11434/v1

slots:
  llm: minimax:MiniMax-M3
  course.content.slide:
    model: minimax:MiniMax-M3
    thinking: { enabled: false }
    fallback: minimax:MiniMax-M2.7   # retried once on a retryable failure
  tts: minimax:speech-2.8-turbo
  video: null                    # off by default; users may turn it on

lock: [tts, video]               # fixed for everyone, with their subtrees; `lock: all` fixes the whole tree
allowUserKeys: false             # whether users may add providers of their own (keys, token plans)

• A slot not listed under slots has no server default and is left to the UI.
• lock names slots written under slots (or lock: all); a locked slot whose subtree resolves to nothing is refused at startup. A locked node also fixes its children: a user cannot set a child of a locked slot.
• A provider listed without any assignment can be picked in the UI; its key is never visible to the UI.
• The yml is validated at startup: an unknown preset, a reference to a missing provider or an unset ${VAR} fails startup with the exact location, instead of being skipped silently.

Resolution and security

Every AI call goes through one server-side resolver: resolveSlot(workspace, slot) → {provider, model, params, source}.

1. The call site finds its slot through the in-code "stage → slot" mapping, for example scene-content with scene type slide → course.content.slide.
2. If the slot is in a locked subtree, resolve it from the yml alone: walk up from the slot to the locked node and take the first assignment the yml writes.
   Otherwise the user's choice wins anywhere on the lineage: walk up the tree through the workspace's assignments first; only if none is found, walk up through the server defaults (the yml, or translated legacy variables). Return on the first assignment; an explicit null stops either walk. Server values are only defaults: whatever a user changes wins, and a step that follows its parent follows the user's choice on that parent.
3. If nothing is assigned up to the root, the capability is unavailable and the caller fails loudly. There is no fallback to any vendor.

source records where the value came from (server default, workspace, or fixed by the administrator), and the settings UI uses it to label each card.

Requests no longer carry keys or provider choices: x-api-key, x-base-url, x-model, x-model-routes, x-image-provider, x-video-provider and the equivalent body fields are removed. Generation requests only carry generation options. Background jobs can reach credentials after the browser is closed.

Key storage and display:

• Keys in the database are encrypted with an instance secret, OPENMAIC_SECRET_KEY. If unset, one is generated on first start and written to the data volume; if it is lost, stored keys must be re-entered.
• The API is write-only for keys: reads return only a mask (sk-…abcd) and connectivity status.
• Keys from the yml or environment are never stored in the database and are never visible to the UI.
• Saving a provider checks connectivity on the server. A failed check still saves, but marks the provider unavailable.

Browserless APIs (such as /api/generate-classroom) resolve against the caller's workspace and behave the same as the UI.

Frontend and settings UI

The frontend holds no configuration. It is a viewer and editor for the server's slot tree. The first purpose of the UI is to make routing readable: after connecting a token plan, you can see at a glance which model each step uses. Changing it comes second, and most users never will.

API

• Read: the resolved tree. Each slot carries its effective value, its source (server default / workspace / fixed / inherited from which node / filled by which plan), whether it is locked, and whether it meets its requirements.
• Write: only unlocked nodes, into the current workspace.
• Generation requests carry no model or key, and the frontend does no fallback logic.

What the settings show: only what the user can change

Users never see slots, locks or policies as concepts. The settings take one of three shapes, derived from the configuration:

Shape	When	What is shown
Set it up yourself	allowUserKeys is on (the default)	Token Plan, Model Services (add a service, enter a key) and the course model diagram
Choose a model	allowUserKeys: false	Only the course model diagram, choosing among the providers the yml declares; no Token Plan, no adding services
Configured by the administrator	every slot is locked (lock: all)	The same course model diagram with every card read-only; nothing to operate

One rule decides every control: show it only if using it can change something. Adding a service for a capability appears only when that capability still has a slot the user may set; Token Plan appears only when keys are allowed and at least one slot the plan recommends is not locked. A locked card collapses to one read-only line with a lock and "fixed by the administrator"; a card on a server default says so and offers "reset to server default" once the user has changed it.

Course Model settings: a zoomable flow diagram, read-first

                 [Pro agent] ── [ Chat model · default ]            [Voice input]
                                   │  │  │  │  │  │
  row 1:  Doc parsing → Web research → Outline → Agents ─┐
                                                         │
  row 2:  Classroom ← Images/Video ← TTS ← Scene actions ← Scene content
                      └────────── per page ──────────┘        ▼ (expand)
                                          slide · interactive · quiz · PBL

• Canvas: pan, zoom (⌘/Ctrl + wheel, buttons, fit to view). Only two kinds of lines: grey arrows show generation order, purple lines show inheritance (solid when following the parent, faint dashed when set separately).
• LLM parent node: "Chat model · default" at the top is the llm root, where the default model is set. Every LLM step links to it. This replaces the main-model control currently at the top of the panel.
• Pipeline: two rows. Row one is preparation (doc parsing → web research → outline → agents); row two runs right to left through per-page generation (scene content → scene actions → TTS → images/video) and ends at classroom. The rows are offset so that lines from the parent to row two pass through the gaps in row one. The whole graph fits a settings dialog at roughly 80–90% zoom.
• Edit on the card, no side panel: the model line on a card is itself a button. Clicking it opens a picker in place: the first option is always "follow parent", then models grouped by provider, then a note and a "Manage providers" link. The picker does not scale with the canvas and becomes a bottom sheet on mobile. A side panel would cover the canvas and force it to pan out of the way, and each card only has one or two models and a switch to edit.
• Capability switches live on the cards: web search, TTS, images, video and voice input each have a switch next to their model line. Off means the slot is null: the line shows "off" and the flow arrow turns dashed. If no provider offers a capability at all, there is no switch, only "not configured". The generation composer no longer has capability switches.
• Expandable children: the scene content card has a "scene types · N set separately" row. Expanding it shows four child cards (slide / interactive / quiz / PBL) linked back by inheritance lines and edited the same way. It starts expanded when a plan assigns a scene type.
• Provider-neutral: the source is plain grey text with the provider's name (for example MiniMax, Kimi, deployment, built-in). No plan gets its own color or badge. The empty state is a generic "Connect a token plan" that lists all plans side by side; after connecting a plan that only covers chat (such as Kimi), uncovered capabilities stay grey.
• Standalone capability: voice input (asr) is not part of the generation pipeline and does not follow the default chat model. It is a separate card in the top-right corner with no inheritance line; its switch and model live on that card. The classroom card only configures its chat model.
• Outside the pipeline: only the Pro agent, as a compact card left of the parent, also linked to it. Its requirement (tool calling) is stated in its picker. Pro session titles sit under it (agent.title) and follow the Pro agent by default, matching the current code, which reuses the agent's connection; they are not shown separately in the UI.

Where current controls go

Current control	In the new model
Token Plan panel (connect, toggle, priority)	An "Add provider from a plan" entry that also fills unassigned slots from the preset; toggle and priority are removed
Model Services (provider list, keys, per-provider toggle)	Add, edit and remove workspace providers; keys are write-only; deployment providers are read-only. The per-provider toggle is removed: change assignments to switch, delete to stop using
Course Model settings · main model at the top	Becomes the LLM parent node in the diagram (llm root)
Course Model settings · stations	Diagram nodes, each mapped to slots
Course Model settings · image / video / search / TTS / ASR switches	On the corresponding card's model line; meaning becomes "is this slot null"
Home page model picker	A shortcut for editing the llm root; writes the same value as the settings UI, with no "this generation only" mode. Shown only when llm can be changed: hidden when it is locked
Capability switches in the generation composer	Removed; capability switches live only in the Course Model settings
TTS mute and microphone buttons in the classroom	In-use controls, unrelated to slots; whether voice input exists is switched on the Voice input card

Removed from the frontend as a result: capability switches in the composer, keys and the seven provider-state slices in the browser, request headers such as x-model / x-model-routes / x-api-key, global *Enabled flags, the station-stage-keys.ts alignment table, and token plan enrollment / fingerprint / yielding / restore logic.

Deployment journeys

The primary target is Docker. Both ways of deploying land on the same model:

Scenario	What the operator writes	What happens in the UI
Personal, zero config	Nothing beyond docker compose up	Set it up yourself: the first-run wizard adds a provider and fills slots, stored in the database
Personal or team, with defaults	openmaic.yml with providers and slots	Set it up yourself, starting from the server defaults
Hosted, users choose	openmaic.yml with providers, slots, allowUserKeys: false, optionally some lock	Choose a model among the administrator's providers
Hosted, fully fixed	openmaic.yml with lock: all	Configured by the administrator: the diagram, every card read-only

Single user

1. docker compose up. Since feat(persistence)!: server-backed persistence only, with a one-way legacy browser import #1710 this starts a bundled PostgreSQL and runs in single-user owner mode: every request resolves to one fixed owner, so the configuration survives browser changes.
2. Open the UI. With no llm assignment, the first-run wizard opens: pick a token plan and enter its key, or pick a vendor / custom endpoint. After the connectivity check passes, the slots it covers are filled automatically.
3. Go back and generate. To turn a capability off (for example video), switch it off in the Course Model settings.
4. Later, add or remove providers and change assignments in settings.

Only the first-run wizard fills slots from a preset. Slots in the yml are written out explicitly; they are defaults unless lock names them. A public deployment can set ACCESS_CODE to keep strangers out.

Multi-user

• Operators configure providers and default assignments in the yml, set allowUserKeys: false, lock what must not change, and configure identity per [RFC] Owner / identity seam and server-only persistence (tracking) #1658.
• Users sign in and generate directly, and never see a key. Slots not locked can be switched among the models of the operator's providers.
• With allowUserKeys: true, users can also add providers in their own workspace, effective only for themselves.

A team sharing one workspace behaves like a single user: members share one set of web settings.

Compatibility and migration

Deployments that only configure providers and a default model upgrade without changing their configuration; the old forms are kept for two minor versions and then removed. Per-stage routing is the exception: it has to be rewritten as slots.

• Old environment variables (MINIMAX_API_KEY, TTS_MINIMAX_API_KEY, DEFAULT_MODEL, MODEL_FALLBACK, …): translated at startup into the equivalent yml structure (providers, DEFAULT_MODEL as the llm default, MODEL_FALLBACK as its fallback; nothing translated is locked), with a deprecation notice. <CAP>_<VENDOR>_ENABLED=false has no equivalent and is reported. When openmaic.yml exists, the old variables are ignored with a notice.
• MODEL_ROUTES: not translated. Per-stage routes do not map one to one onto slots (several stages share a slot, the agent driver and retries follow rules of their own), so a deployment that sets MODEL_ROUTES without openmaic.yml fails at startup with a message asking for the per-stage models as slots.
• Old server-providers.yml: translated the same way, with a prompt to migrate to openmaic.yml.
• Settings already stored in browsers: imported through the one-way legacy browser importer added in feat(persistence)!: server-backed persistence only, with a one-way legacy browser import #1710, using its completion ledger. Provider configs and keys are imported into the workspace database (only if policy allows), the model choice becomes the llm assignment (per-stage routes are not imported, for the same reason as MODEL_ROUTES; they are set again on the model diagram), and token plan enrollment becomes an ordinary provider. Keys are cleared from the browser after import.
• Request headers: once server-side resolution ships, x-api-key and friends are kept for one version, only for browserless API compatibility, and responses mark them deprecated.
• Feature flags: moving NEXT_PUBLIC_* to runtime reads is out of scope here, but it is a prerequisite for prebuilt Docker images and should land in the same timeframe.

stageRoutes in token plan presets are translated through the "stage → slot" mapping, since the presets are maintained in this repository and can be adjusted where stages merge.

Phases

Work happens on the integration/provider-config branch (tracking: #1725), in four phases that can each be reviewed on their own.

Phase	Content	Depends on
P0	Types for provider / slot / assignment, the openmaic.yml schema and the "stage → slot" mapping; implement resolveSlot; translate old provider variables, server-providers.yml, DEFAULT_MODEL and MODEL_FALLBACK into the new structure	—
P1	Workspace config table with encrypted storage; all routes go through resolveSlot; request headers enter deprecation	Server persistence (#1710, landed)
P2	Settings UI reads and writes the server API and shows lock state; first-run wizard; remove the seven frontend provider slices and token plan enrollment; import browser settings	P1
P3	Remove the deprecated environment variables, server-providers.yml and request headers	Two minor versions after P2

In parallel: move each capability's execution dispatch from switch to a registry (TTS and web search first), with no dependency on the phases above.

Open questions and non-goals

Open questions

• Final slot list (first task of P0 in [RFC] Providers, capability slots and server-side model configuration (tracking) #1725): the table above is a draft. Each current call site (including ones not listed, such as generate-classroom and director) needs to be checked so that every stage has exactly one slot, and we need to confirm that agent (with agent.title) is enough outside the pipeline.

Resolved

• Default identity for single-user Docker: the single-user owner mode from feat(persistence)!: server-backed persistence only, with a one-way legacy browser import #1710, so a new browser does not start a new workspace.
• Can regular users change models on slots the operator did not lock? Yes: slots in the yml are defaults, and operators fix what must not change with lock (Oct 3 revision).

Non-goals

• Hot reload of the yml: changes apply on restart.
• An instance-level admin UI or admin role: the instance level is only the yml and environment variables.
• An environment-variable shortcut for token plans: single users go through the first-run wizard and unattended deployments write the yml, rather than adding a third entry point.
• Automatic load balancing or balance-based routing across providers: model fallback stays with the agreed approach of retrying once on a backup model for retryable errors.
• Calling model vendors directly from the browser.

Feedback on the slot tree, the precedence rule and the phases is especially welcome.

Revision history

• Oct 3: configuration modes, for 1.2.0 (before openmaic.yml is first released). Writing a slot in the yml no longer locks it: slots are server defaults users may change, and locking is explicit with lock: [...] or lock: all, which fixes the whole subtree of each named slot (a user can no longer override a child of a locked slot). policy.allowWorkspaceProviders becomes allowUserKeys. The settings take one of three shapes derived from the configuration (set it up yourself / choose a model / configured by the administrator, all on the same course model diagram) and show a control only when using it can change something, so a fully locked deployment no longer offers Token Plan, adding services or the home page model picker. Translated legacy variables become defaults, as DEFAULT_MODEL already was. Outside locked subtrees a user's choice anywhere up the tree outranks every server default. Found while hand-testing a deployment whose yml wrote every root: every control in the settings was visible and none could change anything.

• Sep 30: P1 and P2 landed on integration/provider-config (feat(persistence): workspace model configuration with keys encrypted at rest #1733–refactor(settings)!: server-side model settings only; import browser settings once #1744, fix(config): a policy without workspace providers also stops using them #1750). Decisions made along the way: a workspace provider reaches media, search and document services only at its preset's own endpoint (custom endpoints and self-hosted media presets are deployment-only); the settings API serves the preset catalogue, so no client-safe registry split was needed; fallbacks apply to language-model slots only; policy.allowWorkspaceProviders: false also stops using providers workspaces added before; provider options (non-secret, deployment-only) carry settings such as the VoxCPM backend; the browser import carries providers, keys and the model choice, not per-stage routes or per-browser capability toggles; the browser's own speech recognition stays available while asr is unassigned.

• Sep 29: updated after feat(persistence)!: server-backed persistence only, with a one-way legacy browser import #1710 landed. Background now reflects that settings and keys are still in the browser; added the caller-supplied endpoint attack surface as a motivation; assignments carry the feat(llm): retry once on a fallback model for retryable failures #1614 fallback; the Docker journey uses docker compose up with single-user owner mode, which resolves the first open question; the browser settings import reuses the feat(persistence)!: server-backed persistence only, with a one-way legacy browser import #1710 importer; development moved to integration/provider-config, tracked in [RFC] Providers, capability slots and server-side model configuration (tracking) #1725.

• Sep 30: a provider-only reference (webSearch: tavily) names the provider's default model (feat(config): resolve media and tool capabilities through their slots #1737); retries follow the slot's fallback (feat(config)!: resolve every LLM call through its capability slot #1735).

• Sep 30: MODEL_ROUTES and per-stage routes in browsers are no longer translated: emulating them needed special rules for shared slots, the agent driver and retries and still relied on easy-to-miss notices. Only providers, DEFAULT_MODEL and MODEL_FALLBACK carry over; MODEL_ROUTES without openmaic.yml fails at startup (refactor(config)!: translate only providers and the default model #1732).

• Sep 29: requirements are no longer inherited by child slots, found while mapping stage keys to slots (feat(config): capability slot registry and stage-to-slot mapping #1726): inherited, agent.title would have needed tool calling.

[wyuc]

Alignment with #1658 (owner identity seam, now on main via #1669), on two points this RFC depends on:

1. Workspace = owner. The owner seam already resolves an opaque owner id for every request, Server Action and background run. Background runs rebuild the principal from the stored owner id, and anonymous-to-account claims re-key owner data. I suggest this RFC's "workspace" is exactly that owner id: web settings stored per owner, and background jobs resolving credentials from the owner recorded on the run. No separate workspace concept is needed.
2. Default identity for single-user Docker (the first open question). The next persistence phase will make server persistence the default. The official docker compose will start Postgres by default, and PGlite will be used only for local development (pnpm dev) and tests, clearly labelled. For identity, we plan a built-in single-user auth method as the compose default. It resolves every request to one fixed owner, is intended for localhost/private-network use, and requires ACCESS_CODE when exposed. A new browser then sees the same library and settings, and doesn't re-run the first-run wizard. Deployments with real accounts register their own auth methods instead.

Browser-stored provider keys and model choices would move into the per-owner settings store in this RFC's P2, once encrypted storage (P1) exists. Course data is migrated earlier, silently in the background, as part of the persistence work.

[wyuc]

Resolution for the generate-classroom item under "Open questions" (final slot list), plus what it means for browserless APIs in general.

Browserless APIs use the same slot configuration as the UI. /api/generate-classroom gets no slot of its own and no API-specific settings. It resolves against the caller's workspace (the workspace of the owner resolved through the identity entry point from #1669). In single-user mode that is the one owner, so there is exactly one configuration. Operator locks in openmaic.yml apply the same way. A change in the Course Model settings, such as switching off video or pinning course.outline, applies to the next API run just as it does to the next UI run.

The generate-classroom catch-all stage goes away. Today the server pipeline first resolves one model for the generate-classroom stage and falls back to it for every step that has no route of its own (#1048). Under the slot model, each step resolves the same slot the classic pipeline uses: course.research, course.outline, course.agents, course.content.*, course.actions, plus the tts, image, video and webSearch roots. An unset slot inherits from llm as usual, so "use the defaults" needs no special case. A required slot that resolves to nothing fails the job loudly.

Request fields are removed outright, with no deprecation window. This covers:

• the capability switches enableWebSearch, enableImageGeneration, enableVideoGeneration and enableTTS, plus agentMode. Availability follows from slot assignments, as in the UI.
• the provider fields webSearchProviderId, webSearchApiKey, webSearchModelId and baiduSubSources.

The request carries only generation input. Correspondingly, the line under "Compatibility and migration" that keeps x-api-key and related headers for one version for browserless API compatibility is dropped: those headers go away together with the browser ones.

Capability discovery for API callers comes from slot resolution. It no longer comes from scanning provider lists as /api/health does today. It reports whether each slot resolves, the same state the settings cards show.

The openmaic skill's generate flow, which currently probes capabilities and sends the switches, will be updated in the same change.