THU-MAIC/OpenMAICPublic

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

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

One prompt in, a whole course out — and now you can steer. Released August 27, 2026, OpenMAIC v1.0.0 adds a Pro workbench alongside the classic one-click generator: chat with an agent that plans your curriculum, builds and revises every page, and works straight from your materials.

• 🤖 Agent workbench — a chat-first workspace that plans, builds, and revises whole courses
• 💾 Durable sessions — server-backed runs survive restarts; cancel, resume, and steer anytime
• 📎 Session materials — upload documents, audio, and video, or pull from web search; the agent builds from them
• 🧰 Course tools + 24 built-in skills — slides, quizzes, interactives, PBL, images, video, voices, .pptx import
• 🔌 Neutral by design — bring your own models, media, search providers, and storage backend

Take the full tour in Features, then set it up with Agent workbench and runtime.

• 2026-09-28 — v1.1.2 released! Security release. When a provider is not configured on the server, the routes that accept a caller-supplied base URL (PDF parsing and connectivity checks, the Azure voice list, model listing, image and video providers, LLM calls) now connect only to addresses that passed validation and refuse redirects (GHSA-g87c-cm4q-cw5x); classroom media downloads use the same transport. Read the Behavior Changes section of the changelog before upgrading. See changelog.
• 2026-09-27 — v1.1.1 released! Security release. MinerU Cloud document parsing now holds the presigned upload and result URLs returned by the provider to the same strict public-address policy, validates every redirect hop, and bounds what it reads and decompresses (GHSA-cpjc-vgjh-c5jp). See changelog.
• 2026-09-24 — v1.1.0 released! Classroom chat now runs on an agent loop: reference a slide element, an interactive component or a whiteboard drawing from the playback bar and ask about it, and the teacher can read the lesson, check an experiment's live state and search the web before answering. Settings are rebuilt around the course workflow with a model choice per generation step, plus first-class Token Plan connections. Read the Behavior Changes section before upgrading — Pi is the default chat runtime. See changelog.
• 2026-09-15 — v1.0.3 released! Security release. Access-code verification tokens now expire and verification is rate-limited (GHSA-qpmr-534w-hhpg); the render service applies a network policy to the untrusted HTML it renders (GHSA-vqq3-22q7-289w); audio provider requests validate redirects and pin their connections (GHSA-9p8q-rcmg-pmjw); and Next.js is upgraded to patch a critical RCE. See changelog.
• 2026-09-14 — v1.0.2 released! Security release. Closes a cloud-metadata SSRF gap, a DNS-rebinding bypass on media proxying and a classroom overwrite, and tightens two request paths. Read the Breaking Changes section before upgrading. See changelog.
• 2026-09-06 — v1.0.1 released! Security and stability release; everyone on 1.0.0 should upgrade, as it tightens two defaults. See changelog.
• 2026-08-27 — OpenMAIC v1.0.0: an agent workbench, durable course-building sessions, reusable skills, session materials, provider-neutral server capabilities, and a pluggable persistence stack.
• 2026-08-14 — v0.3.2 released! Video export hardening (deterministic Quiz/PBL covers, fidelity polish, interactive HTML capture, CPU resource profiles); server-backed persistence completed (full document cutover, one-command Postgres stack, incremental saves) plus the asset registry; the @openmaic/generation package; four new locales; Amazon Bedrock, Atlas Cloud, and Claude search providers; FunASR ASR. See changelog.
• 2026-07-21 — v0.3.1 released! One-click MP4 video export; server-backed runtime storage with a Postgres reference server; direct slide manipulation in the editor (drag, resize, rotate, multi-select); smarter "Edit with AI" (validated JSON Patch edits, multi-session history); expanded Document Parsing (multi-format upload, audio/video extraction, AliDocMind, MinerU); new providers (Azure OpenAI, SearXNG, ComfyUI) and the GPT-5.6 model family; action-level playback navigation; SSRF hardening. See changelog.
• 2026-06-28 — v0.3.0 released! Project-Based Learning (PBL) v2 with classroom UI; "Edit with AI" Pro-mode editor agent; the @openmaic/* SDK family (DSL/renderer/importer) published to npm; optional per-stage model routing; new models (GLM-5.2, Kimi K2.7 Code, Qwen3.7 Plus/Max); a vocational-learning task engine; Korean (ko-KR) locale; and relicensing from AGPL-3.0 to MIT. See changelog.
• 2026-06-02 — v0.2.2 released! MAIC Editor (v0) Pro Mode for editing generated slides; editable outline before generation; offline-ready classroom export; new search providers (Brave/Baidu/Bocha/MiniMax) and Azure STT; new models (Claude Opus 4.8, MiniMax M3, Gemini 3.5 Flash); Traditional Chinese (zh-TW) and Brazilian Portuguese (pt-BR) locales. See changelog.
• 2026-04-26 — v0.2.1 released! Integrated VoxCPM2 TTS with voice cloning and on-the-fly auto-generated voices; added per-model thinking config; added end-of-course completion page with persistent quiz state; added latest released models including DeepSeek-V4 / GPT-5.5 / GPT-Image-2 / Xiaomi MiMo / Hy3. See changelog.
• 2026-04-20 — v0.2.0 released! Deep Interactive Mode — 3D visualization, simulations, games, mind maps, and online programming for hands-on learning. See features for details.
• 2026-04-14 — v0.1.1 released! Automatic language inference, ACCESS_CODE authentication, classroom ZIP export/import, custom TTS/ASR providers, Ollama support, and more. See changelog.
• 2026-03-26 — v0.1.0 released! Discussion TTS, immersive mode, keyboard shortcuts, whiteboard enhancements, new providers, and more. See changelog.

OpenMAIC (Open Multi-Agent Interactive Classroom) is an open-source AI platform that turns any topic or document into a rich, interactive classroom experience. Powered by multi-agent orchestration, it generates slides, quizzes, interactive simulations, and project-based learning activities — all delivered by AI teachers and AI classmates who can speak, draw on a whiteboard, and engage in real-time discussions with you. The built-in OpenMAIC Skill works with OpenClaw as well as agent workbenches such as Codex, DeepSeek, and WorkBuddy, so you can generate classrooms from messaging apps like Feishu, Slack, or Telegram, or right inside your IDE.

• One-click lesson generation — Describe a topic or attach your materials; the AI builds a full lesson in minutes
• Multi-agent classroom — AI teachers and peers lecture, discuss, and interact with you in real time
• Rich scene types — Slides, quizzes, interactive HTML simulations, and project-based learning (PBL)
• Whiteboard & TTS — Agents draw diagrams, write formulas, and explain out loud
• Export anywhere — Download editable .pptx slides or interactive .html pages
• Agent workbench integration — The OpenMAIC Skill supports OpenClaw, Codex, DeepSeek, WorkBuddy, and more — generate classrooms from Feishu, Slack, Telegram, 20+ messaging apps, or your IDE

• Node.js >= 22.19
• pnpm >= 10
• PostgreSQL 16 — courses are stored on the server. For local development pnpm db:up starts one in Docker for you.

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install

cp .env.example .env.local

Fill in at least one LLM provider key:

OPENAI_API_KEY=sk-...
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_BASE_URL=https://YOUR-RESOURCE.openai.azure.com/openai
AZURE_OPENAI_MODELS=YOUR-DEPLOYMENT-NAME
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
GROK_API_KEY=xai-...
OPENROUTER_API_KEY=sk-or-...
TENCENT_API_KEY=sk-...
XIAOMI_API_KEY=...
# Or configure Amazon Bedrock with AWS credentials and BEDROCK_REGION.

You can also configure providers via server-providers.yml:

providers:
  openai:
    apiKey: sk-...
  azure:
    apiKey: ...
    baseUrl: https://YOUR-RESOURCE.openai.azure.com/openai
    models:
      - YOUR-DEPLOYMENT-NAME
  anthropic:
    apiKey: sk-ant-...
  bedrock:
    models:
      - us.anthropic.claude-sonnet-5
      - us.anthropic.claude-opus-4-8

Supported providers: OpenAI, Azure OpenAI, Anthropic, Amazon Bedrock, Google Gemini, DeepSeek, Qwen, Kimi, MiniMax, Grok (xAI), OpenRouter, TokenDance, Doubao, Tencent Hunyuan/TokenHub, Xiaomi MiMo, GLM (Zhipu), Ollama (local), Lemonade (local LLM / image / TTS / ASR), FunASR (local ASR), and any OpenAI-compatible API.

Amazon Bedrock quick example:

BEDROCK_REGION=us-east-1
BEDROCK_MODELS=us.anthropic.claude-sonnet-5,us.anthropic.claude-opus-4-8
DEFAULT_MODEL=bedrock:us.anthropic.claude-sonnet-5

Bedrock uses AWS environment credentials or the AWS SDK credential provider chain. For temporary credentials, set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN, or use an AWS profile / role available to the runtime.

OpenMAIC supports Lemonade as a local, OpenAI-compatible provider for LLMs, image generation, TTS, and ASR. No API key is required.

Run Lemonade locally, then point OpenMAIC to it:

LEMONADE_BASE_URL=http://localhost:13305/v1
TTS_LEMONADE_BASE_URL=http://localhost:13305/v1
ASR_LEMONADE_BASE_URL=http://localhost:13305/v1
IMAGE_LEMONADE_BASE_URL=http://localhost:13305/v1

OpenMAIC can transcribe locally through FunASR's OpenAI-compatible server. The built-in provider supports SenseVoiceSmall, Paraformer, and Fun-ASR-Nano and requires no API key.

python -m pip install torch torchaudio
python -m pip install "funasr==1.4.0" fastapi uvicorn python-multipart
# Add vLLM for Fun-ASR-Nano on NVIDIA GPUs
python -m pip install vllm
funasr-server --device cuda --model fun-asr-nano

Point OpenMAIC at the server:

ASR_FUNASR_BASE_URL=http://localhost:8000/v1

Use funasr-server --device cpu --model sensevoice for a CPU-only setup. See the FunASR deployment guide for production options.

OpenMAIC can extract timestamped transcripts and prepared video keyframes locally. Install the system ffmpeg package so both ffmpeg and ffprobe are executable on PATH, then configure one server ASR provider (for example FunASR, Lemonade, or OpenAI) using the variables above. The application resolves the executables at extraction time; ffmpeg is not an npm dependency and is not required to start or use OpenMAIC.

If the executables are unavailable, the local extractor is skipped. A configured AliDocMind provider remains available as the cloud extraction path. When neither local ffmpeg extraction nor AliDocMind is available, audio/video materials are marked failed with an actionable setup message instead of hanging or completing with an empty transcript.

OpenAI quick example:

OPENAI_API_KEY=sk-...
DEFAULT_MODEL=openai:gpt-5.5

MiniMax quick examples:

MINIMAX_API_KEY=...
MINIMAX_BASE_URL=https://api.minimaxi.com/anthropic/v1
DEFAULT_MODEL=minimax:MiniMax-M2.7-highspeed

TTS_MINIMAX_API_KEY=...
TTS_MINIMAX_BASE_URL=https://api.minimaxi.com

IMAGE_MINIMAX_API_KEY=...
IMAGE_MINIMAX_BASE_URL=https://api.minimaxi.com

IMAGE_OPENAI_API_KEY=...
IMAGE_OPENAI_BASE_URL=https://api.openai.com/v1

VIDEO_MINIMAX_API_KEY=...
VIDEO_MINIMAX_BASE_URL=https://api.minimaxi.com

Xiaomi MiMo Token Plan quick example:

MIMO_API_KEY=tp-...
MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
DEFAULT_MODEL=xiaomi:mimo-v2.5-pro

Use https://token-plan-sgp.xiaomimimo.com/v1 or https://token-plan-ams.xiaomimimo.com/v1 for the Singapore or Europe Token Plan clusters.

TokenDance quick example (one key for chat, image, video, TTS, and web search):

TOKENDANCE_API_KEY=sk-...
TOKENDANCE_BASE_URL=https://tokendance.space/gateway/v1
DEFAULT_MODEL=tokendance:deepseek-v4.1-flash

IMAGE_SEEDREAM_API_KEY=sk-...
IMAGE_SEEDREAM_BASE_URL=https://tokendance.space/gateway/ark/v3
IMAGE_SEEDREAM_MODELS=seedream-5.0-lite

VIDEO_MINIMAX_API_KEY=sk-...
VIDEO_MINIMAX_BASE_URL=https://tokendance.space/gateway/minimax
VIDEO_MINIMAX_MODELS=minimax-h3

TTS_MINIMAX_API_KEY=sk-...
TTS_MINIMAX_BASE_URL=https://tokendance.space/gateway/minimax
TTS_MINIMAX_MODELS=minimax-speech-2.8-turbo

BOCHA_API_KEY=sk-...
BOCHA_BASE_URL=https://tokendance.space/gateway/bocha

Without touching .env.local, Settings → Token Plan → TokenDance applies the same key to every modality in one step.

GLM (Zhipu) quick examples:

# China (default)
GLM_API_KEY=...
GLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4

# International (z.ai)
GLM_API_KEY=...
GLM_BASE_URL=https://api.z.ai/api/paas/v4

DEFAULT_MODEL=glm:glm-5.1

Recommended setup: OpenMAIC is at its best with every modality turned on — generated illustrations, narration, video clips, and web-grounded research. The least friction is a single key that covers all of them (see the one-key example above), with a fast long-context model such as deepseek-v4.1-flash as the default.

If you want to use MiniMax as the default server model, set DEFAULT_MODEL=minimax:MiniMax-M2.7-highspeed.

pnpm db:up

This starts a separate development PostgreSQL on 127.0.0.1:5432 (set OPENMAIC_DB_PORT to use another port). It is its own Compose project (openmaic-dev-db, shared by every checkout on this machine) with its own container and data volume, so it never restarts or stops the database of a docker compose up stack, and the two do not share data. Then uncomment the local DATABASE_URL line in .env.local:

DATABASE_URL=postgres://openmaic:[email protected]:5432/openmaic

Any other PostgreSQL works too; point DATABASE_URL at it. pnpm db:down stops the container and keeps its data volume.

pnpm dev

Open http://localhost:3000 and start learning! Without a DATABASE_URL the server refuses to start and tells you how to provide one (see Server-backed persistence).

pnpm build && DATABASE_URL=postgres://... pnpm start

To protect your deployment with a site-level password, set ACCESS_CODE in .env.local:

ACCESS_CODE=your-secret-code

Use a long random value — at least 16 characters from a random generator — because this code is the only secret guarding the deployment.

When set, visitors see a password prompt before accessing the app. All API routes are also protected. When unset (the default in .env.example), middleware.ts does not check a credential and every matched route — including the API — is reachable. That is fail-open: an unconfigured deployment is not gated, and there is no second enforcement point.

The code is remembered in a signed token stored in an HTTP-only cookie for 7 days; the lifetime is enforced server-side, so visitors re-verify after it expires. Verification is rate limited only when TRUST_PROXY_HEADERS=true is set: behind a trusted reverse proxy that overwrites x-forwarded-for / x-real-ip, each client gets its own limit of 10 attempts per 60 seconds, and a successful check clears that client's counter. Without a trusted proxy the app cannot attribute requests to a client, so there is no throttle at all — the length and randomness of the code are the protection.

Or manually:

1. Fork this repository
2. Import into Vercel
3. Set environment variables: DATABASE_URL pointing to an external PostgreSQL database (a serverless function cannot run one itself), and at least one LLM API key
4. Deploy

The server refuses to start without DATABASE_URL. Use a connection string your functions can reach from Vercel's network (a managed PostgreSQL service with TLS, or a pooled connection endpoint when your provider offers one). The same applies to any other serverless or container host: provide the database, then deploy.

cp .env.example .env.local
# Edit .env.local with your API keys, then:
docker compose up --build

Open http://localhost:3000. The stack is two containers, the app and PostgreSQL; the app starts once PostgreSQL reports healthy. Courses, generated media and runtime sessions are stored on the server in named volumes (openmaic-postgres, openmaic-data), so they survive docker compose down and rebuilds; docker compose down -v deletes them.

The Compose file is set up as a personal installation:

• One owner. docker-compose.defaults.env turns on single-user mode: every request resolves to one owner, so every browser sees the same course library and publishing works. No anonymous cookie is minted.
• Loopback only. The app is published on 127.0.0.1:3000, so only this machine can reach it. PostgreSQL is not published at all.

To reach it from other machines, protect it first:

1. Set a long random ACCESS_CODE in .env.local (see ACCESS_CODE). This is strongly recommended: without it, anyone who can reach the port is the single owner and shares, edits and can delete the whole library.
2. Set PERSISTENCE_POSTGRES_PASSWORD to a random value of letters and digits before the first start (for an existing volume, see Server-backed persistence).
3. Publish on the network address: OPENMAIC_PUBLISH_ADDRESS=0.0.0.0 docker compose up -d --build.

These Compose-level variables (OPENMAIC_PUBLISH_ADDRESS, OPENMAIC_PORT for the host port, PERSISTENCE_POSTGRES_PASSWORD) come from your shell or a .env file next to docker-compose.yml, not from .env.local. Single-user mode without ACCESS_CODE logs a prominent warning at startup, and the app also warns when it is published beyond loopback with the default PostgreSQL password; neither stops the server. A later first-run setup flow may prompt for an access code; until then, setting ACCESS_CODE is up to you.

Each default in docker-compose.defaults.env can be overridden in .env.local, which Compose reads after it: for example OWNER_SINGLE_USER=false for one anonymous owner per browser (what pnpm dev does), or to use PERSISTENCE_SHARED_OWNER_ID instead, or your own DATABASE_URL for an external database. The bundled postgres service still starts in that case (the app waits for its health check) but is not used; remove it from a copy of the Compose file if you do not want it.

Docker builds support two optional build arguments. Both are empty by default, so the standard command above keeps using the upstream Alpine and npm registries.

• ALPINE_MIRROR is an Alpine mirror hostname without https://.
• NPM_REGISTRY is a complete npm registry URL.

Use public mirror endpoints only. Do not embed usernames, passwords, or access tokens in these build arguments because Docker may record them in image metadata or build provenance.

With Docker Compose:

ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
NPM_REGISTRY=https://registry.npmmirror.com \
docker compose up --build

For a direct image build:

docker build \
  --build-arg ALPINE_MIRROR=mirrors.tuna.tsinghua.edu.cn \
  --build-arg NPM_REGISTRY=https://registry.npmmirror.com \
  -t openmaic:local .

These arguments do not accelerate Docker Hub pulls, including the Dockerfile frontend and the node:22-alpine base image. Configure a Docker daemon registry mirror separately if those pulls are slow. The pnpm store cache is reused by the same BuildKit builder across builds, subject to normal cache garbage collection; the cache only improves performance and is not required for a correct build.

OpenMAIC always stores courses on the server. The Docker deployment runs exactly two containers, the OpenMAIC app and PostgreSQL. The persistence HTTP server is embedded in the app at /api/persistence; there is no standalone persistence service.

DATABASE_URL is required. Without it the server does not start: it prints [boot] Invalid server configuration; the server will not start: DATABASE_URL is not set. ... with the fix and exits with code 1. Outside Compose, build normally and run with a DATABASE_URL:

pnpm build
DATABASE_URL=postgres://openmaic:password@localhost:5432/openmaic pnpm start

For local development, pnpm db:up starts a separate development database (the Compose postgres service definition under its own project and volume, openmaic-dev-db, shared by every checkout on this machine) and publishes it on 127.0.0.1 (port OPENMAIC_DB_PORT, default 5432); the matching DATABASE_URL is commented in .env.example, and pnpm db:down stops it again. Serverless hosts (see Vercel Deployment) point DATABASE_URL at an external PostgreSQL database.

Add your provider API keys to .env.local as usual. Course documents, folders, chat history and learner runtime sessions, and generated media are stored on the server. What stays in the browser is what belongs to the device and can be lost without losing a course: app settings and UI preferences, the playback position and the editor's current scene, the editor's undo history, a local cache of narration and media the server already stores (and bytes a full store refused, kept for a retry), PDF images staged during generation, and TTS voice profiles registered from that browser. Settings → Clear Local Cache clears exactly that and nothing on the server.

Upgrading from a browser-only build. Courses an earlier browser-only build stored in the browser move to the server automatically, with no action and no UI: the first time that browser opens the upgraded app, once the page is idle, a one-way importer copies each course, with its chat, learner runtime, playback position, agent roster, folders and membership, quiz progress and media, to the owner the server resolves for that browser (the anonymous cookie owner by default), and the course appears in the library. This happens once per browser: the server binds the browser to the first owner that asks (POST /api/identity/legacy-import-binding), and a claim carries the binding to the account (an anonymous owner that signs in and is claimed). Every importer request carries the browser's id and is refused (409 LEGACY_IMPORT_NOT_BOUND) for any owner that does not hold the binding, so another owner that later uses the same browser gets nothing imported. The browser copy is left untouched, and Settings → Clear Local Cache does not delete it. A course the server already has for that owner stays as the server has it; one whose id another owner holds is imported under a new id; one deleted on the server is not brought back. The importer records its progress in the browser (with a random browser id and no owner information), so an interrupted import resumes on a later load and nothing is imported twice; problems are logged in the browser console under [legacy-browser-import]. The importer is temporary and will be removed a few releases later.

The server course library and its folders (/api/stages/**, /api/folders/**) serve whether or not the agent runtime (OPENMAIC_AGENT_RUNTIME_ENABLED) is on. GET /api/agent/runtime reports persistence, next to the runtime's own enabled and runtimeEnabled.

Every /api/persistence request is attributed to the owner the owner identity seam resolves — by default the anonymous cookie (400 days, renewed while in use), one owner per browser; in the Compose deployment, the one single-user owner. There is no separate persistence credential:

• Documents. A read is capability-by-id: if the stage meta exists and is not tombstoned, decideDocumentAccess allows it with no owner check (lib/persistence/document-access.ts), so anyone who can reach the endpoint and knows a stage id can read that course. Writes and deletes are owner-checked.
• Runtime sessions (/runtime/*) are partitioned by learner key, and the learner key is the owner id. The browser learns it from GET /api/persistence/learner-key; a request naming any other learner key is refused (403 FORBIDDEN_LEARNER), and another learner's session answers 404. Runtime of a deleted (tombstoned) course reads as absent and takes no new writes. Learner merge and the admin wipes stay refused.
• Assets are allocated in a per-owner partition, so ASSET_QUOTA_BYTES is a per-owner ceiling and only the owner can replace or delete an entry. Reads stay capability-by-id for media a course viewer needs: an owner reads its own entries, and anyone reads another owner's committed entry while a live course of that same owner references it. A course only references (and commits) its owner's own media: naming another owner's asset id in your course records nothing, so it can neither expose their unsaved uploads nor keep their media alive. Entries written before per-owner partitions (the old shared partition) stay readable by id to everyone, and can be replaced or deleted only by an owner who owns every course referencing them; the collector reclaims them as courses stop naming them, as before.

Without a host auth method the owner is only as strong as a cookie (or, in single-user mode, as ACCESS_CODE or the loopback binding): this is suitable for localhost, trusted-network, or single-team deployments. A deployment with its own accounts registers owner auth methods (see Owner identity) and every surface above follows it.

PERSISTENCE_POSTGRES_PASSWORD (default openmaic-dev, for local use only) initializes the PostgreSQL role only when the data directory is empty, and the default DATABASE_URL in docker-compose.defaults.env is built from the same variable without encoding, so use letters and digits only (characters such as @, /, # or ? break the URL; for such a password, set an encoded DATABASE_URL in .env.local instead). Changing it later does not rotate an existing openmaic-postgres volume. For a disposable local database, run docker compose down -v, set the new password, then start again. To preserve data, run docker compose exec postgres psql -U openmaic -d openmaic -c "ALTER ROLE openmaic WITH PASSWORD 'new-password';", then start with PERSISTENCE_POSTGRES_PASSWORD=new-password (or set the matching DATABASE_URL in .env.local).

Assets are reclaimed by an offline collector rather than on a request path. This deployment runs that collector by default, so nothing has to be configured for asset storage to stop growing. A pass runs every ASSET_COLLECTION_INTERVAL_MS (default 15 minutes) and has two levels. It first releases registry entries — an allocation no document claimed before its pending window ran out, and an entry whose last document reference left longer ago than ASSET_COLLECTION_GRACE_MS (default 1 hour) — and then deletes the bytes whose last entry left, after the same grace. The two levels wait in sequence: releasing an entry is what leaves its bytes unreferenced, so the bytes start their own grace only once the entry has served its. The worst case from "the last document stopped naming this" to "the bytes are gone" is therefore two grace periods, not one. That window is the retention a user's deleted media actually gets, so raise it deliberately. Set ASSET_COLLECTION_ENABLED=0 to switch collection off in a process. A horizontally scaled deployment may leave it on in every instance — each row is locked and re-checked before anything goes, so concurrent collectors serialize rather than race — or disable it everywhere and run its own.

The server owns that bookkeeping end to end, and it needs no configuration because it is not optional here: every document write records which assets the document names and commits the allocations it names, which is exactly what the collector reads. A browser never deletes an asset and is never asked to.

Deleting a course releases the assets it was holding. The course id itself is retired permanently rather than removed — that is what keeps a deleted id from being claimed again — but the references it held are withdrawn in the same transaction, so its media stops counting against the quota immediately. The entry is released after one grace period and its bytes after a second, as above. The grace period is the undo: within it the assets are still there.

ASSET_PENDING_TTL_MS (default 24 hours) is how long an allocation stays pending — its bytes are stored, but no document names its id yet. A client stores bytes first and writes the id into the document afterwards, and nothing leases that gap, so the window has to outlive a whole generation pass plus a write-back waiting for the slide it belongs to: media routinely finishes before that slide exists. A day is deliberately generous, because unclaimed bytes cost storage while an expiry that fires early costs a course its media. A value that is not a positive integer stops the server from starting, for the same reason ASSET_QUOTA_BYTES does.

Each owner may hold ASSET_QUOTA_BYTES (default 10 GiB) of live assets — pending-unexpired or still referenced by a document — before further allocations are refused; the store enforces it inside the write transaction, so concurrent uploads cannot race past it. The ceiling is per owner, not per deployment: with the default anonymous-cookie owners a visitor who clears their cookie becomes a new owner with a fresh quota, so bound total storage elsewhere if that matters. Entries from before per-owner partitions keep counting against the old shared partition. Set ASSET_QUOTA_BYTES=0 to opt out and bound storage elsewhere; any spelling of zero does it. A value that is not a non-negative integer is refused when the server starts, rather than replaced by the default, so a mistyped ceiling stops the process instead of quietly running on a limit nobody chose.

The browser never deletes an asset: one nothing references is left to the collector, and nothing on the wire changes when one is committed — a document write does that as a side effect. Replacing or deleting through the endpoint is limited to the owner, as described above.

Asset byte egress is direct by default: the embedded route materializes the bytes in the response body. Setting ASSET_BYTE_EGRESS=redirect opts into indirect egress, under which a byte GET answers with a short-lived signed S3 URL when the byte layer can sign (S3 can; the PostgreSQL byte column cannot and falls back to direct bytes). Two object-store prerequisites make that safe: the bucket must allow this app's origin via CORS and expose Content-Type on the signed response, and the signing identity must hold s3:ListBucket on the bucket so a missing key answers 404 NoSuchKey rather than 403 — a client can only read a reclaimed asset as a miss when the store confirms it by code. The tradeoffs this opts into are specified in the asset HTTP contract.

The embedded endpoint implements the package's RuntimeStore HTTP contract and DocumentStore HTTP contract.

Invalid configuration stops the server. The register() hook of instrumentation.ts refuses to start on:

• a missing DATABASE_URL;
• a malformed ASSET_QUOTA_BYTES, ASSET_PENDING_TTL_MS, OWNER_WRITE_LOCK_WAIT_MS or OWNER_CLAIM_LOCK_WAIT_MS;
• OWNER_CLAIM_TRIGGER set to anything but explicit or auto;
• OWNER_ANONYMOUS_PREMINT that is not a boolean;
• the removed OWNER_AUTHENTICATOR / TRUSTED_PROXY_* variables, when set;
• PERSISTENCE_SHARED_OWNER_ID that is malformed, set without ACCESS_CODE, or set beside an owner auth registration that leaves out sharedTeamAuthMethod(); sharedTeamAuthMethod() registered without the variable, or not as the last method;
• OWNER_SINGLE_USER that is not a boolean, a malformed OWNER_SINGLE_USER_ID or one set while the mode is off, single-user mode beside PERSISTENCE_SHARED_OWNER_ID, or beside a registration that leaves out singleUserAuthMethod(); singleUserAuthMethod() registered without the switch, or not as the last method;
• ASSET_S3_BUCKET set beside a registered asset byte store, or ASSET_BYTE_EGRESS=redirect with a registered byte store that does not declare signsReadUrls: true.

For any of these, the Node.js server prints a single line, [boot] Invalid server configuration; the server will not start: followed by the reason, and exits with code 1 (under next start and the standalone server.js alike), so a supervisor or container runtime sees the failure instead of a process that listens and answers every request with 500. Any other failure during boot, such as a module missing from the build or a host registration call that throws, also exits with code 1, printed as [boot] Server startup failed; the server will not start: with its stack. Warnings, such as the unset ACCESS_CODE notice and the model-routing checks, never stop the server.

Courses, folders, materials, agent sessions and skills are partitioned by an owner id, which the server resolves for every request in one place (lib/server/identity/). Every owner-scoped route and Server Action asks it, once per request; nothing else reads identity cookies or headers.

Resolution asks an ordered list of owner auth methods. Each method looks for one kind of credential and answers exactly one of:

When every method answers not-applicable, the built-in anonymous fallback resolves the request: one owner per browser, anon:<uuid> 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.

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).

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), 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.

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().

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:

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-applic

  (README truncated)