RFC: OpenMAIC 1.2.0 — server-first

[wyuc]

Status: Draft · Release: 1.2.0 · Tracking: #1658, #1725 · Next: 1.3.0 material library (#1716)

Summary

What. In 1.2.0 the server becomes the only home for courses and media, identity, model configuration and course generation. The browser is a client. The classic user flow does not change.

Why. In 1.1.x most of this exists twice, in the browser and on the server. That split:

• loses work: a course is gone when the browser clears its storage (#321);
• costs money: media is regenerated and re-billed in every new browser (#1386);
• gives different results: the API and the web UI generate through different pipelines (#51);
• keeps causing security fixes: callers could point the server at any provider endpoint (GHSA-g87c);
• shuts out agents and scripts, which have no browser.

Why a breaking change, and why now. Keeping both halves as options keeps the split. The server side is mostly built and unreleased, so one release lets everyone migrate once, with automatic one-way imports. 1.3.0 builds on it.

Scope

	Workstream	State
A	Server persistence, one-way import of browser data	on main (#1710)
B	Owner identity: single user, shared team, host auth, claims	on main (#1669)
C	Server-side model configuration (slots, openmaic.yml, settings)	P0–P2 on integration/provider-config (#1725)
D	Headless API: { requirement, materialIds }, saved to the owner's library	on integration/provider-config (#1728, #1730)
E	Server-side generation runs	to build
F	Long-running Node only; Vercel supported up to 1.1.x	to do
G	Agent registry on the server: built-in agents in code, custom agents in the database	to build

Where things live

	1.1.x	1.2.0
Courses, chat, media	browser (server opt-in)	PostgreSQL + asset pool
Identity	the browser that holds the data	resolved owner
Keys and models	browser, sent per request	server slots
Classic generation	browser calls each step	server run
Headless generation	separate server pipeline	the same run
Custom agents	browser localStorage	database (built-in agents stay in code)
Deployment	Docker, Node, Vercel	Docker or Node + PostgreSQL

E. Server-side generation runs

Today the browser drives classic generation step by step and hands state between pages through sessionStorage; a separate server pipeline serves the API and has drifted from it. Closing the tab stops generation.

Design. A run is an owner-scoped PostgreSQL record. A runner in every process executes its steps — the existing classic step logic, moved from the API routes into server functions — and commits a checkpoint after each step. If a process dies, another one takes over from the last checkpoint. The browser starts the run, subscribes to its events, and sends commands. The separate server pipeline is retired; the headless API becomes a view of a run.

Part	Contract
Input	requirement, materialIds, interactive, taskEngine, agents (auto, or agent ids: built-in from code, custom from the owner's registry), learner profile, outlineReview (wait for the UI, auto for the API). No keys or models.
States	preparing → outlining → awaiting_outline_confirmation → generating → completed, plus paused and stopped
Outline review	the run always waits for confirmation, holding no worker; with the page open the browser keeps today's review screen and 2.5 s auto-continue; if the user left, the run waits until they confirm from the course card. Confirm sends { outlineRevision, commandId }
After confirmation	the run always completes in the background; there is no stop or pause. Leaving the page or going back to home does not stop it. Deleting the course ends the run at the next step
Events	ordered by seq; snapshot + GET …/events?after=<seq> over SSE, polling fallback; outline tokens stream live
Commands	confirm-outline and retry, idempotent by commandId, owner-checked
Failures	linear: a failed step pauses the run; Retry re-runs that step only
Library	a course card appears when the run starts and shows its state (outlining, waiting for confirmation, generating n/m, paused after a failure)
Concurrency	a configurable per-owner limit on active runs
Materials	uploaded with POST /api/materials, extracted on the server; images stored as course assets, not inline base64

Parity. Before browser orchestration is removed, these must match 1.1.x side by side, with screenshots: preview steps and labels; outline streaming; outline review (enabled, opened early, auto-continue, edits); agent choice and non-blocking agent cards; entering the classroom after the first scene; in-order scene progress; pause and Retry; media and its Retry; reload or another device rebuilding the same view. New: the course card appears from the start, and generation continues after leaving the page.

Pro mode

Classic runs, the headless API and the Pro agent's generation tools call the same step functions; only the orchestration differs (a fixed pipeline vs. an agent deciding). Runs execute on the agent runtime's infrastructure — leases, the event log, NOTIFY wake-ups and the owner event stream — rather than a second runner. A course is read-only in the classroom editor and in Pro until its run completes; after that, the Pro agent can take over. Pro ignores the classic outline.

G. Agent registry

Built-in agents stay in code (read-only, updated and translated with releases). Custom agents move from browser localStorage to the owner's records in the database and are imported once, like other browser data. Runs reference agents by id.

F. Deployment

A run needs a process that outlives requests, as the Pro runner and background jobs already do. 1.2.0 supports Docker / docker compose or pnpm start with PostgreSQL, and vercel.json is removed from main. The README keeps a Vercel section that says serverless deployment is supported up to 1.1.x, with its Deploy button pointing at the release/1.1.x branch; data carries over when such a deployment later moves to a long-running host.

Breaking changes

Audience	Change
Operators	DATABASE_URL required; NEXT_PUBLIC_PERSISTENCE removed; compose starts PostgreSQL in single-user mode; Vercel unsupported; MODEL_ROUTES must be rewritten as slots in openmaic.yml (fails at boot otherwise); keep OPENMAIC_SECRET_KEY or its secret file with the database; dev-token variables removed
Users	browser data, model settings and custom agents are imported once; leaving the page no longer stops generation; anonymous identity lasts 400 days — personal installs should use single-user mode
API callers	generate-classroom takes { requirement, materialIds }; /api/classroom removed; jobs and materials are owner-scoped (keep one cookie jar in anonymous mode); x-api-key / x-model style headers deprecated
Embedders	storage configure* calls require a store; no unscoped document store; auth methods and hooks registered once from instrumentation.ts

The changelog's Unreleased section is the full list.

Upgrade

Deployment	Do
docker compose	pull and start; move model settings to openmaic.yml or the Models page; rewrite MODEL_ROUTES; open the app once in each browser that has local courses
pnpm start + own PostgreSQL	set DATABASE_URL, an identity mode, and OPENMAIC_SECRET_KEY for multiple instances; then as above
Vercel	stay on 1.1.x, or move to a long-running host with the same database
Skill / API	follow the updated openmaic skill: upload, submit, poll as the same owner

Not in 1.2.0

Material library (#1716, 1.3.0); PDF naming cleanup (#621); provider P3 (two minors later); removing the temporary importers; stop/pause controls for runs; a Pro tool that starts a classic run; a container-platform one-click template.

Release plan

E and F land on one integration branch based on integration/provider-config, which merges into main once; 1.2.0 is cut from main.

Phase	Content
G	agent registry in the database; one-time import from localStorage
M	versioned SQL migrations per store (#1658 phase 7)
E1	run table, events and commands; step functions extracted from the routes and shared with Pro tools; runner on the agent runtime infrastructure, with checkpoints and takeover
E2	headless API on runs; retire the old server pipeline
E3	browser becomes a run client; parity checklist with screenshots
E4 + F	remove browser orchestration and vercel.json; README Vercel section for 1.1.x; docs and changelog

Release candidate: 1.2.0-rc.1 is cut from main after the merge and used for the upgrade rehearsal.

Release criteria: CI green including the PostgreSQL contract suites; an upgrade rehearsal from 1.1.x on the release candidate (browser data and custom agents, legacy classrooms, env-only config, MODEL_ROUTES, two instances); the parity checklist; real runs of classic generation, headless generation and a forced-restart takeover; complete changelog (the model configuration entries are still missing) and docs.

Open questions

• Default per-owner limit on active runs (proposed: 2).

Appendix: prior art

Agent platforms keep execution on the backend and treat clients as entry points (OpenClaw Gateway, OpenHands Agent Server, Letta App Server). Long-artifact generators run on the server (Gamma API, NotebookLM Audio Overviews, open-notebook, DeepTutor). Plan approval inside a server run is a standard primitive (LangGraph interrupt, used by Open Deep Research to approve a report plan; Inngest, Trigger.dev, Temporal). LobeHub removed its client database in January 2026 (lobehub#11123). The trap to avoid is "background" without durability: in-process tasks that fail on restart.

[wyuc]

Tracking issue: #1755. The remaining 1.2.0 work (M, G, E1–E4, F) lands on integration/server-first, based on integration/provider-config; each phase is its own PR there and links back here.

[redbotster]

the server-first move is the right call, especially workstream C. centralizing model config means you now have one place where provider keys live, but that also means one place to get wrong. the GHSA-g87c fix you referenced (endpoint injection) is a symptom of keys and endpoints being passed around as plain config rather than being brokered. once you have server-side slots, consider a secrets backend where the key never materializes in env vars or request payloads, only a short-lived reference the server exchanges at call time. full disclosure: i work on 1Claw, which does exactly that for agent and server contexts via an HSM-backed vault, so i'm not a neutral party, but the pattern holds regardless of what tool you use.