Get an immersive, multi-agent learning experience in just one click

English | Simplified Chinese
Live Demo · Quick Start · Lemonade · FunASR · Features · Use Cases · OpenClaw

` from an `HttpOnly` `anonymous_id` cookie that lasts 400 days (the longest browsers keep one) and is renewed, same value, on every route handler and Server Action response that resolves to it, so it expires only after 400 days without use. Page responses do not renew it, so pages stay cacheable, and a response that clears it (a claim, a retired owner) never renews it. Losing it (a manual clear, or 400 days idle) loses access to that owner's library from the browser: anonymous identity has no other key, which is why the Compose deployment defaults to single-user mode and a multi-user host should use accounts. The middleware mints it on the page response of a browser's first load, so every request the page sends presents one owner; a route handler reached without a valid cookie mints one the same way, and a valid cookie is never replaced. It cannot publish. A host can turn the fallback off, and then such a request is a `401` too. A refused request is never served as an anonymous owner. Out of the box nothing is registered, so every request is an anonymous owner, unless one of two built-ins is selected by the environment (they exclude each other): - `PERSISTENCE_SHARED_OWNER_ID` (requires `ACCESS_CODE`): the built-in `sharedTeam` method resolves every request to that fixed id, so the team behind the access code shares one library and may publish. - `OWNER_SINGLE_USER=true` (the Compose default): the built-in `singleUser` method resolves every request to one owner for a personal installation; see [Single-user mode](#single-user-mode). Authorization reads the principal's `kind` and `roles`, never the shape of the id. The core roles are `course:publish` (publish and unpublish a course) and `admin` (reserved for administrative surfaces; no built-in grants it). ##### Single-user mode `OWNER_SINGLE_USER=true` resolves every request to one fixed owner, `OWNER_SINGLE_USER_ID` (default `local`; 1-128 characters of `[A-Za-z0-9._-]`, so the reserved `anon:` prefix is impossible). The principal is `kind: 'user'` with the `course:publish` role: it is one person's own installation, so publishing works, and unlike `sharedTeam` (a team behind one code, no one person) it gets a claim candidate, see below. No anonymous cookie is minted. **Exposure.** Every request becomes the owner of the whole library, and a route handler cannot tell a local client from a remote one (it does not see the TCP peer, and forwarding headers are set by the client), so nothing inspects requests. Single-user mode runs with or without `ACCESS_CODE`: - **With `ACCESS_CODE`**, the access-code gate admits requests, as for `sharedTeam`. - **Without it**, the deployment relies on nobody else reaching the server: bind it to loopback or a private network (the Compose file publishes on `127.0.0.1` by default; outside Compose, for example `pnpm start -H 127.0.0.1`). The server logs one prominent warning at startup explaining that anyone who can reach it shares, edits and can delete the single library, and how to set `ACCESS_CODE`. It does not refuse to start. A later first-run setup flow may prompt for an access code; for now, set `ACCESS_CODE` yourself before the server is reachable by others. **Earlier anonymous work.** A browser that used the deployment anonymously before still sends its `anonymous_id` cookie. The single-user principal gets a `pendingClaim` for it (see [Claiming anonymous work](#claiming-anonymous-work)), but nothing moves on its own: the default trigger is explicit. To bring that work into the single owner, send `POST /api/identity/claim` (same-origin JSON, body `{}`) from that browser, or set `OWNER_CLAIM_TRIGGER=auto` knowingly. > [!WARNING] > A claim is irreversible. With `OWNER_CLAIM_TRIGGER=auto`, **every** browser > that visits merges its anonymous library into the single owner on its first > request. If several people used the deployment anonymously before, that > merges all their libraries into one shared, deletable library. **The owner id is permanent.** Changing `OWNER_SINGLE_USER_ID` later, or switching from `PERSISTENCE_SHARED_OWNER_ID`, leaves the previous owner's library stranded: it is not anonymous, so it cannot be claimed. To keep a shared-team library, set `OWNER_SINGLE_USER_ID` to the same id. A host that registers its own methods and also wants the single owner as the last resort includes `singleUserAuthMethod()` (exported from `@/lib/server/identity`) last, under the same rules as `sharedTeamAuthMethod()`. ##### Registering methods A host with its own accounts writes a method per credential it accepts and registers them once, from `instrumentation.ts` `register()`, before the server serves a request: ```ts const { configureOwnerAuthentication } = await import('@/lib/server/identity'); configureOwnerAuthentication({ methods: [ { name: 'session', async authenticate(req) { const session = await readSession(req.headers); // host code if (session === undefined) return { status: 'not-applicable' }; if (!session.valid) return { status: 'invalid', reason: 'expired session' }; return { status: 'authenticated', principal: { ownerId: `user:${session.userId}`, kind: 'user', roles: new Set(session.canPublish ? ['course:publish'] : []), assurance: 'verified', }, }; }, describeStoredOwner: (ownerId) => ownerId.startsWith('user:') ? { kind: 'user' } : undefined, }, ], // anonymousFallback: false, // refuse requests no method applies to }); ``` - **Present but unusable is `invalid`, never `not-applicable`.** Answer `not-applicable` only when the method's header or cookie is absent. A method that answers `not-applicable` for a malformed or expired credential of its own kind silently hands the request to the next method or to an anonymous owner; core cannot tell. A method that cannot decide (its key endpoint or session store is down) throws, and the request fails as a server error. - `setCookies` on an `authenticated` answer ride every response, errors included. `reason` on an `invalid` answer is for server logs only. - Server Actions ask the same methods in the same order, through `authenticateFromContext()` when a method has one and otherwise `authenticate()` with the request headers. In a Server Action cookies must be written through `next/headers`; an answer carrying `setCookies` is refused. - `describeStoredOwner(ownerId)` says what kind of owner a stored id is, for work that holds only the id (an agent run, a claim). The anonymous fallback is asked first, then the methods in order. An id nobody recognizes is a `user` with no roles. - The middleware mints the anonymous cookie on page navigations whenever neither `OWNER_SINGLE_USER` nor `PERSISTENCE_SHARED_OWNER_ID` is set: it can run in the Edge runtime and cannot see this registration. A page cookie next to a host credential is a claim candidate like any other anonymous cookie. - With `anonymousFallback: false`, set `OWNER_ANONYMOUS_PREMINT=false`: the cookie would serve no request, and with `OWNER_CLAIM_TRIGGER=auto` it would be claimed and cleared after every cookieless page load. The server warns at startup when this registration leaves pre-minting on. - With the anonymous fallback on (the default), keep pre-minting: without it, an anonymous visitor's first API requests each mint their own owner again. To avoid a claim candidate beside your credential, skip `anonymousOwnerForNavigation` in `middleware.ts` only for the requests your methods authenticate themselves (a page request carrying your session cookie, say). - `issuesAnonymousOwners: true` with `clearCredential()` is only for a method that authenticates anonymous principals itself with a cookie: those `Set-Cookie` values ride every `403 OWNER_RETIRED`. Core never calls `clearCredential()` there on any other method, so an account's session cookie is never cleared because an anonymous identity was retired. - Principals are checked per request: an owner id that is not 1-256 printable non-space ASCII characters, an unknown `kind` or `assurance`, or a `pendingClaim` set by the method is a `500` for that request rather than stored. The same resolved owner is the runtime learner key and the asset partition of `/api/persistence`, so the methods govern those too. Registration is checked at boot, and each of these throws from `register()` so the server does not start: a second call, a call after owner resolution has started, an empty method list, a malformed or duplicate-named method, and the `sharedTeam` rules below. To keep a shared team owner beside host methods, include `sharedTeamAuthMethod()` (also exported from `@/lib/server/identity`) as the **last** method: it always authenticates, so nothing after it would be asked. `PERSISTENCE_SHARED_OWNER_ID` set beside a registration that does not include it, or `sharedTeamAuthMethod()` registered without the variable, fails the boot rather than being ignored. `OWNER_AUTHENTICATOR` and the `TRUSTED_PROXY_*` variables of an earlier built-in gateway-header authenticator no longer exist; if any of them is set, the boot fails with a message pointing here, instead of silently serving every request as an anonymous owner. ##### Recipe: accounts through an identity gateway (signed JWT) OpenMAIC has no built-in gateway authenticator. A deployment behind an identity gateway writes a small method that verifies the **signed** assertion the gateway forwards, against the identity provider's published keys. Unlike a plain user header, a signed token cannot be forged by a client that reaches the app around the gateway. Common sources: | Gateway | Header | Issuer / keys | |---|---|---| | oauth2-proxy with `--pass-authorization-header` (or `injectRequestHeaders` in `--alpha-config` setting `Authorization: Bearer `) | `Authorization: Bearer …` | The IdP's issuer and `jwks_uri`; the audience is the OAuth client id | | Cloudflare Access | `Cf-Access-Jwt-Assertion` | `https://.cloudflareaccess.com`, keys at `/cdn-cgi/access/certs`; the audience is the application's AUD tag | | Google Cloud IAP | `x-goog-iap-jwt-assertion` | `https://cloud.google.com/iap`, keys at `https://www.gstatic.com/iap/verify/public_key-jwk` | The sketch below uses the [`jose`](https://github.com/panva/jose) library, which the host adds as its own dependency. **It is a recipe the host owns and must test**, not code OpenMAIC ships or maintains. Put the file in `lib/server/identity/host/`: the boundary test (`tests/server/identity/cookie-guard.test.ts`) fails on reads of gateway identity headers or of an incoming `Authorization` header anywhere else, core identity files included. Register the method from `instrumentation.ts`. ```ts // lib/server/identity/host/gateway-jwt.ts (host code) import { createRemoteJWKSet, errors, jwtVerify } from 'jose'; import type { OwnerAuthMethod } from '@/lib/server/identity'; const ISSUER = 'https://idp.example.org/'; const AUDIENCE = 'openmaic'; const JWKS = createRemoteJWKSet(new URL('https://idp.example.org/.well-known/jwks.json')); const ADMIN_GROUPS = new Set(['openmaic-admins']); /** jose errors that mean "this token is bad", as opposed to "the keys could not be fetched". */ const TOKEN_ERRORS = [ errors.JWTExpired, // exp / nbf errors.JWTClaimValidationFailed, // iss, aud, other claim checks errors.JWTInvalid, // not a usable JWT payload errors.JWSInvalid, // malformed compact serialization errors.JWSSignatureVerificationFailed, errors.JWKSNoMatchingKey, // unknown kid errors.JWKSMultipleMatchingKeys, // no kid and several candidate keys errors.JOSEAlgNotAllowed, // alg outside `algorithms` errors.JOSENotSupported, // alg or header this library cannot verify ]; /** The token, `undefined` when this method does not apply. */ function bearerToken(headers: Headers): string | undefined { // Cloudflare Access / IAP: return headers.get('cf-access-jwt-assertion') ?? undefined; const match = /^Bearer\s+(\S+)$/i.exec(headers.get('authorization')?.trim() ?? ''); return match?.[1]; } export const gatewayJwtMethod: OwnerAuthMethod = { name: 'gatewayJwt', async authenticate(req) { const token = bearerToken(req.headers); if (token === undefined) return { status: 'not-applicable' }; let payload; try { // Checks the signature against the IdP's keys, `iss`, `aud`, `exp` and `nbf`. ({ payload } = await jwtVerify(token, JWKS, { issuer: ISSUER, audience: AUDIENCE, algorithms: ['RS256', 'ES256'], clockTolerance: 30, })); } catch (error) { // Only a failure of the token itself is `invalid`. Anything else (the key // endpoint unreachable, answering non-200 or unparsable data, a timeout) // is a server fault: rethrown, it fails the request as a 500 instead of // refusing every user as if their token were forged. if (TOKEN_ERRORS.some((type) => error instanceof type)) { return { status: 'invalid', reason: (error as errors.JOSEError).code }; } throw error; } const ownerId = `user:${payload.sub ?? ''}`; if (!payload.sub || !/^[\x21-\x7e]{1,256}$/.test(ownerId)) { return { status: 'invalid', reason: 'unusable sub' }; } const groups: unknown[] = Array.isArray(payload.groups) ? payload.groups : []; const roles = new Set(['course:publish']); if (groups.some((group) => typeof group === 'string' && ADMIN_GROUPS.has(group))) { roles.add('admin'); } return { status: 'authenticated', principal: { ownerId, kind: 'user', roles, assurance: 'verified', channel: 'gateway' }, }; }, describeStoredOwner: (ownerId) => ownerId.startsWith('user:') ? { kind: 'user', roles: new Set(['course:publish']) } : undefined, }; ``` ```ts // instrumentation.ts, inside register() const { configureOwnerAuthentication } = await import('@/lib/server/identity'); const { gatewayJwtMethod } = await import('@/lib/server/identity/host/gateway-jwt'); configureOwnerAuthentication({ methods: [gatewayJwtMethod], anonymousFallback: false }); ``` Notes for the host: - **Absent means not-applicable, present but bad means invalid.** A request without the header falls through (to the anonymous fallback, or a `401` with `anonymousFallback: false`, the usual choice when the gateway covers every route). A wrong signature, issuer or audience, or an expired token, is a `401`, never an anonymous owner. - **A key endpoint outage is not a bad token.** Only the listed token errors answer `invalid`. `jose` reports a JWKS endpoint that is unreachable, answers non-200 or returns unparsable data as a generic `JOSEError` (`ERR_JOSE_GENERIC`), which the recipe rethrows: the request fails as a server error rather than refusing every user as if their token were forged. - **Pin `issuer`, `audience` and `algorithms`.** Without an audience check any token the IdP issued for another application would be accepted. - **`sub` is the stable id**; an email can change or be reassigned. Choose the owner id scheme once: changing it later changes every owner. - **Groups** are IdP-specific (a `groups` claim needs the IdP to release it; IAP sends none). Drop the admin mapping if yours has no such claim. - The gateway still should not be bypassable, and must not exempt app routes from authentication, but a client that reaches the app directly cannot mint a valid token, so no shared secret is needed. ##### Claiming anonymous work A visitor who works anonymously and then signs in has two owners: the anonymous one their courses were written under, and the account. A **claim** moves everything the anonymous owner holds to the account in one database transaction, and retires the anonymous id. **When a claim can arise.** Core attaches the claim candidate itself: when a host method authenticates a non-anonymous principal and the same request also carries a valid `anonymous_id` cookie, the principal gets a `pendingClaim` naming that anonymous owner. This covers a visitor who worked anonymously and then signed in (with the anonymous fallback on), and a deployment that moved from anonymous use to accounts while visitors still hold their old cookie (with the fallback on or off). There is no candidate without a valid cookie, for an anonymous principal, or for the built-in `sharedTeam` (it has no credential of its own, so nothing says whose browser work it is); a method cannot set one itself. The built-in `singleUser` does get one: its deployment has one person, so the cookie names that person's earlier anonymous work. Nothing moves until the claim is triggered: - **Explicitly (the default):** the app calls `POST /api/identity/claim` with a JSON body (`{}`) from its own pages. The answer is `200 { status: 'claimed', moved }` or `200 { status: 'already-claimed' }`, with a `Set-Cookie` that drops the anonymous cookie. - **Automatically:** `OWNER_CLAIM_TRIGGER=auto` claims on the first route request that carries a pending claim, before the handler runs. The explicit routes are exempt, so they still report their own claim. Server Actions never trigger it. Prefer the explicit trigger where one browser can be shared by several people: whoever signs in first takes the anonymous work in it. **The anonymous cookie is a bearer credential.** Whoever presents it can read and edit that anonymous work, and, beside a signed-in account, claim it into the account. On shared devices, clear it (a claim does) before the next person signs in. The cookie is unsigned and not bound to the account, and it is the claim candidate core reads. It is host-only, but a sibling subdomain under the same registrable domain can set a Domain-scoped `anonymous_id` that the browser may send first, so a hostile subdomain could plant which anonymous identity a signed-in visitor claims. Serve OpenMAIC on a registrable domain of its own (or where no untrusted party controls a sibling subdomain). Hardening the cookie itself (a `__Host-` name on HTTPS deployments, refusing a request that presents more than one `anonymous_id`) is a deferred item. | Request | Result | | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | Not same-origin JSON (`Sec-Fetch-Site` other than `same-origin`, a foreign `Origin`, or any content type but `application/json`) | `403 CROSS_ORIGIN_REFUSED`, nothing changes | | An anonymous requester | `403 TARGET_ANONYMOUS` | | No anonymous cookie beside the account | `409 NO_PENDING_CLAIM` | | The anonymous owner was already claimed by another account | `409 ALREADY_CLAIMED_ELSEWHERE`; the cookie is dropped | | Either owner is being written (the claim could not take its locks in time) | `503 OWNER_BUSY` with `Retry-After`; retry as it is | | A claim the rules below refuse | `4xx` with the rule's code; nothing changes | What moves, in this fixed order (a host adds its own tables with `registerClaimParticipant`, see below): 1. **Folders.** A folder whose name the account already uses (compared case-insensitively, like `createFolder`) is merged into the account's; one whose id the account already uses for another name moves under a fresh id; the rest move as they are, after the account's own. Filing follows. 2. **Courses** (`stage_meta`), including deleted ones. 3. **Materials.** 4. **Agent sessions** and their session-list history. 5. **User skills.** A handle the account already uses is renamed to the first handle neither side holds (`my-notes-2`, `my-notes-3`, ...). 6. **Runtime sessions** (the learner key). They are re-keyed as stored, so a session written by a newer version does not stop the claim. 7. **Asset entries** (the per-owner partition), so a claimed course keeps rendering its media for every viewer. 8. **Legacy import bindings** (temporary, with the one-way legacy browser import): a browser whose pre-server data the anonymous owner held is then the account's, so the import continues for it. Quotas are not applied to what moves: the account keeps everything, and if it is now above its asset, material, skill or folder limit it cannot add more until it is back under. The claim is recorded in `owner_merges`. Rules: only an anonymous owner can be claimed, and only by a non-anonymous one; claiming the same pair again succeeds and does nothing; an anonymous owner already claimed by one account cannot be claimed by another; and there are no chains (a retired account cannot claim, and an owner that absorbed others cannot be claimed), so every retired id forwards in one step. After a claim the anonymous id is **retired**. A request that still presents it writes nothing under it: - Creates through `/api/persistence` (documents, folders, assets, runtime sessions), the folder, course, material and skill-upload routes, and every other write through `/api/persistence` answer `403 OWNER_RETIRED`. - A write by id to a row that moved (deleting a skill, posting to an agent session) answers `403 OWNER_RETIRED` too. - Every such response carries the `Set-Cookie` values that drop the retired anonymous cookie (and those of any method that declares `issuesAnonymousOwners`), so the browser gets a fresh anonymous owner on its next request. The library of the retired id reads as empty. Work that started before the claim and runs on without a request (an agent run's course edits, generated media and new skills) follows the id to the account instead, so a course that was still generating when its author signed in lands in their account. An agent session created by a request that races the claim is written for the account, as if it had been created just before the claim. Every write that creates or changes an owner's rows takes a per-owner PostgreSQL advisory lock (the identity lock) in shared mode as its transaction's first statement. A claim takes it in exclusive mode for both owners before touching a row. A fenced write racing a claim therefore either commits first and is moved, or waits and is refused; the tests show no deadlock and nothing left under the retired id for these writes. Waits are bounded: - A claim waits up to `OWNER_CLAIM_LOCK_WAIT_MS` (default 5000) for the two identity locks. While it waits, PostgreSQL queues new writers of both owners behind it, so this is kept short. - A write waits up to `OWNER_WRITE_LOCK_WAIT_MS` (default 30000) for its owner's lock. - An upload holds the lock while its bytes are written, so a claim waits for in-flight uploads, up to its bound. - Running out of time is `503 OWNER_BUSY` with `Retry-After`, and nothing is written. The asset collector does not take the identity lock; a collector pass racing a claim over the same entries can make PostgreSQL abort one of them, and a claim aborted that way also answers `OWNER_BUSY`. A host registers participants for its own owner-keyed tables from `instrumentation.ts`: ```ts const { registerClaimParticipant } = await import('@/lib/persistence/owner-claims'); registerClaimParticipant({ name: 'course-notes', order: 1000, // after core's 100-800; see lib/persistence/owner-claims.ts rekey: async (tx, fromOwnerId, toOwnerId) => ( await tx.query('UPDATE course_notes SET owner_id = $2 WHERE owner_id = $1 RETURNING 1', [ fromOwnerId, toOwnerId, ]) ).rows.length, }); ``` A participant runs inside the claim's transaction; if it throws, nothing any participant did is kept. `claimOwner(from, to)` and `claimPendingOwner(principal)` run a claim from host code. A claim's source must be described as anonymous (`describeStoredOwner`, through `principalFromStoredOwner`). Forwarding a retired id is core's own (`owner_merges`); there is no host hook for it. `owner_merges` records claims of anonymous owners only, because the write fences enforce retirement only for ids described as anonymous: `describeStoredOwner` must keep describing an id the same way, and a row retiring any other owner is refused when read. A host that merges two signed-in accounts moves the rows itself (its own participants) and refuses the merged-away account in its auth method. `OWNER_WRITE_LOCK_WAIT_MS` and `OWNER_CLAIM_LOCK_WAIT_MS` are checked at startup. ##### Host extension hooks A host can add product behavior at four points without forking a route. They are registered like the owner auth methods: once, from `instrumentation.ts` `register()`, and sealed on first use (a second call, or a call after the server started using them, throws). A plain object or a class instance both work; each hook is read once at registration and bound to the object passed. A misspelled hook is refused rather than silently never called: a plain object may carry only the known keys, and a class instance may carry no public method other than a hook, so keep a host class's helpers private (`#helper`) or register a plain object. With nothing registered, every point behaves exactly as described above. ```ts // instrumentation.ts, inside register(), next to configureOwnerAuthentication const { configurePersistenceHooks, configureAssetByteStore } = await import('@/lib/server/persistence-hooks'); configurePersistenceHooks({ name: 'my-host', // Course creation, inside the transaction that creates the course. async authorizeCreate(tx, actor) { const retired = await tx.query('SELECT 1 FROM host_retired_owners WHERE owner_id = $1', [ actor.ownerId, ]); return retired.rows.length ? { allow: false, message: 'account retired' } : { allow: true }; }, async onCreate(tx, actor, stageId) { await tx.query('INSERT INTO host_library (owner_id, stage_id) VALUES ($1, $2)', [ actor.ownerId, stageId, ]); }, // What GET /api/stages lists. library: { name: 'owned-and-saved', async list({ principal, queryable, ownedStageIds }) { const saved = await queryable.query<{ stage_id: string }>( 'SELECT stage_id FROM host_saved_courses WHERE owner_id = $1', [principal.ownerId], ); return [...(await ownedStageIds()), ...saved.rows.map((row) => row.stage_id)]; }, }, // Upload admission (req.operation: 'create' | 'replace'), before any byte // is stored or counted. async beforeAssetAllocate(principal, req) { const exhausted = await uploadBudgetExhausted(principal.ownerId, req.headers); // host code return exhausted ? Response.json({ error: { code: 'UPLOAD_BUDGET' } }, { status: 429 }) : undefined; }, }); // Where asset bytes live, for the request path and the collector alike. configureAssetByteStore({ name: 'my-object-store', create: () => createMyObjectByteStore(), // host code: an AssetByteStore signsReadUrls: true, // required for ASSET_BYTE_EGRESS=redirect }); ``` | Hook | Called | Contract | |---|---|---| | `authorizeCreate(tx, actor, stageId)` | Once per created course, inside its transaction, after the course rows are written | Resolve `{ allow: true }` or `{ allow: false, message? }`. A refusal rolls everything back and answers `403 CREATE_REFUSED` (on `/api/persistence` and `POST /api/stages`). | | `onCreate(tx, actor, stageId)` | Right after `authorizeCreate` allowed it, same transaction | Statements on `tx` commit with the course; a throw rolls the whole create back. | | `library.list({ principal, queryable, ownedStageIds })` | `GET /api/stages` | Resolve at most 5000 stage ids (more is a `500`). The route lists them in that order as the usual items, without duplicates, and drops every id the read path would refuse (deleted, unclaimed, or not addressable at all, such as `..` or one containing NUL). `folderId` is shown only on the principal's own courses. | | `beforeAssetAllocate(principal, req)` | Every upload over `/api/persistence/assets`: `POST /assets` (`req.operation: 'create'`) and `PUT /assets/{id}/content` (`'replace'`, with the decoded `req.assetId`), after the owner is resolved and before the body is read | Resolve `undefined` to proceed or a `Response` to answer with it; nothing is stored and no quota is counted. Decide on `operation` / `assetId`, which are the storage handler's own routing; `url` is the request as received. Media an agent run generates on the server is not an HTTP upload and does not pass this hook; the per-owner quota still bounds it. | | `configureAssetByteStore({ name, create, signsReadUrls? })` | Lazily, by the persistence route and by the asset collector | `create({ queryable })` returns an `AssetByteStore` (`@openmaic/storage`) that keeps bytes outside the registry database and declares it with `writesOutsideRegistryDatabase: true`. The flag is trusted: a store that sets it but writes through the registry database can deadlock. Replaces the `ASSET_S3_BUCKET` switch; setting both stops the server. | **What counts as a create.** A course is created by the transaction that records its owner for the first time: the first save of a new stage id, from a request or from an agent run. Saving, editing or renaming a course the owner already holds is an update and calls neither create hook; so is a create that loses a race to a concurrent create of the same id by the same owner. `actor.ownerId` is always the owner. `actor.source` says who is writing: `'request'` carries `actor.principal`, the principal the request resolved to; `'background'` is an agent run writing on the owner's behalf after its request ended, and has no principal because a run records only the owner id. A background write is not a trusted caller: the owner started it, so apply the same limits to it. On a background write a refusal reaches the agent as a fixed "refused by this deployment" result; `message` is only sent to request clients. Courses written before ownership rows existed are adopted by a one-time backfill when the server starts. That runs outside any request, so no create hook runs for them; the server logs how many it adopted. **What a library may list.** Course reads are capability-by-id, so listing an id hands it out: a provider lists another owner's course only when the principal is entitled to know its id (it saved it, it was shared with it). The route guarantees the rest: it never lists a course that `GET /api/stages/{id}` would not serve. **Redirect egress.** The built-in layers are unchanged (S3 signs; the PostgreSQL column falls back to direct bytes). A configured store that does not declare `signsReadUrls: true` stops the server at boot under `ASSET_BYTE_EGRESS=redirect`, instead of being discovered by the first read. One that declares it but turns out to have no `signReadUrl` is logged and served with direct bytes, like the built-in fallback; the collector never signs. ### Optional: Agent workbench and runtime The Pro workbench is a usable course-building surface entered from the home page. Its collapsible navigation rail, conversation pane, and tabbed classroom pane share `/api/agent/*` control-plane routes and an in-process session runner. It is off by default. Enable its build-time entry point and the server runtime; it uses the same PostgreSQL connection as the rest of the app: ```env NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true OPENMAIC_AGENT_RUNTIME_ENABLED=true DATABASE_URL=postgres://openmaic:openmaic-dev@postgres:5432/openmaic ``` The agent runs on the `agent` slot of `openmaic.yml` (or the model settings), which follows the default chat model unless it has its own assignment and needs a model with tool calling: ```yaml providers: openai: preset: openai apiKey: ${OPENAI_API_KEY} slots: llm: openai:gpt-5.5 agent: model: openai:gpt-5.5 api: openai-completions # or openai-responses ``` While the flag is off, the `/api/agent/sessions*` and `/api/agent/owner-events` routes answer `404`; the course library and folder routes do not depend on the flag (see [Server-backed persistence](#server-backed-persistence-postgresql)). The `agent` slot's `api` is `openai-completions` (the default) or `openai-responses`, and it must not set `thinking.effort` (the configuration is refused at startup or when saved); it may set `thinking.mode`. An effort the agent inherits from `llm` is dropped for the agent. A deployment still configured only through `DEFAULT_MODEL` has the agent turned off until the `agent` slot is assigned. Runner cadence (scan interval, heartbeat, lease TTL, concurrency, attempts) and the reserved compaction knobs are listed in `.env.example`. ### Optional: MP4 Video Export (Render Service) The "Export Video" menu builds a self-contained [Hyperframes](https://www.npmjs.com/package/@hyperframes/producer) project entirely in the browser. Turning that into an MP4 needs Chromium + FFmpeg on Node 22, so it runs in an isolated `render-service` container rather than the app. It's opt-in. Start it with the `video-export` compose profile: ```bash docker compose --profile video-export up --build ``` The app auto-detects the service via `RENDER_SERVICE_URL` (preset in `docker-compose.yml`) and enables one-click MP4 rendering. Without the profile — or when `RENDER_SERVICE_URL` is unset — export degrades to downloading the project ZIP for local CLI rendering. See [`render-service/README.md`](render-service/README.md) for standalone setup and tuning (`RENDER_MAX_CONCURRENCY`, etc.). ### Optional: MinerU (Advanced Document Parsing) [MinerU](https://github.com/opendatalab/MinerU) provides enhanced parsing for complex tables, formulas, and OCR. You can use the [MinerU official API](https://mineru.net/) or [self-host your own instance](https://opendatalab.github.io/MinerU/quick_start/docker_deployment/). Declare it in `openmaic.yml` and assign the `document` slot to it: `mineru-cloud` for the official API, or `mineru` with the `baseUrl` of your own instance. ```yaml providers: mineru: preset: mineru-cloud apiKey: ${PDF_MINERU_CLOUD_API_KEY} slots: document: mineru ``` Without `openmaic.yml`, the legacy variables `PDF_MINERU_CLOUD_API_KEY` or `PDF_MINERU_BASE_URL` in `.env.local` still work. ### Optional: VoxCPM2 (Self-Hosted TTS with Voice Cloning) [VoxCPM2](https://github.com/OpenBMB/VoxCPM) is an open-source TTS model from OpenBMB with voice cloning. OpenMAIC ships an adapter; run VoxCPM on your own hardware and OpenMAIC will talk to it. **1. Run a VoxCPM backend.** Three deployment styles, all behind the same OpenMAIC adapter. You pick which one with `options.backend` in `openmaic.yml` (step 2). | Backend | Endpoint | When to use | | --- | --- | --- | | **vLLM-Omni** | `/v1/audio/speech` | OpenAI-compatible speech endpoint, ideal for GPU servers | | **Python API** | `/tts/upload` | Official VoxCPM Python runtime via FastAPI | | **Nano-vLLM** | `/generate` | Lightweight Nano-vLLM FastAPI deployment | See the [VoxCPM repo](https://github.com/OpenBMB/VoxCPM) for backend setup. **2. Point OpenMAIC at it.** VoxCPM2 runs on your own network, so the deployment configures it in `openmaic.yml` (no API key required); workspaces cannot add it in **Settings → Model Services**: ```yaml providers: voxcpm: preset: voxcpm-tts baseUrl: http://localhost:8000/v1 options: backend: vllm-omni # vllm-omni (default) | python-api | nano-vllm slots: tts: voxcpm ``` Voice registration works only on the `vllm-omni` backend; `python-api` and `nano-vllm` send the voice prompt with each request. Without `openmaic.yml`, the legacy `TTS_VOXCPM_BASE_URL=http://localhost:8000/v1` sets the endpoint but cannot choose a backend. **3. Manage voices.** With VoxCPM2 assigned to the `tts` slot, open **Settings → Model Services → Text-to-Speech → VoxCPM2** (the voice manager appears only when `tts` resolves to a `voxcpm-tts` provider). Three voice modes: - **Auto Voice** (default): OpenMAIC generates a voice prompt from each agent's persona at synthesis time. No setup required. - **Prompt voice**: describe the voice in natural language, e.g. *"warm female teacher voice, calm and encouraging, mid-pitch"*. - **Clone voice**: upload a short reference audio clip or record one in the browser. The clip is stored in this browser (IndexedDB) and sent to your VoxCPM backend on each synthesis. --- ## ✨ Features ### Agent Workbench and Pro Mode (v1.0.0) The workbench adds a conversational course-building agent to OpenMAIC. Its durable sessions can be resumed after a worker restart, accept follow-up instructions while running, and stream a replayable event history to the chat surface. Open it from the Pro control on the home page. The workspace combines a transient, collapsible folders/conversations rail with a chat pane and a classroom pane whose open courses stay in tabs. Workspace controls return to classic mode, and either entry remains gated by the public workbench flag plus the configured server runtime. The agent works through explicit, validated tools rather than editing opaque blobs: | Area | Capabilities | | --- | --- | | **Plan and organize** | Plan multi-lesson curricula; create courses and folders; rename and move courses | | **Build and edit** | Read/search the stage DSL; atomically patch one scene; generate, duplicate, insert, delete, and reorder pages; edit narration and deck structure | | **Use materials** | Upload files; extract documents, audio, and video; search extracted text; fetch trusted web URLs; reuse material media | | **Create media** | Generate images and videos through configured server providers; generate narration audio | | **Import and inspect** | Import `.pptx` slides with their layout preserved; render scene previews for visual inspection when available | | **Configure the classroom** | List available voices, set the agent roster, and clone/register a voice when a pluggable registration adapter is configured | Twenty-four built-in skills cover curriculum planning, deep research, interactive, lecture, workshop, vocational, and other teaching styles, slide/stage craft, PPTX import, editing, and style reuse. User-authored skills are stored per owner and can be created, read, and patched through the same runtime. The server-backed workbench also exposes owner-scoped folder routes and a per-viewer stage metadata sidecar for ownership, publication, and generation-complete state. A stage ID acts as the capability for reading a non-deleted course, but stage mutations remain restricted to its owner. The material upload contract stores supported source bytes before lease-fenced document or media extraction records derived text and images; media extraction can select AliDocMind or the optional local ffmpeg/ffprobe provider. Under the hood, agent sessions are database-backed with leases, heartbeats, crash resume, cancellation, and follow-up steering, and database-maintained revision counters keep per-stage and per-scene freshness monotonic so the workbench refetches only the scenes that changed. Server routes resolve LLM, media, ASR/TTS, and search configuration provider-neutrally: credentials never reach the browser, uniform `__ENABLED=false` switches can force off any served capability, startup validation warns about bad model configuration, and unresolved model routes fail loudly instead of guessing a vendor. ### Pluggable Storage OpenMAIC stores course documents, learner runtime records and assets on the server, in PostgreSQL. The `@openmaic/storage` package defines swappable stores for those primitives — PostgreSQL-backed documents, learner runtime, assets, durable agent sessions, session materials, and user skills, plus browser implementations for embedders — and HTTP clients connect the browser to the embedded persistence endpoint, while the server asset layer can keep bytes in PostgreSQL or S3. Device-scoped KV values (settings, playback position) stay in the browser. ### Deep Interactive Mode (New!) **Passive listening? ❌ Hands-on exploration! ✅** As Einstein said: *"Play is the highest form of research."* While **Standard Mode** focuses on quickly generating classroom content, **Deep Interactive Mode** goes further — creating interactive, explorable, hands-on learning experiences. Students don't just watch knowledge; they adjust experiments, observe simulations, and actively explore how things work. #### Five Types of Interactive UI

**🌐 3D Visualization** Three-dimensional visual representations that make abstract structures more intuitive.	**⚙️ Simulation** Process simulations and experimental environments for observing dynamic changes and outcomes.
**🎮 Game** Knowledge-based mini-games that reinforce understanding and memory through interactive challenges.	**🧭 Mind Map** Structured knowledge organization to help learners build an overall conceptual framework.
**💻 Online Programming** In-browser coding and instant execution for learning by writing, testing, and iterating.

#### AI Teacher Guidance The AI teacher can actively operate the UI to guide students — highlighting key areas, setting conditions, providing hints, and directing attention at the right moments. #### Available on Any Device All generated interactive UI is fully responsive — desktop, tablet, or mobile.

**Desktop**	**Mobile**
**iPad**

#### Need a More Complete and Professional UI Generation Experience? If you are looking for a version with richer functionality, stronger interactivity, and deeper optimization for high-quality educational UI production, please visit [MAIC-UI](https://github.com/THU-MAIC/MAIC-UI). ### Lesson Generation Describe what you want to learn or attach reference materials. PDF, Word, PowerPoint, spreadsheet, text, image, audio, and video inputs can enter the material pipeline; configured extractors turn supported sources into content for generation. OpenMAIC's classic two-stage pipeline handles the rest: | Stage | What Happens | |-------|-------------| | **Outline** | AI analyzes your input and generates a structured lesson outline | | **Scenes** | Each outline item becomes a rich scene — slides, quizzes, interactive modules, or PBL activities | ### Classroom Components

**🎓 Slides** AI teachers deliver lectures with voice narration, spotlight effects, and laser pointer animations — just like a real classroom.	**🧪 Quiz** Interactive quizzes (single / multiple choice, short answer) with real-time AI grading and feedback.
**🔬 Interactive Simulation** HTML-based interactive experiments for visual, hands-on learning — physics simulators, flowcharts, and more.	**🏗️ Project-Based Learning (PBL)** Choose a role and collaborate with AI agents on structured projects with milestones and deliverables.

### Multi-Agent Interaction

- **Classroom Discussion** — Agents proactively initiate discussions; you can jump in anytime or get called on - **Roundtable Debate** — Multiple agents with different personas discuss a topic, with whiteboard illustrations - **Q&A Mode** — Ask questions freely; the AI teacher responds with slides, diagrams, or whiteboard drawings - **Whiteboard** — AI agents draw on a shared whiteboard in real time — solving equations step by step, sketching flowcharts, or illustrating concepts visually.

### Agent Workbench Integration

The OpenMAIC skill package (`skills/openmaic/`) uses the standard SKILL.md format and can be loaded by various agent workbenches — besides OpenClaw, this includes **Codex**, **DeepSeek**, **WorkBuddy**, and others. It is a guided SOP covering the live demo, local setup, classroom generation, and secondary development on top of the `@openmaic/*` SDK. [OpenClaw](https://github.com/openclaw/openclaw) is a personal AI assistant that connects to the messaging platforms you already use (Feishu, Slack, Discord, Telegram, WhatsApp, etc.). With this integration, you can **generate and view interactive classrooms directly from your chat app** without ever touching a terminal.

Just tell your agent assistant what you want to learn — it handles everything else: - **Hosted mode** — Grab an access code from [open.maic.chat](https://open.maic.chat/), save it in your config, and generate classrooms instantly — no local setup required - **Self-hosted mode** — Clone, install dependencies, configure API keys, and start the server — the skill guides you through each step - **Track progress** — Poll the async generation job and send you the link when ready - **Secondary development** — Guide you through building on top of OpenMAIC: create your own app with the `@openmaic/*` SDK (see the extend docs inside the skill) Every step asks for your confirmation first. No black-box automation.

**Available on ClawHub** — Install with one command: ```bash clawhub install openmaic ``` Or, in other agent workbenches such as Codex, DeepSeek, or WorkBuddy, import the `skills/openmaic/` folder from the repo (or its zipped archive) into the workbench to use it:

Configuration & details

| Phase | What the skill does | |------|-------------| | **Clone** | Detect an existing checkout or ask before cloning/installing | | **Startup** | Choose between `pnpm dev`, `pnpm build && pnpm start`, or Docker | | **Provider Keys** | Recommend a provider path; you edit `.env.local` yourself | | **Generation** | Submit an async generation job and poll until it completes | Optional config in `~/.openclaw/openclaw.json`: ```jsonc { "skills": { "entries": { "openmaic": { "config": { // Hosted mode: paste your access code from open.maic.chat "accessCode": "sk-xxx", // Self-hosted mode: local repo path and URL "repoDir": "/path/to/OpenMAIC", "url": "http://localhost:3000" } } } } } ```

### Export | Format | Description | |--------|-------------| | **PowerPoint (.pptx)** | Fully editable slides with images, charts, and LaTeX formulas | | **Interactive HTML** | Self-contained web pages with interactive simulations | | **Classroom ZIP** | Full classroom export (course structure + media) for backup or sharing | Importing a classroom ZIP stores its embedded audio, images, video, and posters in the server asset pool before saving the course, so other browsers resolve those assets without the importing browser's cache. A ZIP is also a way to move a course between deployments: export it from one and import it on the other. **Offline / intranet classrooms:** When you export a classroom (`.maic.zip`) or a Resource Pack, OpenMAIC inlines the external assets referenced by interactive scenes (KaTeX, Three.js incl. `three/addons`, Tailwind CDN, Google Fonts, images) into the exported HTML as `data:` URIs. The exported course then plays fully offline after import into an air-gapped/intranet instance — no public CDN is contacted at playback time. Assets that can't be fetched at export time (e.g. CORS-restricted image hosts) are reported and left as URLs. Classrooms exported *before* this feature still reference CDNs and must be re-exported to gain offline support. ### And More - **Text-to-Speech** — Multiple voice providers with customizable voices - **Speech Recognition** — Talk to your AI teacher using your microphone - **Web Search** — Agents search the web for up-to-date information during class - **Provider controls** — Server-side capability discovery, model resolution, force-off switches, and fail-loud routing keep deployments explicit - **Course freshness** — Database-triggered per-scene revision counters, freshness events, and targeted scene fetches keep workbench views synchronized - **i18n** — Interface supports 12 locales across 11 languages: Simplified Chinese, Traditional Chinese, English, Japanese, Korean, Russian, Arabic, Portuguese (Brazil), Spanish (Mexico), French, Vietnamese, and German - **Dark Mode** — Easy on the eyes for late-night study sessions --- ## 💡 Use Cases

> *"Teach me Python from scratch in 30 min"*	> *"How to play the board game Avalon"*
> *"Analyze the stock prices of Zhipu and MiniMax"*	> *"Break down the latest DeepSeek paper"*

--- ## 🤝 Contributing We welcome contributions from the community! Whether it's bug reports, feature ideas, or pull requests — every bit helps. ### Project Structure ``` OpenMAIC/ ├── app/ # Next.js App Router │ ├── api/ # Generation, media, persistence, and agent APIs │ │ ├── agent/ # Durable session, event, material, and skill control plane │ │ ├── stages/ # Owner-scoped course reads, writes, manifests, and scene fetches │ │ ├── generate/ # Scene generation pipeline (outlines, content, images, TTS …) │ │ ├── generate-classroom/ # Async classroom job submission + polling │ │ ├── chat/ # Multi-agent discussion (SSE streaming) │ │ ├── pbl/ # Project-Based Learning endpoints │ │ ├── persistence/ # Embedded persistence service (Runtime/Document Store HTTP contracts) │ │ ├── export-video/ # MP4 video export (backs onto render-service) │ │ └── ... # quiz-grade, parse-pdf, web-search, transcription, etc. │ ├── classroom/[id]/ # Classroom playback page │ └── page.tsx # Home page (generation input) │ ├── lib/ # Core business logic │ ├── generation/ # Two-stage lesson generation pipeline │ ├── orchestration/ # LangGraph multi-agent orchestration (director graph) │ ├── playback/ # Playback state machine (idle → playing → live) │ ├── action/ # Action execution engine (speech, whiteboard, effects) │ ├── ai/ # LLM provider abstraction │ ├── api/ # Stage API facade (slide/canvas/scene manipulation) │ ├── store/ # Zustand state stores │ ├── types/ # Centralized TypeScript type definitions │ ├── audio/ # TTS & ASR providers │ ├── media/ # Image & video generation providers │ ├── persistence/ # Browser/server persistence wiring and PostgreSQL provider │ ├── server/agent-runtime/ # Durable runner, skills, materials, and course-building tools │ ├── export/ # PPTX & HTML export │ ├── hooks/ # React custom hooks (55+) │ ├── i18n/ # Internationalization (zh-CN, zh-TW, en-US, ja-JP, ko-KR, ru-RU, ar-SA, pt-BR, es-MX, fr-FR, vi-VN, de-DE) │ └── ... # prosemirror, storage, pdf, web-search, utils │ ├── components/ # React UI components │ ├── slide-renderer/ # Canvas-based slide editor & renderer │ │ ├── Editor/Canvas/ # Interactive editing canvas │ │ └── components/element/ # Element renderers (text, image, shape, table, chart …) │ ├── scene-renderers/ # Quiz, Interactive, PBL scene renderers │ ├── generation/ # Lesson generation toolbar & progress │ ├── workbench/ # Pro workbench conversation and course-reference UI │ ├── chat/ # Chat area & session management │ ├── settings/ # Settings panel (providers, TTS, ASR, media …) │ ├── whiteboard/ # SVG-based whiteboard drawing │ ├── agent/ # Agent avatar, config, info bar │ ├── ui/ # Base UI primitives (shadcn/ui + Radix) │ └── ... # audio, roundtable, stage, ai-elements │ ├── packages/ # Workspace packages │ ├── @openmaic/dsl/ # Versioned course/slide data contract and validators │ ├── @openmaic/renderer/ # React renderer for the slide DSL │ ├── @openmaic/editor/ # Composable slide editing core and React surface │ ├── @openmaic/importer/ # PPTX → OpenMAIC slide importer │ ├── @openmaic/generation/ # Generation contracts, pipeline, and prompt assets │ ├── @openmaic/storage/ # Browser, HTTP, PostgreSQL, and S3 persistence primitives │ ├── pptxgenjs/ # Customized PowerPoint generation │ └── mathml2omml/ # MathML → Office Math conversion │ ├── render-service/ # MP4 video export render service (Chromium + FFmpeg, standalone container) │ ├── skills/ # OpenClaw / ClawHub skills │ └── openmaic/ # Guided OpenMAIC setup & generation SOP │ ├── SKILL.md # Thin router with confirmation rules │ └── references/ # On-demand SOP sections (generation, deployment, extending, …) │ ├── configs/ # Shared constants (shapes, fonts, hotkeys, themes …) └── public/ # Static assets (logos, avatars) ``` ### Key Architecture - **Generation Pipeline** (`@openmaic/generation`) — Two-stage: outline generation → scene content generation - **Agent Runtime** (`lib/server/agent-runtime/`) — PostgreSQL-backed sessions with leased execution, resume/steer semantics, skills, materials, and validated course tools - **Persistence Layer** (`@openmaic/storage`) — Swappable document, runtime, KV, asset, agent-session, material, and user-skill stores - **Multi-Agent Orchestration** (`lib/orchestration/`) — LangGraph state machine managing agent turns and discussions - **Playback Engine** (`lib/playback/`) — State machine driving classroom playback and live interaction - **Action Engine** (`lib/action/`) — Executes 21 action types (speech, whiteboard draw/text/shape/chart, spotlight, laser …) - **Storage Layer** (`@openmaic/storage`) — Runtime/Document/asset storage abstraction with a Postgres reference implementation; its HTTP contracts let you plug in any external storage service ### How to Contribute 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request --- ## 💼 Partnerships This project is licensed under the MIT License, so commercial use is permitted free of charge. For partnership or collaboration inquiries, please contact: **thu_maic@mail.tsinghua.edu.cn** --- ## 📝 Citation If you find OpenMAIC useful in your research, please consider citing: ```bibtex @Article{JCST-2509-16000, title = {From MOOC to MAIC: Reimagine Online Teaching and Learning through LLM-driven Agents}, journal = {Journal of Computer Science and Technology}, volume = {}, number = {}, pages = {}, year = {2026}, issn = {1000-9000(Print) /1860-4749(Online)}, doi = {10.1007/s11390-025-6000-0}, url = {https://jcst.ict.ac.cn/en/article/doi/10.1007/s11390-025-6000-0}, author = {Ji-Fan Yu and Daniel Zhang-Li and Zhe-Yuan Zhang and Yu-Cheng Wang and Hao-Xuan Li and Joy Jia Yin Lim and Zhan-Xin Hao and Shang-Qing Tu and Lu Zhang and Xu-Sheng Dai and Jian-Xiao Jiang and Shen Yang and Fei Qin and Ze-Kun Li and Xin Cong and Bin Xu and Lei Hou and Man-Li Li and Juan-Zi Li and Hui-Qin Liu and Yu Zhang and Zhi-Yuan Liu and Mao-Song Sun} } ``` --- ## ⭐ Star History [](https://star-history.com/#THU-MAIC/OpenMAIC&Date) --- ## 📄 License This project is licensed under the [MIT License](LICENSE). ### Third-Party Components The repository bundles workspace packages that are **not** covered by the root MIT license and keep their own terms: - `packages/mathml2omml` — [LGPL-3.0-or-later](packages/mathml2omml/LICENSE) - `packages/pptxgenjs` — [MIT](packages/pptxgenjs/package.json) (third-party) When redistributing the repository as a whole, the terms of each bundled package above apply to that package's files.